feat: implement `repeats` #5011

mmomtchev · 2023-09-13T10:31:10Z

Refs: Re-run a test multiple times / fixes #2332

Requirements

Filling out the template is required. Any pull request that does not include enough information to be reviewed in a timely manner may be closed at the maintainers' discretion.
All new code requires tests to ensure against regressions.

Description of the Change

Implements a this.repeats - a very useful feature judging by the number of thumbs up on the issue #2332

Alternate Designs

This design follows very closely the already existing retries feature

Why should this be in core?

It is a core feature that is difficult to implement in a plugin

Benefits

It is a useful feature that allows:

testing of tear-down procedures
testing for leaks

Possible Drawbacks

This design follows very closely the tried and tested retries feature so the risks should be minimal

Applicable issues

#2332

Refs: Re-run a test multiple times mochajs#2332

linux-foundation-easycla · 2023-09-13T10:31:15Z

The committers listed above are authorized under a signed CLA.

✅ login: mmomtchev / name: Momtchil Momtchev (8cd9463)

falsandtru · 2024-02-13T21:00:56Z

Can you add the current iteration number to the context? Reproducible tests require reproducible seeds.

const rng = xorshift.random(this.currentIteration + 1)

JoshuaKGoldberg

🔥 great PR, thanks for sending @mmomtchev! The test coverage is thorough and the code changes are all clear & logical. Makes sense to me.

I think the only change request on my end is adding a new EVENT_TEST_REPEAT. Would love to hear your thoughts on that.

Note that per #5027 we're trying to ease into big changes. Since this one touches so much we're going to have to wait a while to get through more patch & minor level changes first.

JoshuaKGoldberg · 2024-03-04T15:52:29Z

lib/runner.js

+          repeatedTest.currentRepeat(test.currentRepeat() + 1);
+          tests.unshift(repeatedTest);
+
+          self.emit(constants.EVENT_TEST_RETRY, test, null);


[Refactor] 🤔 I think a "retry" is different from a "repeat" as designed. I think we'd want a constants.EVENT_TEST_REPEAT so hooks can differentiate. Thoughts?

I agree (especially since EVENT_TEST_RETRY is supposed to have a mandatory Error argument) - but I wonder whether there should be a special event. You will get the EVENT_TEST_BEGIN / EVENT_TEST_END / EVENT_TEST_PASS chain anyway. Should there be another event after these when a test is to be repeated? Should it come in place of the EVENT_TEST_PASS?

Hmm yeah that's a good point. I think it'd be reasonable to leave out the event for now. We can always add it in if folks ask. Taking one out is much harder.

Will also want to hear from @mochajs/maintenance-crew on this (and the PR in general, per the review note).

Oh, and per #5011: if there's no event then I think it'd be especially valuable to make sure test contexts have the current repeat count.

JoshuaKGoldberg · 2024-03-04T15:53:31Z

docs/index.md

+
+This feature does re-run a passed test and its corresponding `beforeEach/afterEach` hooks, but not `before/after` hooks.
+
+If using both `repeat` and `retries`, the test will be run `repeat` times tolerating up to `retries` failures in total.


[Praise] Very good line to have. The distinction between the repeat and retries could be tricky for folks to understand. I like having this clear explanation!

JoshuaKGoldberg

