Construyendo el Conformance Test Suite de Node-API

Hola, mi nombre es Kane, y hoy quiero compartir un proyecto que he estado construyendo en la organización de Node.js, un conjunto de pruebas de conformidad para Node API. Pero primero, unas palabras sobre mí. Mi nombre es Kane, como dije, y soy ingeniero de experiencia de desarrollador en 11labs. Construí experiencias de desarrollador para personas que construyen sobre los agentes de voz y los otros servicios que tenemos. Y antes de eso, mantuve el SDK de Atlas Devices, anteriormente conocido como Realm.js en MongoDB. Soy un orgulloso padre de tres, con sede en Roskill, justo al oeste de Copenhague. También me gusta construir en público, y hago mucho código abierto. Callstack me patrocina para esto en particular, y tengo patrocinios de GitHub abiertos si quieres unirte a ellos. También puedes encontrarme en BlueSky.

Y comencemos con algo con lo que podrías estar familiarizado. Has escrito un complemento nativo de Node.js, quizás. Funciona perfectamente bien en Node.js, y tu CI está en verde, y lo envías. Pero, ¿funciona en Bunn, en Deno? ¿Funciona en React Native, que recientemente también soportó o agregó soporte para Node API a través de Hermes? La respuesta honesta es que probablemente no lo sepas, y ese es el problema que me propuse solucionar.

Permíteme retroceder y explicar cómo llegamos aquí. Permíteme comenzar poniéndonos en la misma página de Node, qué es Node API, y comenzando con lo que no es, porque a menudo se confunde. No son las APIs de tiempo de ejecución de Node.js, cosas como File System, Path, Process. Aunque algunas de estas están potencialmente construidas sobre Node API, ¿qué es entonces? Es una API C para acceder a JavaScript. Es estable en API. Eso significa que puedes compilarlo una vez, y tu complemento una vez, y luego puedes reutilizarlo en nuevas versiones de Node.js. Los encabezados para la API C, se envían en npm. Así que, un paquete, eso es todo lo que necesitas. Y contiene estos archivos de biblioteca en dos capas. Una es la parte específica del motor, y este es el js-native-api.h, creando valores, llamando funciones, gestionando memoria, por ejemplo, y luego la parte específica del tiempo de ejecución, que es más específica de Node.js. APIs de tiempo de ejecución, como buffers, trabajo asíncrono, eventos de ciclo de vida. Originalmente, Node API fue diseñado para abstraer V8 para los internos de Node.js, y básicamente, podrías escribir tu implementación una vez, y luego no tendrías que vincular directamente contra la versión específica de V8. Para otros entornos de ejecución ahora, comenzaron a adoptar esto. BAN y DINO, no necesariamente en ese orden. Y luego más tarde, React Native por Hermes, y estos otros implementadores también. Esto es lo notable.

Y como dije, está dividido en estas dos categorías de APIs. Ya mencioné esto. Y quiero decir, el lado izquierdo, estas son las APIs independientes del motor. Se supone que funcionan en todos los motores JS. Y luego las otras, más específicas del tiempo de ejecución, específicas de Node.js, pueden o no tener soporte dentro de los otros implementadores. Esto también resulta ser un concepto para el conjunto de pruebas de conformidad. Y ahora que sabemos qué es Node API y quién lo está implementando, quiero decirte qué falta.

Así que el repositorio de Node.js ya tiene pruebas para esto. Tienen como 58 carpetas de pruebas probando cada una de las diferentes áreas de características. Pero cuando abres estas pruebas, ves cosas como una llamada require, que es específica de Node.js, el patrón común JS, para la importación de módulos. Y también ves cosas como cargar el complemento usando una llamada require, que no es parte de la especificación oficial, se podría decir, de Node API. Y estas pruebas están completamente vinculadas al tiempo de ejecución de Node.js. La utilidad, el archivo de comentarios que ves aquí, tiene una implementación interna que usa FS y las rutas y cosas así. Así que queremos asegurarnos de ejecutarlas en otros entornos de ejecución.

Puedes ver algunos de los trabajos previos existentes aquí. Puedes ver algunos de los proyectos básicamente copiaron las pruebas de Node.js. Y las consecuencias aquí son que cuando se corrige un error en el repositorio de Node.js, no se propaga automáticamente o si se agrega una nueva prueba, por ejemplo, no se propaga automáticamente y ejercita la implementación de Bonandino. Y esto es un problema porque la aclaración de la especificación, puedes ver que las pruebas están implementando, permanecen aisladas. Y cuando un entorno de ejecución afirma que soporta Node API, no hay una garantía compartida como algo que puedas usar para validar esa afirmación. Y esto es una brecha. Y eso es lo que llena el conjunto de pruebas de conformidad de Node API.

Al introducirlo, la idea aquí desde el problema original, captura la motivación. No estaba planeado. Node API no planeaba convertirse en un estándar de ejecución cruzada, pero lo hizo. Y ahora necesita la infraestructura para estandarizarse. Y básicamente tenerlo en el CTS y la organización de Node.js significa que tiene cierta legitimidad y los entornos de ejecución tienen una verdad compartida para medir. Y también puedes, como autor de estos complementos, ver qué APIs puedes usar en todos los entornos de ejecución.

