Testando Tipos

Projeto de Exemplo

GitHub - Jogar Online

O Vitest permite escrever testes para seus tipos, usando as sintaxes expectTypeOf ou assertType. Por padrão, todos os testes em arquivos *.test-d.ts são considerados testes de tipo, mas isso pode ser alterado com a opção de configuração typecheck.include.

Internamente, o Vitest executa tsc ou vue-tsc, dependendo da sua configuração, e analisa os resultados. O Vitest também exibirá erros de tipo em seu código-fonte, se encontrar algum. Você pode desativá-lo com a opção de configuração typecheck.ignoreSourceErrors.

Lembre-se de que o Vitest não executa ou compila esses arquivos; eles são apenas analisados estaticamente pelo compilador. Por causa disso, não é possível usar declarações dinâmicas. Ou seja, você não pode usar nomes de teste dinâmicos e APIs como test.each, test.runIf e test.skipIf, test.concurrent. No entanto, é possível usar outras APIs, como test, describe, .only, .skip e .todo.

Flags da CLI como --allowOnly e -t também são suportadas na verificação de tipos.

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 }));
});

Qualquer erro de tipo gerado dentro de um arquivo de teste será tratado como um erro de teste. Portanto, você pode usar qualquer artifício de tipagem que quiser para testar os tipos do seu projeto.

Você pode encontrar uma lista dos matchers disponíveis na seção API.

Lendo Erros

Se você estiver usando a API expectTypeOf, consulte a documentação expect-type em suas mensagens de erro.

Quando os tipos não correspondem, .toEqualTypeOf e .toMatchTypeOf usam um tipo auxiliar especial para produzir mensagens de erro que sejam o mais claras possível. Mas há uma sutileza em entendê-las. Como as asserções são escritas de forma "fluente", a falha deve ocorrer no tipo "esperado", não no tipo "real" (expect<Actual>().toEqualTypeOf<Expected>()). Isso significa que os erros de tipo podem ser um pouco confusos; portanto, esta biblioteca produz um tipo MismatchInfo para tentar explicitar a expectativa. Por exemplo:

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

É uma asserção que falhará, já que {a: 1} tem o tipo {a: number} e não {a: string}. A mensagem de erro neste caso será algo como isto:

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}>()

Note que a restrição de tipo reportada é uma mensagem legível, especificando os tipos "esperado" e "real". Em vez de interpretar a frase Types of property 'a' are incompatible // Type 'string' is not assignable to type "Expected: string, Actual: number" literalmente, observe o nome da propriedade ('a') e a mensagem: Expected: string, Actual: number. Isso indicará o problema na maioria dos casos. Tipos extremamente complexos, é claro, exigirão mais esforço para depurar e podem exigir alguma experimentação. Por favor, abra uma issue caso as mensagens de erro sejam enganosas.

Os métodos toBe... (como toBeString, toBeNumber, toBeVoid etc.) falham ao resolver para um tipo não chamável quando o tipo Actual em teste não corresponde. Por exemplo, a falha para uma asserção como expectTypeOf(1).toBeString() será algo como isto:

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

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

A parte This expression is not callable não é muito informativa - o erro significativo é a próxima linha, Type 'ExpectString<number> has no call signatures. Isso essencialmente significa que você passou um número, mas afirmou que deveria ser uma string.

Se o TypeScript adicionasse suporte para tipos "throw", essas mensagens de erro poderiam ser significativamente aprimoradas. Até lá, será necessário um certo esforço para compreendê-las.

Objetos "esperados" concretos vs typeargs

Mensagens de erro para uma asserção como esta:

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

Será menos útil do que para uma asserção como esta:

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

Isso acontece porque o compilador TypeScript precisa inferir o typearg para o estilo .toEqualTypeOf({a: ''}), e esta biblioteca só pode marcá-lo como uma falha, comparando-o com um tipo Mismatch genérico. Portanto, quando possível, use um typearg em vez de um tipo concreto para .toEqualTypeOf e toMatchTypeOf. Se for muito mais conveniente comparar dois tipos concretos, você pode usar typeof:

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

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

Caso tenha dificuldade em trabalhar com a API expectTypeOf e identificar erros, você sempre pode usar a API assertType mais simples:

const answer = 42;

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

TIP

Ao usar a sintaxe @ts-expect-error, é recomendável que você se certifique de que não cometeu um erro de digitação. Você pode fazer isso incluindo seus arquivos de tipo na opção de configuração test.include, para que o Vitest também execute esses testes e apresente falha com ReferenceError.

Este teste passará, porque espera um erro, mas a palavra "answer" tem um erro de digitação, então é um falso positivo:

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

Executar Typechecking

A partir do Vitest 1.0, para habilitar o typechecking, basta incluir a flag --typecheck ao seu comando Vitest em package.json:

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

Agora é possível executar a verificação de tipos:

npm

npm run test

yarn

yarn test

pnpm

pnpm run test

bun

bun test

O Vitest usa tsc --noEmit ou vue-tsc --noEmit, dependendo da sua configuração. Portanto, você pode remover esses scripts do seu pipeline.