Mocha retry configuration: missing flaky‑test threshold for retried passes

Short answer

No. Mocha (including 10.x) has no configuration option, CLI flag, or built-in reporter behavior that classifies a test passing on attempt 2+ as flaky. A retried pass is reported as an ordinary pass. The supported pattern is to detect it yourself in an afterEach hook using this.currentRetry(), collect the results, and surface them through a custom reporter or a CI artifact.

Why the hook approach works

Two facts in your constraints combine into the detection rule:

• this.currentRetry() returns the current attempt number (0 on the first attempt) and resets per test.
• afterEach runs after every attempt, and by then this.test.state is set for a passing attempt.

So a test that passed on a retry is exactly: this.currentRetry() > 0 && this.test.state === 'passed'. That is your flaky threshold of "one or more retries" expressed as a single condition.

Implementation

In a root-level setup file (loaded via --file or .mocharc):

// flaky-tracker.js
const flaky = [];

exports.flaky = flaky;

exports.mochaHooks = {
  afterEach() {
    if (this.currentRetry() > 0 && this.test.state === 'passed') {
      flaky.push({
        title: this.test.fullTitle(),
        attempts: this.currentRetry() + 1,
      });
    }
  },
};

Then a minimal custom reporter that fails or flags the build:

// flaky-reporter.js
const Base = require('mocha').reporters.Base;
const { flaky } = require('./flaky-tracker');

module.exports = class FlakyReporter extends Base {
  constructor(runner) {
    super(runner);
    runner.on('end', () => {
      if (flaky.length) {
        console.log(`\n${flaky.length} flaky test(s):`);
        for (const f of flaky) {
          console.log(`  ${f.title} (passed on attempt ${f.attempts})`);
        }
        // Quarantine mode: exit non-zero to fail CI
        // process.exitCode = 1;
      }
    });
  }
};

npx mocha --file ./flaky-tracker.js --reporter ./flaky-reporter.js

Version behavior

The retry API (this.retries(), this.currentRetry(), per-attempt hook re-execution) has been stable since roughly Mocha 5.x and is unchanged through 10.x, so this pattern is version-agnostic across that range. One caveat: arrow functions bind this lexically, so hooks must use function syntax to access the Mocha context — this has always been true, not a version difference.

Verification

1. Add a test with this.retries(2) that fails on attempt 0 and passes on attempt 1 (e.g., a counter in module scope).
2. Run with the setup file and confirm the reporter lists it exactly once with attempts: 2.
3. Confirm a test passing on attempt 0 does not appear in the list.

Caveats

Because the whole test function re-runs per attempt, keep side effects idempotent and reset state in beforeEach. Also note the default spec reporter will never show flaky status on its own — the collected data only surfaces through your reporter or by writing the flaky array to a JSON artifact for CI to consume.