El CTS tiene cinco objetivos de diseño. Uno es que no queremos ninguna API de tiempo de ejecución de Node.js dentro de las pruebas reales, por lo que básicamente tenemos que usar características estándar del lenguaje. El segundo es que el arnés es personalizable por el implementador. Cuando digo implementar, me refiero a un implementador de Node API como Bondino, React Native, por ejemplo. Y cada entorno de ejecución trae sus propias implementaciones de globales específicos a los que las pruebas pueden acceder. También queremos tener un tercero aquí, el mismo objetivo es que queremos tener una adopción gradual, lo que significa que a medida que estás implementando como un nuevo entorno de ejecución está implementando estas APIs, queremos que puedan hacerlo gradualmente.

Y así no tiene que ser como un todo o nada que tengan que ejecutar. Un cuarto es que queremos que cada uno de los archivos de prueba se ejecute de forma aislada. Así es como lo hacen otras suites de pruebas también. Previene fugas entre las pruebas y hace posible ejecutar toda la suite de pruebas y ver fallos sin que se bloquee el proceso que está ejecutando y organizando la ejecución de las pruebas. El quinto aquí es que queremos publicar en npm. Así puedes obtener fácilmente el paquete y ejecutar tus pruebas sin la molestia de revisar el repositorio. Bien. Así que aquí hay una arquitectura de tres niveles. Puedes ver en verde aquí tenemos el ejecutor de pruebas. Esto es específico para el implementador. En este caso, podría ser Node.js. Y luego tenemos los azules que son implementaciones de un arnés, pero la implementación aquí es específica para el entorno de ejecución. Y luego tenemos la prueba aquí en gris, que es test.js, y luego algo de código de complemento nativo. Y déjame guiarte a través de cada uno de estos en profundidad. Si solo miramos el CTS en el nivel final, puedes ver que tenemos el directorio de pruebas aquí. Ejercitamos el arnés en sí. Así que esto es básicamente para tener una verificación de cordura de que el implementador está proporcionando un arnés en el que podemos confiar.

Luego tenemos la JS native API. Estas son las pruebas del motor de JavaScript. Y luego tenemos el Node API, pruebas más específicas del entorno de ejecución. Los implementadores también pueden traer su propia implementación de arnés, y pueden hacerlo en sus propios repositorios, o también pueden traerla y poner algunos archivos en el CTS para que dependan de ellos. Actualmente, solo tenemos Node.js aquí.

Así que quiero mostrar algunos... Si miramos los niveles aquí, podríamos llamarlos... Primero, tenemos los complementos nativos. Estos son códigos C++ que ejercitan el Node API, y básicamente son llamados, cargados por la función load add-on, y luego el JavaScript está manejando y ejercitando el complemento, que básicamente está llamando al Node API por debajo. Usamos CMake como sistema de construcción principalmente porque es más flexible para nosotros, y Jib también ha sido abandonado por el proyecto Chromium, por lo que no es algo en lo que queramos confiar para el futuro lejano. Y creo que, sí, tenemos algunas funciones auxiliares aquí para definir un complemento, haciendo posible construir en múltiples plataformas.

C2 aquí es el arnés, el arnés proporcionado por el implementador. Ahora mismo, tiene que soportar tres globales. El assert, básicamente simples afirmaciones. Add, perdón, load add-on, que es una función que llamas para cargar un complemento específico para la prueba en tu prueba. En Node.js, usamos una implementación basada en DLOpen, y luego tenemos una utilidad GCUntil que básicamente desencadena la recolección de basura hasta que se cumple una cierta condición, y esto nuevamente es proporcionado por el arnés de prueba y utilizado por la prueba. Y luego tenemos, en este caso, una parte del arnés, el orquestador de Node.js. Y nuevamente, esto es específico para los diferentes implementadores. Pueden proporcionar sus propias formas de cargar pruebas, pero en este caso, importamos los archivos separados que proporcionarán los globales, y luego cargamos el archivo de prueba y lo ejecutamos usando un subproceso.

