La referencia de beyond test

Alcance#

beyond test de la línea de comandos de Beyond, Node.js 22.21.1 o posterior, solo objetivos Node. Se ejecutó el 2026-09-22 con el grupo de aceptación testing de la línea de comandos contra una instalación recién construida; la cadena de herramientas no está publicada en un registro público.

Línea de comandos#

beyond test [<path> ...] [--workspace <directory>] [--coverage] [--name <pattern>] [--reporter <name>] [-- <node arguments>]

--coverage, --name y --reporter pertenecen a test; dárselos a run es un error de uso.

Recolección#

Un archivo de prueba se llama <name>.test.ts, .test.mts, .test.js o .test.mjs. Los directorios se recorren recursivamente; node_modules y los directorios ocultos (un nombre que empieza con .) nunca se recorren. La lista se ordena, así que dos ejecuciones de un workspace recolectan los mismos archivos en el mismo orden, y se imprime en la salida de error antes de la ejecución.

La barrera de compilación#

Antes de ejecutar nada, el servicio de desarrollo compila todos los módulos públicos del workspace. Cuando uno no compila, no se ejecuta nada y cada diagnóstico se reporta ubicado en la fuente, como <file>:<line>:<column> <CODE>: <message>:

beyond: error: "@qa/shared/text" does not build (BUILD_FAILED)
beyond: error: shared/text/decorate.ts:1:50 TRANSPILE_ERROR: Module "@qa/shared/text": decorate.ts (1:50): Expression expected.
beyond: error: nothing was run: correct the sources and run the tests again

Nunca se sirve un artefacto anterior en lugar de un módulo que no compila.

Los procesos de prueba#

El runner de Node ejecuta cada archivo en un proceso propio. Cada proceso recibe:

Un archivo de prueba es TypeScript o JavaScript; Node elimina los tipos por sí mismo. Un paquete cuyas pruebas son archivos .ts declara "type": "module" en su package.json, o las nombra .mts; de lo contrario Node advierte que tuvo que adivinar el formato del archivo.

Importaciones#

Una prueba importa un módulo público por su especificador bare (@qa/shared/text), resuelto a través de la sesión del servicio de desarrollo a la salida de desarrollo para Node, el mismo artefacto que beyond run ejecuta. Los archivos internos de un módulo no son importables. Los módulos integrados de Node y los paquetes instalados se resuelven como en cualquier módulo.

Mocks de módulos#

mock.module(specifier, { namedExports, defaultExport, cache }) de node:test reemplaza un módulo público, un módulo integrado o un paquete instalado para el archivo de prueba y para todos los módulos que lo importan, cuando se registra antes de importar el módulo bajo prueba:

mock.module('@qa/shared/text', { namedExports: { greet: (name: string) => `mocked ${name}` } });
const { main } = await import('@qa/app/main');

Un mock dura lo que dura el archivo; cada archivo se ejecuta en su propio proceso. Los archivos internos no se pueden simular.

Cobertura#

--coverage agrega --experimental-test-coverage con las exclusiones **/*.test.* y **/node_modules/**, y Node imprime su reporte reasignado a las fuentes TypeScript del workspace, cada una con su directorio. El conteo de funciones de un archivo incluye toda función que nunca fue llamada; las líneas sin cubrir incluyen el cuerpo de tal función solo cuando tiene líneas propias. --reporter lcov escribe los mismos datos en formato LCOV.

Identidades de archivo#

Los módulos entregados por el servicio se identifican en un proceso de prueba con una ruta file: bajo .beyond/modules del workspace, <host>_<port>/m/<package>@<version>/modules/<subpath>.mjs, un archivo marcador escrito una sola vez; el código viene del servicio, con su mapa de fuentes inline. Esto es lo que hace funcionar la cobertura y los mocks de módulos, y es lo que import.meta.url de un módulo servido muestra en una prueba. beyond run nunca lo usa. Agrega .beyond/ al archivo de ignorados del proyecto.

Archivos de prueba y el compilador#

Un procesador de un módulo deja fuera de sus entradas <name>.test.<ext>, <name>.spec.<ext> y todo lo que hay bajo un directorio __tests__ o __fixtures__, así que un archivo de prueba junto a las fuentes no cambia ni el artefacto del módulo ni su hash. Un manifiesto de módulo que establece "tests": "included" toma esos archivos como entradas; requiere que el paquete declare dónde están sus manifiestos ("beyond": { "modules": "." }).

El servidor de desarrollo#

El comando reutiliza el servidor en ejecución del workspace o inicia uno, se conecta a él mientras dura la ejecución y se desconecta al final. Un servidor iniciado por beyond test termina poco después de que su último cliente se desconecta; uno iniciado por beyond run se usa y sobrevive; dos ejecuciones simultáneas comparten un servidor.

Códigos de salida#