(I'd hit the wrong button first)

Copilot

Pull Request Overview

A new core feature is implemented to allow passed tests to be repeated using a new repeats API. Key changes include adding repeats support to suites, tests, and runnables; updating CLI options and documentation; and introducing new assertions and events for repeated tests.

Reviewed Changes

Copilot reviewed 34 out of 34 changed files in this pull request and generated 1 comment.

File	Description
test/integration/fixtures/repeats/*.js	Added integration tests to verify repeats behavior with synchronous and asynchronous tests.
test/integration/fixtures/options/*	Updated option-based tests to include repeats alongside retries.
lib/*.js	Extended core APIs and reporters to track, repeat, and report test repeats.
lib/cli/, example/config/, docs/index.md	Updated CLI metadata, configuration examples, and documentation for repeats support.

Comments suppressed due to low confidence (2)

lib/mocha.js:173

The documentation refers to the option as 'repeat' while the implementation and CLI use 'repeats'. For consistency, update the comment to use 'repeats'.

* @param {number} [options.repeat] - Number of times to repeat passed tests.

lib/runnable.js:196

[nitpick] To ensure consistent behavior with Suite.prototype.repeats, consider converting the input to a number (e.g. using parseInt) when setting _repeats.

this._repeats = n;

Copilot · 2025-06-12T07:47:01Z

lib/runner.js

+          repeatedTest.currentRepeat(test.currentRepeat() + 1);
+          tests.unshift(repeatedTest);
+
+          self.emit(constants.EVENT_TEST_RETRY, test, null);


[nitpick] Since repeated tests are conceptually different from retried tests, consider emitting a separate event (e.g. EVENT_TEST_REPEAT) to differentiate their behavior and aid in debugging.

This PR has been open for almost 2 years now - and by now it is out of date. I can certainly invest more time to update it and implement the changes, but I just want to make sure that mocha understands that I won't make any compromises related to my affair and if you are waiting for me to invest more time just to ask once again, at the next conference my leaflets will certainly start with mocha.

implement repeats

8cd9463

Refs: Re-run a test multiple times mochajs#2332

JoshuaKGoldberg mentioned this pull request Feb 6, 2024

🚀 Feature: Re-run a test multiple times: this.repeat #2332

Open

voxpelli requested a review from a team February 13, 2024 16:23

JoshuaKGoldberg added the semver-major implementation requires increase of "major" version number; "breaking changes" label Mar 4, 2024

JoshuaKGoldberg reviewed Mar 4, 2024

View reviewed changes

JoshuaKGoldberg requested changes Mar 4, 2024

View reviewed changes

JoshuaKGoldberg added the status: waiting for author waiting on response from OP or other posters - more information needed label Mar 4, 2024

JoshuaKGoldberg changed the title ~~implement repeats~~ feat: implement repeats Mar 4, 2024

JoshuaKGoldberg added status: needs review a maintainer should (re-)review this pull request and removed status: waiting for author waiting on response from OP or other posters - more information needed labels Aug 6, 2024

JoshuaKGoldberg requested a review from a team August 6, 2024 15:17

voxpelli requested a review from Copilot June 12, 2025 07:46

Copilot AI reviewed Jun 12, 2025

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Uh oh!

feat: implement `repeats` #5011

feat: implement `repeats` #5011

Uh oh!

mmomtchev commented Sep 13, 2023 •

edited by JoshuaKGoldberg

Loading

Uh oh!

linux-foundation-easycla bot commented Sep 13, 2023 •

edited

Loading

Uh oh!

falsandtru commented Feb 13, 2024

Uh oh!

JoshuaKGoldberg left a comment

Uh oh!

JoshuaKGoldberg Mar 4, 2024

Uh oh!

mmomtchev Mar 4, 2024

Uh oh!

JoshuaKGoldberg Mar 4, 2024

Uh oh!

JoshuaKGoldberg Mar 4, 2024

Uh oh!

JoshuaKGoldberg Mar 4, 2024

Uh oh!

JoshuaKGoldberg left a comment

Uh oh!

Copilot AI left a comment

Uh oh!

Copilot AI Jun 12, 2025

Uh oh!

mmomtchev Jun 12, 2025

Uh oh!

Uh oh!


		This feature does re-run a passed test and its corresponding `beforeEach/afterEach` hooks, but not `before/after` hooks.

		If using both `repeat` and `retries`, the test will be run `repeat` times tolerating up to `retries` failures in total.

Uh oh!

feat: implement repeats #5011

Are you sure you want to change the base?

feat: implement repeats #5011

Uh oh!

Conversation

mmomtchev commented Sep 13, 2023 • edited by JoshuaKGoldberg Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Requirements

Description of the Change

Alternate Designs

Why should this be in core?

Benefits

Possible Drawbacks

Applicable issues

Uh oh!

linux-foundation-easycla bot commented Sep 13, 2023 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

falsandtru commented Feb 13, 2024

Uh oh!

JoshuaKGoldberg left a comment

Choose a reason for hiding this comment

Uh oh!

JoshuaKGoldberg Mar 4, 2024

Choose a reason for hiding this comment

Uh oh!

mmomtchev Mar 4, 2024

Choose a reason for hiding this comment

Uh oh!

JoshuaKGoldberg Mar 4, 2024

Choose a reason for hiding this comment

Uh oh!

JoshuaKGoldberg Mar 4, 2024

Choose a reason for hiding this comment

Uh oh!

JoshuaKGoldberg Mar 4, 2024

Choose a reason for hiding this comment

Uh oh!

JoshuaKGoldberg left a comment

Choose a reason for hiding this comment

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull Request Overview

Reviewed Changes

Uh oh!

Copilot AI Jun 12, 2025

Choose a reason for hiding this comment

Uh oh!

mmomtchev Jun 12, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

feat: implement `repeats` #5011

feat: implement `repeats` #5011

mmomtchev commented Sep 13, 2023 •

edited by JoshuaKGoldberg

Loading

linux-foundation-easycla bot commented Sep 13, 2023 •

edited

Loading