¿Y por qué usamos un subproceso? Nuevamente, los estados no pueden filtrarse entre las pruebas, y también es crítico para las pruebas de recolección de basura y tiempo de vida de los objetos. Y la recolección de basura global es nueva para cada prueba aquí, y también coincide con lo que vemos en otras suites de pruebas de conformidad. Queremos asegurarnos de que nos mantenemos agnósticos al tiempo de ejecución. Nuevamente, como dije, no queremos que la prueba dependa de las APIs de tiempo de ejecución de Node.js. ¿Y cómo resolvemos eso? Entonces, la técnica uno es que no usamos las llamadas require. No usamos un sistema de módulos específico. Por ahora, básicamente tenemos el archivo de prueba auto-contenido, y lo que necesite para funcionar se inyecta mediante globales de antemano. Así que, como puedes ver, no hay declaraciones de importación aquí, y usamos solo un load add-on para cargar el complemento y afirmar usando estos globales, como dije. Y usamos ESLint para hacer cumplir esto en tiempo de Lint, así que nos aseguramos de que no se cuelen llamadas al sistema de módulos. Y esta es la configuración que usamos para eso, por ejemplo. La técnica dos aquí, la recolección de basura hasta para pruebas de finalización, es básicamente desencadenar la recolección de basura. Así que lo hacemos una y otra vez hasta que se cumple alguna condición. También nos aseguramos de ceder el control usando el set immediate. Cedemos al bucle de eventos, y luego llamamos a esta recolección de basura GCM global que se proporciona porque ejecutamos el proceso con expose GC. Y básicamente, hacemos esto 10 veces en este caso, y luego, si no tiene éxito dentro de eso, entonces tenemos que abandonar. Sí. Entonces, nuevamente, esto es algo específico del implementador. Bondino podría implementar esto de manera diferente. React Native también podría hacerlo. Entonces, nuevamente, esta división en API no es solo una decisión de diseño. También es algo que usamos en la hoja de ruta para cómo migramos cosas. Tenemos este archivo porting MD, que captura el estado actual de la migración de las pruebas. Tenemos algunas pruebas fáciles, que, como puertos directos, no son tan difíciles, y tenemos algunas pruebas medianas que requerirán cambios, adiciones al arnés, y luego tenemos las difíciles que podrían ser más complicadas de realmente portar. ¿Y dónde estamos hoy? El progreso se realiza aquí. Ya tenemos la infraestructura en su lugar, un arnés, sistema de construcción CMake con este soporte específico de plataforma en él. Tenemos una matriz de CI ejecutándose en Mac, Ubuntu, Windows, probando en cuatro versiones diferentes de Node, y tenemos la aplicación de ESLint para asegurarnos de que tenemos el sistema de módulos de Node en uso. Y también publicamos bajo la organización de Node.js en GitHub. Así que, ahora mismo, en el estado actual, 14 pruebas están completamente portadas. Estas son la categoría fácil en las pruebas agnósticas del motor, y esto es aproximadamente la mitad, ¿verdad? Y tenemos otras... Esta es la prueba restante.

Como puedes ver aquí, la mayoría de las pruebas de Node API son medianas o difíciles. Sí. Otro aspecto que se puede mencionar es que algunas de estas Node API o algunas de las otras funciones están marcadas como experimentales en los archivos de encabezado, y eso es actualmente un desafío de diseño que no hemos resuelto. Básicamente, ¿cómo aseguras que algunas de estas podrían ser implementadas por los runtimes, verdad? Podría ser que algunas de las funciones aquí sean create shared array buffer o un post finalizer. Y actualmente, estas se omiten del paquete de archivos de encabezado, por lo que no se compilan por defecto. Y si un runtime quiere ofrecer soporte para algunas de estas, creo que debería ser posible para el CTS ejercitarlo. Y una posible solución aquí es usar algo como un encabezado personalizado que haga declaraciones anticipadas. Y luego tenemos una variante específica, potencialmente CMA y algunas características que tú como implementador puedes proporcionar, como un global de características experimentales con las capacidades de tu implementación.

Y luego las pruebas pueden básicamente verificar aquí y omitir de manera elegante en caso de que el arnés indique que el implementador no soporta una cierta función experimental. Entonces, ¿qué sigue? Creo que hemos completado la fase uno y ahora tenemos dos por delante. La fase dos es tomar las pruebas medianas y difíciles y trasladarlas una P a la vez. Y espero usar botellas de lenguaje para esto. Y luego tenemos la fase tres para que uno y Deno y React Native ejecuten este conjunto en su CI. Eso podría ser increíble. Y luego, potencialmente, un objetivo adicional de integrar esto o integrarlo de alguna manera con el repositorio principal de Node.js para que podamos ejecutar estas pruebas cada vez que hagamos cambios en Node.js. Entonces, ¿te gustaría contribuir? Veo tres formas claras de hacerlo. Una es que necesitamos portar todas las pruebas. Y las fáciles ya están hechas. Lo siento por eso. Pero las siguientes son las medianas y las difíciles. Y puedes elegir una de la migración aquí. Puedes copiar el C y JavaScript de la prueba existente y eliminar o manipular el– eliminar las APIs de tiempo de ejecución de Node.js para hacerlo agnóstico. Luego también puedes agregar tu runtime al arnés. Así que si eres un implementador de una implementación de Node API, puedes proporcionar– limpiar tu directorio dentro del directorio de implementadores e implementar load add-on assert y gguntil. Y entonces estarás listo para comenzar.

Y si solo tienes curiosidad sobre esto, agradecería una estrella o un seguimiento en el repositorio de GitHub. Esto te ayuda a mantenerte actualizado. Eso es todo por ahora. Muchas gracias por tu tiempo. Es un bien escaso en estos días.