});

The test runner supports persisting the state of the run to a file, allowing

the test runner to rerun failed tests without having to re-run the entire test suite.

Use the [`--test-rerun-failures`][] command-line option to specify a file path where the

state of the run is stored. if the state file does not exist, the test runner will

create it.

the state file is a JSON file that contains an array of run attempts.

Each run attempt is an object mapping successful tests to the attempt they have passed in.

The key identifying a test in this map is the test file path, with the line and column where the test is defined.

in a case where a test defined in a specific location is run multiple times,

for example within a function or a loop,

a counter will be appended to the key, to disambiguate the test runs.

note changing the order of test execution or the location of a test can lead the test runner

to consider tests as passed on a previous attempt,

meaning `--test-rerun-failures` should be used when tests run in a deterministic order.

example of a state file:

[

{

"test.js:10:5": { "passed_on_attempt": 0, "name": "test 1" },

},

{

"test.js:10:5": { "passed_on_attempt": 0, "name": "test 1" },

"test.js:20:5": { "passed_on_attempt": 1, "name": "test 2" }

}

]

in this example, there are two run attempts, with two tests defined in `test.js`,

the first test succeeded on the first attempt, and the second test succeeded on the second attempt.

When the `--test-rerun-failures` option is used, the test runner will only run tests that have not yet passed.

node --test-rerun-failures /path/to/state/file

Individual tests can be marked as flaky or incomplete by passing the `todo`

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_.

