Pruebas de Tipos

Proyecto de Ejemplo

GitHub - Probar en línea

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

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

Es importante tener en cuenta que Vitest no ejecuta ni compila estos archivos; solo los analiza estáticamente utilizando el compilador. Debido a esto, no puedes utilizar sentencias dinámicas. En otras palabras, no se admiten nombres de prueba dinámicos ni las APIs test.each, test.runIf, test.skipIf y test.concurrent. Sin embargo, puedes usar otras APIs como test, describe, .only, .skip y .todo.

El uso de flags de la 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('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 }));
});

Cualquier error de tipo que ocurra dentro de un archivo de prueba se tratará como un fallo de prueba, por lo que puedes utilizar cualquier técnica de tipado que desees para probar los tipos de tu proyecto.

Puedes encontrar una lista de los matchers disponibles en la sección de la API.

Interpretación de Errores

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

Cuando los tipos no coinciden, .toEqualTypeOf y .toMatchTypeOf utilizan un tipo auxiliar especial para generar mensajes de error lo más informativos posible. Sin embargo, su interpretación requiere prestar atención a los detalles. Dado que las aserciones se escriben de forma encadenada, el error debe buscarse en el tipo "esperado", no en el tipo "actual" (expect<Actual>().toEqualTypeOf<Expected>()). Esto significa que los errores de tipo pueden resultar confusos, por lo que esta biblioteca genera un tipo MismatchInfo para explicitar 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 será similar a este:

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 comprensible que especifica tanto los tipos "esperados" como los "actuales". En lugar de interpretar la frase Types of property 'a' are incompatible // Type 'string' is not assignable to type "Expected: string, Actual: number" literalmente, simplemente observa el nombre de la propiedad ('a') y el mensaje: Expected: string, Actual: number. Esto te indicará cuál es el problema en la mayoría de los casos. Los tipos extremadamente complejos, por supuesto, requerirán más esfuerzo para depurar y podrían requerir cierta experimentación. Por favor, abre un issue si los mensajes de error son particularmente engañosos.

Los métodos toBe... (como toBeString, toBeNumber, toBeVoid, etc.) fallan porque se resuelven a un tipo no invocable cuando el tipo Actual bajo prueba no coincide. Por ejemplo, el fallo para una aserción como expectTypeOf(1).toBeString() se verá 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 tan útil; el error significativo es la siguiente línea: Type 'ExpectString<number> has no call signatures. Esto significa que se esperaba una cadena, pero se proporcionó un número.

Si TypeScript agregara soporte para los tipos "throw", estos mensajes de error podrían mejorarse significativamente. Hasta entonces, requerirán un análisis cuidadoso.

Objetos "esperados" concretos vs. typeargs

Los mensajes de error para una aserción como la siguiente:

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

Serán menos informativos 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 (typearg) para el estilo .toEqualTypeOf({a: ''}), y esta biblioteca solo puede indicar el error comparándolo con un tipo genérico Mismatch. Por lo tanto, siempre que sea posible, utiliza un argumento de tipo en lugar de un tipo concreto para .toEqualTypeOf y toMatchTypeOf. Si es 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 complicado trabajar con la API expectTypeOf y encontrar los errores, siempre puedes usar la API assertType más sencilla:

const answer = 42;

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

TIP

Cuando utilices la sintaxis @ts-expect-error, es recomendable 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 genere un error ReferenceError.

Esto se considerará correcto, ya que se espera un error, pero la palabra "answer" tiene un error tipográfico, por lo que es un falso positivo:

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

Ejecutar Verificación de Tipos

Desde Vitest 1.0, para habilitar la verificación de tipos, simplemente añade el flag --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.