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

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

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

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

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

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

"test-rerun-failures": {

"type": "string"

},

"test-rerun-failures": {

"type": "string"

},

.It Fl -test-rerun-failures

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

rerunning only failed tests.

parsePreviousRuns,

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

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

previousRuns: null,

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());

}

setupFailureStateFile(root, globalOptions);

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,

rerunFailuresFilePath,

if (rerunFailuresFilePath) {

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

}

rerunFailuresFilePath,

if (rerunFailuresFilePath) {

validatePath(rerunFailuresFilePath, 'options.rerunFailuresFilePath');

}

rerunFailuresFilePath,

rerunFailuresFilePath,

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

get attempt() {

return this.#test.attempt ?? 0;

}

this.testDisambiguator = new SafeMap();

this.attempt = undefined;

this.passedAttempt = undefined;

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;

}

}

if (this.attempt !== undefined) {

details.attempt = this.attempt;

}

if (this.passedAttempt !== undefined) {

details.passed_on_attempt = this.passedAttempt;

}