* `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

* `cause` {Error} The actual error thrown by the test.

* `type` {string|undefined} The type of the test, used to denote whether

this is a suite.

* `attempt` {number|undefined} The attempt number of the test run,

present only when using the [`--test-rerun-failures`][] flag.

* `file` {string|undefined} The path of the test file,

`undefined` if test was run through the REPL.

* `line` {number|undefined} The line number where the test is defined, or

* `duration_ms` {number} The duration of the test in milliseconds.

* `type` {string|undefined} The type of the test, used to denote whether

this is a suite.

* `attempt` {number|undefined} The attempt number of the test run,

present only when using the [`--test-rerun-failures`][] flag.

* `passed_on_attempt` {number|undefined} The attempt number the test passed on,

present only when using the [`--test-rerun-failures`][] flag.

* `file` {string|undefined} The path of the test file,

`undefined` if test was run through the REPL.

* `line` {number|undefined} The line number where the test is defined, or

[`--test-only`]: cli.md#--test-only

[`--test-reporter-destination`]: cli.md#--test-reporter-destination

[`--test-reporter`]: cli.md#--test-reporter

[`--test-rerun-failures`]: cli.md#--test-rerun-failures

[`--test-skip-pattern`]: cli.md#--test-skip-pattern

[`--test-update-snapshots`]: cli.md#--test-update-snapshots

[`--test`]: cli.md#--test

}

]

},

"test-rerun-failures": {

"type": "string"

},

"test-shard": {

"type": "string"

},

}

]

},

"test-rerun-failures": {

"type": "string"

},

"test-shard": {

"type": "string"

},

.It Fl -test-reporter-destination

The destination for the corresponding test reporter.

.It Fl -test-rerun-failures

Configures the tests runner to persist the state of tests to allow

rerunning only failed tests.

.It Fl -test-only

Configures the test runner to only execute top level tests that have the `only`

option set.

reporterScope,

shouldColorizeTestFiles,

setupGlobalSetupTeardownFunctions,

parsePreviousRuns,

} = require('internal/test_runner/utils');

const { PassThrough, compose } = require('stream');

const { reportReruns } = require('internal/test_runner/reporter/rerun');

const { queueMicrotask } = require('internal/process/task_queues');

const { TIMEOUT_MAX } = require('internal/timers');

const { clearInterval, setInterval } = require('timers');

shouldColorizeTestFiles: shouldColorizeTestFiles(globalOptions.destinations),

teardown: null,

snapshotManager: null,

previousRuns: null,

isFilteringByName,

isFilteringByOnly,

async runBootstrap() {

return summary;

function setupFailureStateFile(rootTest, globalOptions) {

if (!globalOptions.rerunFailuresFilePath) {

return;

}

rootTest.harness.previousRuns = parsePreviousRuns(globalOptions.rerunFailuresFilePath);

if (rootTest.harness.previousRuns === null) {

rootTest.diagnostic(`Warning: The rerun failures file at ` +

`${globalOptions.rerunFailuresFilePath} is not a valid rerun file. ` +

'The test runner will not be able to rerun failed tests.');

rootTest.harness.success = false;

process.exitCode = kGenericUserError;

return;

}

if (!process.env.NODE_TEST_CONTEXT) {

const reporter = reportReruns(rootTest.harness.previousRuns, globalOptions);

compose(rootTest.reporter, reporter).pipe(new PassThrough());

}

function setupProcessState(root, globalOptions) {

const hook = createHook({

__proto__: null,

const rejectionHandler =

createProcessEventHandler('unhandledRejection', root);

const coverage = configureCoverage(root, globalOptions);

setupFailureStateFile(root, globalOptions);

const exitHandler = async (kill) => {

if (root.subtests.length === 0 && (root.hooks.before.length > 0 || root.hooks.after.length > 0)) {

// Run global before/after hooks in case there are no tests

const {

ArrayPrototypePush,

JSONStringify,

} = primordials;

const { relative } = require('path');

const { writeFileSync } = require('fs');

function reportReruns(previousRuns, globalOptions) {

return async function reporter(source) {

const obj = { __proto__: null };

const disambiguator = { __proto__: null };

for await (const { type, data } of source) {

if (type === 'test:pass') {

let identifier = `${relative(globalOptions.cwd, data.file)}:${data.line}:${data.column}`;

if (disambiguator[identifier] !== undefined) {

identifier += `:(${disambiguator[identifier]})`;

disambiguator[identifier] += 1;

} else {

disambiguator[identifier] = 1;

}

obj[identifier] = {

__proto__: null,

name: data.name,

passed_on_attempt: data.details.passed_on_attempt ?? data.details.attempt,

};

}

}

ArrayPrototypePush(previousRuns, obj);

writeFileSync(globalOptions.rerunFailuresFilePath, JSONStringify(previousRuns, null, 2), 'utf8');

};

module.exports = {

__proto__: null,

reportReruns,

only,

argv: suppliedArgs,

execArgv,

rerunFailuresFilePath,

root: { timeout },

cwd }) {

const processNodeOptions = getOptionsAsFlagsFromBinding();

if (timeout != null) {

ArrayPrototypePush(runArgs, `--test-timeout=${timeout}`);

}

if (rerunFailuresFilePath) {

ArrayPrototypePush(runArgs, `--test-rerun-failures=${rerunFailuresFilePath}`);

}

ArrayPrototypePushApply(runArgs, execArgv);

execArgv = [],

argv = [],

cwd = process.cwd(),

rerunFailuresFilePath,

} = options;

if (files != null) {

);

}

if (rerunFailuresFilePath) {

validatePath(rerunFailuresFilePath, 'options.rerunFailuresFilePath');

}

if (shard != null) {

validateObject(shard, 'options.shard');

// Avoid re-evaluating the shard object in case it's a getter

coverage,

coverageExcludeGlobs,

coverageIncludeGlobs,

rerunFailuresFilePath,

lineCoverage: lineCoverage,

branchCoverage: branchCoverage,

functionCoverage: functionCoverage,

isolation,

argv,

execArgv,

rerunFailuresFilePath,

};

if (isolation === 'process') {

} = require('timers');

const { TIMEOUT_MAX } = require('internal/timers');

const { fileURLToPath } = require('internal/url');

const { relative } = require('path');

const { availableParallelism } = require('os');

const { innerOk } = require('internal/assert/utils');

const { bigint: hrtime } = process.hrtime;

return this.#test.passed;

}

get attempt() {

return this.#test.attempt ?? 0;

}

diagnostic(message) {

this.#test.diagnostic(message);

}

this.childNumber = 0;

this.timeout = kDefaultTimeout;

this.entryFile = entryFile;

this.testDisambiguator = new SafeMap();

} else {

const nesting = parent.parent === null ? parent.nesting :

parent.nesting + 1;

this.endTime = null;

this.passed = false;

this.error = null;

this.attempt = undefined;

this.passedAttempt = undefined;

this.message = typeof skip === 'string' ? skip :

typeof todo === 'string' ? todo : null;

this.activeSubtests = 0;

this.loc.file = fileURLToPath(this.loc.file);

}

}

if (this.loc != null && this.root.harness.previousRuns != null) {

let testIdentifier = `${relative(this.config.cwd, this.loc.file)}:${this.loc.line}:${this.loc.column}`;

const disambiguator = this.root.testDisambiguator.get(testIdentifier);

if (disambiguator !== undefined) {

testIdentifier += `:(${disambiguator})`;

this.root.testDisambiguator.set(testIdentifier, disambiguator + 1);

} else {

this.root.testDisambiguator.set(testIdentifier, 1);

}

this.attempt = this.root.harness.previousRuns.length;

const previousAttempt = this.root.harness.previousRuns[this.attempt - 1]?.[testIdentifier]?.passed_on_attempt;

if (previousAttempt != null) {

this.passedAttempt = previousAttempt;

this.fn = noop;

}

}

}

applyFilters() {

if (!this.passed) {

details.error = this.error;

}

if (this.attempt !== undefined) {

details.attempt = this.attempt;

}

if (this.passedAttempt !== undefined) {

details.passed_on_attempt = this.passedAttempt;

}

return { __proto__: null, details, directive };

}