Testování typů

Ukázkový projekt

GitHub - Hrát online

Vitest umožňuje psát testy pro vaše typy pomocí syntaxe expectTypeOf nebo assertType. Ve výchozím nastavení jsou všechny testy v souborech *.test-d.ts považovány za typové testy, ale toto chování můžete změnit pomocí konfigurační možnosti typecheck.include.

Vitest interně spouští tsc nebo vue-tsc v závislosti na vaší konfiguraci a analyzuje výsledky. Vitest také zobrazí typové chyby ve vašem zdrojovém kódu, pokud je nalezne. Tuto funkci můžete zakázat pomocí konfigurační možnosti typecheck.ignoreSourceErrors.

Upozorňujeme, že Vitest tyto soubory nespouští ani nekompiluje. Jsou pouze staticky analyzovány kompilátorem, a proto nemůžete používat dynamické konstrukce. To znamená, že nemůžete používat dynamické názvy testů a API test.each, test.runIf, test.skipIf, test.concurrent. Můžete ale používat jiná API, například test, describe, .only, .skip a .todo.

CLI příznaky, jako --allowOnly a -t, jsou pro kontrolu typů také podporovány.

import { assertType, expectTypeOf } from 'vitest';
import { mount } from './mount.js';

test('my types work properly', () => {
  expectTypeOf(mount).toBeFunction();
  expectTypeOf(mount).parameter(0).toMatchTypeOf<{ name: string }>();

  // @ts-expect-error name is a string
  assertType(mount({ name: 42 }));
});

Jakákoli typová chyba, která se objeví uvnitř testovacího souboru, bude považována za chybu testu. Můžete tedy použít libovolné typové triky k testování typů vašeho projektu.

Seznam dostupných matcherů naleznete v sekci API.

Interpretace chyb

Pokud používáte API expectTypeOf, prostudujte si dokumentaci expect-type o chybových hlášeních.

Pokud se typy neshodují, .toEqualTypeOf a .toMatchTypeOf používají speciální pomocný typ k vytváření co nejužitečnějších chybových zpráv. K jejich pochopení je ale potřeba jistá nuance. Protože jsou tvrzení psána "řetězově", chyba by měla být na "očekávaném" typu, nikoli na "skutečném" typu (expect<Actual>().toEqualTypeOf<Expected>()). To znamená, že typové chyby mohou být trochu matoucí. Proto tato knihovna vytváří typ MismatchInfo, aby se pokusila explicitně uvést, co se očekává. Například:

expectTypeOf({ a: 1 }).toEqualTypeOf<{ a: string }>();

Toto tvrzení selže, protože {a: 1} má typ {a: number} a ne {a: string}. Chybová zpráva v tomto případě bude vypadat přibližně takto:

test/test.ts:999:999 - error TS2344: Type '{ a: string; }' does not satisfy the constraint '{ a: \\"Expected: string, Actual: number\\"; }'.
  Types of property 'a' are incompatible.
    Type 'string' is not assignable to type '\\"Expected: string, Actual: number\\"'.

999 expectTypeOf({a: 1}).toEqualTypeOf<{a: string}>()

Všimněte si, že hlášené typové omezení je zpráva čitelná pro člověka, která specifikuje jak "očekávaný", tak "skutečný" typ. Neměli byste brát větu Types of property 'a' are incompatible // Type 'string' is not assignable to type "Expected: string, Actual: number" doslova. Stačí se podívat na název vlastnosti ('a') a zprávu: Expected: string, Actual: number. To vám ve většině případů řekne, co je špatně. Extrémně složité typy budou samozřejmě vyžadovat více úsilí k ladění a mohou vyžadovat určité experimentování. Pokud jsou chybové zprávy skutečně zavádějící, vytvořte prosím issue.

Metody toBe... (jako toBeString, toBeNumber, toBeVoid atd.) selžou tím, že se vyřeší na nevolatelný typ, pokud se Actual typ v testu neshoduje. Například selhání pro tvrzení jako expectTypeOf(1).toBeString() bude vypadat přibližně takto:

test/test.ts:999:999 - error TS2349: This expression is not callable.
  Type 'ExpectString<number>' has no call signatures.

999 expectTypeOf(1).toBeString()
                    ~~~~~~~~~~

Část This expression is not callable není příliš užitečná. Smysluplná chyba je na dalším řádku: Type 'ExpectString<number> has no call signatures. To v podstatě znamená, že jste předali číslo, ale tvrdili jste, že by to měl být řetězec.

Pokud by TypeScript přidal podporu pro "throw" types, tyto chybové zprávy by se daly výrazně vylepšit. Do té doby bude potřeba se na ně trochu zamračit.

Konkrétní objekty vs. typové argumenty

Chybové zprávy pro tvrzení, jako je toto:

expectTypeOf({ a: 1 }).toEqualTypeOf({ a: '' });

Budou méně užitečné než pro tvrzení, jako je toto:

expectTypeOf({ a: 1 }).toEqualTypeOf<{ a: string }>();

Je to proto, že kompilátor TypeScript potřebuje odvodit typový argument pro styl .toEqualTypeOf({a: ''}) a tato knihovna jej může označit jako selhání pouze porovnáním s obecným typem Mismatch. Proto, pokud je to možné, použijte pro .toEqualTypeOf a toMatchTypeOf raději typový argument než konkrétní typ. Pokud je pohodlnější porovnat dva konkrétní typy, můžete použít typeof:

const one = valueFromFunctionOne({ some: { complex: inputs } });
const two = valueFromFunctionTwo({ some: { other: inputs } });

expectTypeOf(one).toEqualTypeOf<typeof two>();

Pokud je pro vás práce s API expectTypeOf obtížná a máte problémy se zjišťováním chyb, můžete vždy použít jednodušší API assertType:

const answer = 42;

assertType<number>(answer);
// @ts-expect-error answer is not a string
assertType<string>(answer);

TIP

Při použití syntaxe @ts-expect-error se možná budete chtít ujistit, že jste neudělali překlep. Můžete to udělat zahrnutím souborů s typy do možnosti konfigurace test.include, takže Vitest tyto testy také skutečně spustí a selže s ReferenceError.

Toto projde, protože se očekává chyba, ale slovo "answer" má překlep, takže se jedná o falešně pozitivní výsledek:

// @ts-expect-error answer is not a string
assertType<string>(answr); //

Spuštění kontroly typů

Od verze Vitest 1.0 stačí pro povolení kontroly typů přidat příznak --typecheck do příkazu Vitest ve vašem package.json:

{
  "scripts": {
    "test": "vitest --typecheck"
  }
}

Nyní můžete spustit kontrolu typů:

npm

npm run test

yarn

yarn test

pnpm

pnpm run test

bun

bun test

Vitest používá tsc --noEmit nebo vue-tsc --noEmit v závislosti na vaší konfiguraci, takže můžete tyto skripty odstranit z vašeho pracovního postupu.