run

History

run(options?): TestsStream

Attributes

options:Object

Configuration options for running tests. The following properties are supported:

concurrency?:number | boolean

If a number is provided, then that many test processes would run in parallel, where each process corresponds to one test file. If true, it would run os.availableParallelism() - 1 test files in parallel. If false, it would only run one test file at a time. Default: false.

cwd?:string

Specifies the current working directory to be used by the test runner. Serves as the base path for resolving files as if running tests from the command line from that directory. Default: process.cwd().

files?:Array

An array containing the list of files to run. Default: Same as running tests from the command line.

forceExit?:boolean

Configures the test runner to exit the process once all known tests have finished executing even if the event loop would otherwise remain active. Default: false.

globPatterns?:Array

An array containing the list of glob patterns to match test files. This option cannot be used together with files. Default: Same as running tests from the command line.

inspectPort?:number | Function

Sets inspector port of test child process. This can be a number, or a function that takes no arguments and returns a number. If a nullish value is provided, each process gets its own port, incremented from the primary's process.debugPort. This option is ignored if the isolation option is set to 'none' as no child processes are spawned. Default: undefined.

isolation?:string

Configures the type of test isolation. If set to 'process', each test file is run in a separate child process. If set to 'none', all test files run in the current process. Default: 'process'.

only:boolean

If truthy, the test context will only run tests that have the only option set

setup?:Function

A function that accepts the TestsStream instance and can be used to setup listeners before any tests are run. Default: undefined.

execArgv?:Array

An array of CLI flags to pass to the node executable when spawning the subprocesses. This option has no effect when isolation is 'none'. Default: []

argv?:Array

An array of CLI flags to pass to each test file when spawning the subprocesses. This option has no effect when isolation is 'none'. Default: [].

signal:AbortSignal

Allows aborting an in-progress test execution.

testNamePatterns?:string | RegExp | Array

A String, RegExp or a RegExp Array, that can be used to only run tests whose name matches the provided pattern. Test name patterns are interpreted as JavaScript regular expressions. For each test that is executed, any corresponding test hooks, such as beforeEach(), are also run. Default: undefined.

testSkipPatterns?:string | RegExp | Array

A String, RegExp or a RegExp Array, that can be used to exclude running tests whose name matches the provided pattern. Test name patterns are interpreted as JavaScript regular expressions. For each test that is executed, any corresponding test hooks, such as beforeEach(), are also run. Default: undefined.

testTagFilters?:string | string[]

A boolean expression, or an array of boolean expressions, used to filter tests by their declared tags. Multiple expressions compose by AND. Equivalent to passing --experimental-test-tag-filter on the command line. See Test tags. Default: undefined.

timeout?:number

A number of milliseconds the test execution will fail after. If unspecified, subtests inherit this value from their parent. Default: Infinity.

watch?:boolean

Whether to run in watch mode or not. Default: false.

shard?:Object

Running tests in a specific shard. Default: undefined.

index:number

is a positive integer between 1 and <total> that specifies the index of the shard to run. This option is required.

total:number

is a positive integer that specifies the total number of shards to split the test files to. This option is required.

randomize?:boolean

Randomize execution order for test files and queued tests. This option is not supported with watch: true. Default: false.

randomSeed?:number

Seed used when randomizing execution order. If this option is set, runs can replay the same randomized order deterministically, and setting this option also enables randomization. The value must be an integer between 0 and 4294967295. Default: undefined.

rerunFailuresFilePath?:string

A file path where the test runner will store the state of the tests to allow rerunning only the failed tests on a next run. see [Rerunning failed tests][] for more information. Default: undefined.

coverage?:boolean

enable code coverage collection. Default: false.

coverageExcludeGlobs?:string | Array

Excludes specific files from code coverage using a glob pattern, which can match both absolute and relative file paths. This property is only applicable when coverage was set to true. If both coverageExcludeGlobs and coverageIncludeGlobs are provided, files must meet both criteria to be included in the coverage report. Default: undefined.

coverageIncludeGlobs?:string | Array

Includes specific files in code coverage using a glob pattern, which can match both absolute and relative file paths. This property is only applicable when coverage was set to true. If both coverageExcludeGlobs and coverageIncludeGlobs are provided, files must meet both criteria to be included in the coverage report. Default: undefined.

coverageIncludeAll?:boolean

Includes source files that were never loaded by the test run in the coverage report, where they are reported as having zero coverage. Candidate files are searched for in cwd, and are subject to the same coverageIncludeGlobs and coverageExcludeGlobs filtering as the rest of the report. This property is only applicable when coverage was set to true. Default: false.

lineCoverage?:number

Require a minimum percent of covered lines. If code coverage does not reach the threshold specified, the process will exit with code 1. Default: 0.

branchCoverage?:number

Require a minimum percent of covered branches. If code coverage does not reach the threshold specified, the process will exit with code 1. Default: 0.

functionCoverage?:number

Require a minimum percent of covered functions. If code coverage does not reach the threshold specified, the process will exit with code 1. Default: 0.

env?:Object

Specify environment variables to be passed along to the test process. This option is not compatible with isolation='none'. These variables will override those from the main process, and are not merged with process.env. Default: process.env.

Returns:TestsStream

Note: shard is used to horizontally parallelize test running across machines or processes, ideal for large-scale executions across varied environments. It's incompatible with watch mode, tailored for rapid code iteration by automatically rerunning tests on file changes.

import { tap } from 'node:test/reporters';
import { run } from 'node:test';
import process from 'node:process';
import path from 'node:path';

run({ files: [path.resolve('./tests/test.js')] })
 .on('test:fail', () => {
   process.exitCode = 1;
 })
 .compose(tap)
 .pipe(process.stdout);

JavaScript

const { tap } = require('node:test/reporters');
const { run } = require('node:test');
const path = require('node:path');

run({ files: [path.resolve('./tests/test.js')] })
 .on('test:fail', () => {
   process.exitCode = 1;
 })
 .compose(tap)
 .pipe(process.stdout);

JavaScript