Pruebas de Tipado

Proyecto de Ejemplo

GitHub - Probar en Línea

Vitest te permite escribir pruebas para tus tipos utilizando las sintaxis expectTypeOf o assertType. Por defecto, todos los archivos *.test-d.ts se consideran pruebas de tipo, pero puedes modificar esta configuración con la opción typecheck.include.

Internamente, Vitest invoca a tsc o vue-tsc (según tu configuración) y analiza sus resultados. Vitest también mostrará los errores de tipo encontrados en tu código fuente. Puedes deshabilitar esta funcionalidad con la opción de configuración typecheck.ignoreSourceErrors.

Es importante tener en cuenta que Vitest no ejecuta estos archivos; solo son analizados estáticamente por el compilador. Esto implica que si utilizas nombres dinámicos, test.each o test.for, el nombre de la prueba no se evaluará, sino que se mostrará literalmente.

WARNING

Antes de Vitest 2.1, la opción typecheck.include sobrescribía el patrón include, lo que significaba que tus pruebas en tiempo de ejecución no se ejecutaban; solo se verificaban los tipos.

A partir de Vitest 2.1, si tus patrones include y typecheck.include se superponen, Vitest reportará las pruebas de tipo y las pruebas en tiempo de ejecución como entradas separadas.

El uso de opciones de línea de comandos (CLI), como --allowOnly y -t, también es compatible para la verificación de tipos.

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

test('mis tipos funcionan como se espera', () => {
  expectTypeOf(mount).toBeFunction();
  expectTypeOf(mount).parameter(0).toMatchTypeOf<{ name: string }>();

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

Cualquier error de tipo que se active dentro de un archivo de prueba será tratado como un error de prueba. Esto te permite utilizar cualquier técnica de tipado que desees para probar los tipos de tu proyecto.

Puedes consultar una lista de posibles comparadores en la sección de API.

Lectura de Errores

Si estás utilizando la API expectTypeOf, consulta la documentación de expect-type sobre sus mensajes de error.

Cuando los tipos no coinciden, .toEqualTypeOf y .toMatchTypeOf emplean un tipo auxiliar especial para generar mensajes de error lo más útiles posible. Sin embargo, su interpretación tiene un matiz. Dado que las aserciones se escriben de forma encadenada, el fallo debe residir en el tipo "esperado", no en el tipo "real" (expect<Actual>().toEqualTypeOf<Expected>()). Esto puede hacer que los errores de tipo sean un poco confusos, por lo que esta biblioteca produce un tipo MismatchInfo para intentar hacer explícita la expectativa. Por ejemplo:

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

Esta aserción fallará, ya que {a: 1} tiene el tipo {a: number} y no {a: string}. El mensaje de error en este caso dirá algo como esto:

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

Observa que la restricción de tipo reportada es un mensaje legible que especifica tanto los tipos "esperado" como "real". En lugar de tomar la frase Types of property 'a' are incompatible // Type 'string' is not assignable to type "Expected: string, Actual: number" literalmente, concéntrate solo en el nombre de la propiedad ('a') y el mensaje: Expected: string, Actual: number. Esto te indicará el problema en la mayoría de los casos. Los tipos extremadamente complejos, por supuesto, requerirán más esfuerzo para depurar y pueden necesitar algo de experimentación. Por favor, abre una incidencia si los mensajes de error son realmente engañosos.

Los métodos toBe... (como toBeString, toBeNumber, toBeVoid, etc.) fallan al resolverse a un tipo que no se puede invocar cuando el tipo Actual bajo prueba no coincide. Por ejemplo, el fallo de una aserción como expectTypeOf(1).toBeString() se verá algo así:

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

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

La parte This expression is not callable no es muy útil; el error significativo es la siguiente línea: Type 'ExpectString<number>' has no call signatures. Esto esencialmente significa que pasaste un número pero afirmaste que debería ser una cadena.

Si TypeScript añadiera soporte para tipos "throw", estos mensajes de error podrían mejorarse significativamente. Hasta entonces, requerirán un cierto esfuerzo de interpretación.

Objetos "esperados" concretos vs. argumentos de tipo

Los mensajes de error para una aserción como esta:

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

Serán menos útiles que para una aserción como esta:

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

Esto ocurre porque el compilador de TypeScript necesita inferir el argumento de tipo para el estilo .toEqualTypeOf({a: ''}), y esta biblioteca solo puede marcarlo como un fallo comparándolo con un tipo Mismatch genérico. Por lo tanto, siempre que sea posible, utiliza un argumento de tipo en lugar de un tipo concreto para .toEqualTypeOf y toMatchTypeOf. Si resulta mucho más conveniente comparar dos tipos concretos, puedes usar typeof:

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

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

Si te resulta difícil trabajar con la API expectTypeOf y descifrar errores, siempre puedes usar la API assertType más simple:

const answer = 42;

assertType<number>(answer);
// @ts-expect-error answer no es un string
assertType<string>(answer);

TIP

Al usar la sintaxis @ts-expect-error, es posible que quieras asegurarte de no haber cometido un error tipográfico. Puedes hacerlo incluyendo tus archivos de tipo en la opción de configuración test.include, para que Vitest también ejecute estas pruebas y falle con un ReferenceError.

Esto pasará porque se espera un error. Sin embargo, la palabra "answer" tiene un error tipográfico, lo que resulta en un falso positivo:

// @ts-expect-error answer no es un string
assertType<string>(answr);

Ejecutar Verificación de Tipos

Para habilitar la verificación de tipos, simplemente añade la bandera --typecheck a tu comando Vitest en package.json:

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

Ahora puedes ejecutar la verificación de tipos:

npm

npm run test

yarn

yarn test

pnpm

pnpm run test

bun

bun test

Vitest utiliza tsc --noEmit o vue-tsc --noEmit, dependiendo de tu configuración, por lo que puedes eliminar estos scripts de tu flujo de trabajo.