The beyond test reference

Scope#

beyond test of the Beyond command line, Node.js 22.21.1 or later, Node targets only. It was executed on 2026-09-22 by the testing acceptance group of the command line against a freshly built installation; the toolchain is not published in a public registry.

Command line#

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

--coverage, --name and --reporter belong to test; giving them to run is a usage error.

Collection#

A test file is named <name>.test.ts, .test.mts, .test.js or .test.mjs. Directories are walked recursively; node_modules and hidden directories (a name starting with .) are never walked. The list is sorted, so two runs of one workspace collect the same files in the same order, and it is printed on the standard error before the run.

The build gate#

Before anything runs, the development service builds every public module of the workspace. When one does not build, nothing runs and each diagnostic is reported located in the source, as <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

An older artifact is never served in place of a module that does not build.

The test processes#

Node's runner executes each file in a process of its own. Every process receives:

A test file is TypeScript or JavaScript; Node strips the types itself. A package whose tests are .ts files declares "type": "module" in its package.json, or names them .mts; otherwise Node warns that it had to guess the format of the file.

Imports#

A test imports a public module by its bare specifier (@qa/shared/text), resolved through the session of the development service to the Node development output, the same artifact beyond run executes. Internal files of a module are not importable. Node built-ins and installed packages resolve as in any module.

Module mocks#

mock.module(specifier, { namedExports, defaultExport, cache }) of node:test replaces a public module, a built-in or an installed package for the test file and for every module that imports it, when it is registered before the module under test is imported:

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

A mock lasts for the file; each file runs in its own process. Internal files cannot be mocked.

Coverage#

--coverage adds --experimental-test-coverage with the exclusions **/*.test.* and **/node_modules/**, and Node prints its report remapped to the TypeScript sources of the workspace, each with its directory. The function count of a file includes every function that was never called; the uncovered lines include the body of such a function only when it has lines of its own. --reporter lcov writes the same data in LCOV form.

File identities#

Modules delivered by the service are identified in a test process by a file: path under .beyond/modules of the workspace, <host>_<port>/m/<package>@<version>/modules/<subpath>.mjs, a placeholder file written once; the code comes from the service, with its source map inline. This is what makes coverage and module mocks work, and it is what import.meta.url of a served module shows in a test. beyond run never uses it. Add .beyond/ to the ignore file of the project.

Test files and the compiler#

A processor of a module leaves out of its inputs <name>.test.<ext>, <name>.spec.<ext> and everything under a __tests__ or __fixtures__ directory, so a test file beside the sources changes neither the artifact of the module nor its hash. A module manifest that sets "tests": "included" takes those files as inputs; it requires the package to declare where its manifests are ("beyond": { "modules": "." }).

The development server#

The command reuses the running server of the workspace or starts one, attaches to it for the duration of the run and detaches at the end. A server started by beyond test ends shortly after its last client detaches; one started by beyond run is used and survives; two simultaneous runs share one server.

Exit codes#