Duplicate writes from suite‑wide retry causing non‑idempotent test side effects

Direct answers

Can Mocha retry only the failing test without re-running before hooks? No. The --retries flag operates at the suite (file) level. Every retry re-executes the entire test file context, including all before, beforeEach, afterEach, and after hooks.

Is there a configuration to limit retries to the failing test and its after hooks? No such configuration exists in Mocha 10.x or earlier. The retry mechanism is implemented in the runner and always restarts the full suite.

Can a per-test retry API be added to avoid duplicate writes? Mocha exposes this.retries(n) inside a test to set the retry count, but it does not expose any API to control retry scope. Feature requests for test-level retry isolation have been open for years; maintainers consistently recommend making tests idempotent or restructuring hooks.

Why this happens (confirmed behavior)

Mocha's documentation states: "If a test fails, Mocha will retry the test up to n times." In practice, "the test" means the entire test file when --retries is passed on the command line, or the current suite when set programmatically. Each retry creates a fresh run of the suite hierarchy, so before hooks fire again. This is by design, not a bug.

Practical workarounds

1. Move mutable setup to beforeEach with matching afterEach cleanup

let db;
before(async () => { db = await connect(); }); // expensive, immutable
beforeEach(async () => { await db.truncate('widgets'); }); // clean slate each attempt
afterEach(async () => { await db.truncate('widgets'); }); // cleanup on failure too
it('inserts a widget', async () => { await db.insert('widgets', { name: 'A' }); });

Each retry gets a clean table. The cost is running truncate/cleanup on every attempt.

2. Make writes idempotent

// Use upsert / ON CONFLICT DO NOTHING / unique constraints
await db.query(`INSERT INTO widgets (id, name) VALUES (1, 'A') ON CONFLICT (id) DO NOTHING`);

Duplicate executions become harmless. This is the maintainers' preferred approach.

3. Implement custom retry logic inside the test

const retry = require('async-retry');
it('flaky external call', async () => {
  await retry(async (bail) => {
    const res = await fetch('/api/flaky');
    if (!res.ok) throw new Error('flaky');
    return res.json();
  }, { retries: 3, minTimeout: 100 });
});

Only the test body retries; hooks run once. Trade-off: you lose Mocha's built-in retry reporting (attempt numbers in reporters).

4. Share expensive immutable fixtures via before, mutate only in beforeEach

let schema;
before(async () => { schema = await loadSchema(); }); // once per file
beforeEach(() => { db = schema.createTestDb(); }); // fresh per attempt
afterEach(() => db.close());

Diagnostic detail that changes the recommendation

Are the duplicate writes hitting a shared external database used by other test files or processes, or a per-test temporary database that is torn down after the suite? If shared, workaround 1 or 2 is required. If temporary, you can also consider running the suite in a transaction and rolling back in after (though Mocha retries break transaction boundaries).