Asegurando la Calidad del Código TypeScript con expect-type

Hola, mi nombre es Misha Koletsky. Soy ingeniero de software y soy el autor de Expect Type, una biblioteca para pruebas a nivel de tipo en TypeScript. Entonces, ¿qué es? Es una biblioteca disponible a través de npm que te permite escribir pruebas para tus tipos. Así que, si estás familiarizado con escribir pruebas para el comportamiento en tiempo de ejecución, esto es muy similar, y será una sintaxis muy familiar para cualquiera que esté familiarizado con la funcionalidad Expect de Jest o VTest, pero esto te permite escribir pruebas para los tipos reales de tu código TypeScript en lugar del comportamiento en tiempo de ejecución o los valores reales.

Esto es útil para asegurarte de que tus tipos son lo que piensas que son, pero también asegura que se mantengan como deseas a medida que pasa el tiempo. Así que, puede ayudarte a protegerte contra colegas o tu futuro yo de cometer un error al retroceder tipos, agregar anys y ese tipo de cosas a medida que tu base de código evoluciona. Esto también es una muy buena manera de mejorar tus propias habilidades en TypeScript. Así que, si quieres aprender más sobre TypeScript y evaluar cómo TypeScript interactúa con tu base de código, esta es una muy buena manera de hacerlo y de documentar cómo TypeScript funciona en tu equipo.

Todo esto viene sin paso de compilación. Así que, no hay ningún CLI extra que necesites ejecutar. No hay ninguna extensión de IDE VS code que necesites instalar o algo por el estilo. Todo aparecerá en cualquier IDE que uses, y los errores, si los hay, aparecerán cuando ejecutes TSC, el CLI de TypeScript, que con suerte ya estás usando si estás usando TypeScript. No hay dependencias, así que no hay bloat que agregue a tus node modules. Si miras el GitHub después de esta charla, verás que son solo un puñado de archivos TypeScript. Hay algunos genéricos complicados en su implementación, pero nada de eso debería ser algo de lo que debas preocuparte como usuario de expect type. No hay una versión de parche multi-megabyte de TypeScript que se envíe con ella. Son solo tipos bastante simples. Y tampoco hay sobrecarga en tiempo de ejecución. Así que, hemos visto algunos equipos usando expect type en su código de producción, de hecho. No tiene que ejecutarse como parte de un conjunto de pruebas.

Así que, si tienes tipos muy, muy complejos, genéricos, inferidos que son muy difíciles de acceder desde otros módulos, incluido el código de prueba, puedes simplemente poner afirmaciones de expect type directamente en tu código de producción, y no hay preocupación de rendimiento porque todas las funciones que vienen con la biblioteca no tienen sobrecarga en tiempo de ejecución. Así que, no necesitas ningún truco especial de compilador para evitar la sobrecarga de rendimiento. Y como se mencionó, tampoco hay dependencias.

Así que, esto es lo que parece el uso básico. La exportación principal es esta función expect type a la que pasarás un valor, y luego básicamente harás afirmaciones sobre ese valor. Así que aquí, estamos diciendo que esperamos que 42 sea un número. Esperamos que hello sea una cadena, lo cual es obviamente algo que esperarías. En la vida real, no probarías valores literales, pero importarías algo, digamos, de tu código de producción, y te asegurarías de que un cierto valor sea un número o una cadena. También puede hacer tipos complejos. Así que, aquí hay un ejemplo apenas más complejo de un pedido de café.

Probablemente queramos ir más allá de simplemente decir que el pedido de café es un objeto. Queremos asegurarnos de que es un objeto de un cierto tipo. Así que aquí, escribimos una afirmación que dice que el pedido de café tiene dos propiedades, una que se llama type, que es una string, y otra que se llama quantity, que es un tipo number.

Hay muchas más características. Así que, prácticamente cada característica que puedas imaginar en TypeScript, cualquier cosa que tenga funcionalidad nativa, puedes probarla con expect type. Así que, una bastante común que hay un ejemplo aquí es que tenemos dos valores, ambos tienen legs, pero tienen otras propiedades que tal vez no son relevantes para esta prueba. Así que, puedes escribir, hemos escrito dos afirmaciones aquí del mismo tipo. Una, nos hemos asegurado de que horse tiene tipo de legs number, y también una table. Pero obviamente, no necesitamos preocuparnos por esas propiedades extra como que una table usualmente no tiene un name y un horse usualmente no tiene un material. Así que, esto es similar a solo para coincidir con el helper de objeto, si estás familiarizado con eso. También se soportan características más avanzadas de TypeScript.

Así que, aquí tenemos una función de type guard donde nos aseguramos de que la entrada a una función es de tipo date. Así que, puedes verificar que la función devuelve un Boolean, pero también puedes verificar que protege entradas de tipo date. Así que, eso es lo que hace esa segunda afirmación allí. Hay muchos ejemplos como este. Hay un helper de asserts similar. Realmente vale la pena explorar la documentación para encontrarlos todos. Y pruebas de tipos genéricos también. Así que, no tienes que pasar un valor a la función expect type, puedes simplemente pasar un tipo genérico que en realidad no existe en tiempo de ejecución en absoluto. Así que, aquí tenemos una magic box que tiene contents y su propiedad locked.

Y aquí lo estamos pasando como un tipo genérico en la función expect type y nos aseguramos de que la propiedad contents tenga tipo number.

Hay muchísimos más, como dije, vale la pena leer la documentación. Hay ejemplos fáciles de entender para prácticamente todo lo que quieras hacer en TypeScript.

Quiero hablar brevemente sobre la integración con marcos de prueba también. Solo depende de TypeScript, por lo que puedes usarlo con Jest o Mocha o Playwright o cualquier marco de prueba que te guste. Pero hay un soporte incorporado para expect type en VTest, del cual obtienes algunas ventajas. Lo usas de la misma manera exacta, pero VTest hará un seguimiento de cuándo has llamado a expect type y lo mapeará a la prueba que está llamando a esa función para que puedas ver errores asociados con nombres de prueba, lo cual puede ser útil una vez que tu suite de pruebas se vuelva grande y más complicada.

Así que esto es algo que vale la pena usar. Si estás usando VTest, puedes exportar la función expect type directamente desde VTest. No necesitas instalar la biblioteca expect type si estás usando VTest.

Algunas mejores prácticas que he recogido de años tanto construyendo como usando expect type de, no lo uses todo el tiempo. Solo prueba cosas que realmente sea útil probar. Y una buena regla general para esto es que las bibliotecas deberían tener pruebas de tipo para asegurarse de que los consumidores de esas bibliotecas puedan usarlas de la manera correcta. Pero las aplicaciones probablemente no deberían. Si estás escribiendo una prueba a nivel de tipo para decir, mi componente React devuelve un nodo React, eso probablemente no sea lo más útil de hacer. No es una regla al 100%, pero básicamente, probablemente no valga la pena el tiempo para probar la mayoría del código de aplicación.

Pero obviamente, las aplicaciones pueden tener funciones de utilidad que tienen propiedades en común con las bibliotecas también. Así que no. Así que toma esto con un grano de sal. Busca casos extremos. Así que el tipo de ayudante toEqual que viste antes puede detectar cualquier propiedad nunca nula, propiedades de solo lectura. Así que eso es algo que es realmente importante verificar en tus pruebas de tipo. Así que ahí es donde resulta útil. Y luego asegúrate de que realmente lo estás ejecutando como parte de tus pipelines de CI. Así que todo lo que necesitas hacer es ejecutar TSC, lo cual deberías estar haciendo de todos modos para tu base de código. Y luego cualquier afirmación de expect type aparecerá como errores en tus pipelines de CI también. Con suerte, los verás antes de que llegue a CI si estás usando un IDE que soporte TypeScript.

Otro consejo es hacer que los genéricos sean específicos. A veces así es como lo expreso. Pero puedes ver un ejemplo aquí. Así que en lugar de probar un tipo genérico directamente, querrás usar un ejemplo del tipo genérico. Así que digamos que eres el autor de una biblioteca llamada Zod, que es una forma de hacer validaciones en tiempo de ejecución con fuerte soporte de TypeScript. En lugar de intentar probar el ayudante z.object, aquí en este ejemplo estamos creando un esquema de persona. Y luego nos aseguramos de que devuelva el tipo que esperarías de ese esquema. Eso tiende a ser una forma mucho mejor de usar expect type que intentar realmente probar una especie de función genérica en bruto.

Mostraré una demostración rápida solo para que puedas ver cómo se ven los errores porque mucho de este código es, puedes ver cómo se ven las afirmaciones, pero realmente quieres ver cómo se ve cuando algo sale mal. Así que dividamos esto en dos. Así que aquí tenemos una afirmación diciendo que esta función add tiene parámetros de tipo number number, lo cual parece una prueba apropiada, pero está fallando. Y si miramos este mensaje de error, podemos ver por qué. Está un poco comprimido en mi pantalla, así que cerremos eso.

Number number doesn't satisfy the constraint zero number one. Y luego hay un poco de arte para leer el mensaje de error, pero básicamente es esa línea inferior la parte importante. Type number is not assignable to expected number, it's the actual string. Así que eso nos dice que algo ha salido mal en el código que escribimos. Oh sí, en nuestra función add, accidentalmente dijimos que estaríamos sumando un número y una cadena. Esto debería ser number.

Y luego deberíamos ver que el error desaparece una vez que las divisiones de pila se actualizan. La segunda afirmación, puedes ver que dice que devuelve un Boolean. Esto es solo para mostrarte otro ejemplo de un mensaje de error y cómo necesitas leerlos. Y esto básicamente dice que expect type of Boolean has of number has no call signatures. Así que puedes ver que es porque obviamente deberíamos estar devolviendo un número en su lugar, y luego el error desaparece.

Ese es solo un ejemplo muy rápido de cómo leer los mensajes de error. Hay un montón más que viene de expect type. Si estás interesado en algunas opciones más avanzadas de cómo puedes probar tus tipos, entonces puedes venir y echar un vistazo a algunas de estas propuestas. Tengo todos los enlaces aquí. Así que está donde esperarías encontrarlo en NPM, en GitHub. Hay documentación para ello en el sitio web de Vitest, y también estoy disponible en X bajo mmcalc. Muchas gracias. Adiós.