Preventing duplicated external writes during Mocha test retries

Direct Answer

Mocha does not provide a built-in mechanism to suppress side effects during retries. To avoid duplicated external writes without adding idempotency logic to every test, you must choose a strategy that matches the external system you are writing to. The most reliable approaches are:

• Database transactions – wrap each test in a transaction and roll back in an afterEach hook (works only for transactional databases).
• Idempotency keys – generate a unique key per test run (e.g., a UUID) and pass it to the external API; the service must support deduplication.
• State reset in beforeEach – delete or reset the specific records the test creates before each retry attempt.
• Mock the external layer – use Sinon.js, Nock, or a similar library to intercept network calls so no real writes occur.

If the external system is a third‑party API that lacks idempotency support and cannot be mocked, you cannot fully eliminate duplicates without modifying the service or accepting the risk.

Confirmed Facts

• Mocha retries re‑execute the entire test function from the beginning, including any beforeEach hooks.
• Mocha does not distinguish between transient and deterministic failures; it simply retries up to the configured count.
• Transaction rollback only works when the database supports transactions and the test uses the same connection/transaction context.
• Idempotency keys require the target service to recognize and deduplicate them; legacy APIs often ignore such keys.

Practical Steps for the Common Case (Transactional Database)

1. In a top‑level beforeEach, start a transaction and make the connection available to the test (e.g., via this.db).
2. In the test, perform all writes using that transaction.
3. In afterEach, always roll back the transaction. Only commit if you explicitly decide to (rare in tests).
4. Set retries at the suite or test level: this.retries(3) or --retries 3.

// Example with a generic DB client that supports transactions
beforeEach(async function () {
  this.trx = await db.beginTransaction();
});

afterEach(async function () {
  await this.trx.rollback(); // runs after each retry attempt
});

it('creates a user', async function () {
  this.retries(2);
  const id = await this.trx.insert('users', { name: 'test' });
  // intentional failure after write to simulate transient error
  if (this.currentTest.state === 'failed') throw new Error('transient');
  assert.ok(id);
});

Verification You Can Run Today

1. Write a test that inserts a row, then throws an error after the insert.
2. Enable retries (this.retries(2)).
3. After the test finishes (passes after retries or fails), query the database directly and confirm exactly one row exists.
4. Add console.log timestamps in beforeEach and the test body to verify the hook runs before each retry.

One Missing Diagnostic Detail

What is the external system you are writing to? (e.g., PostgreSQL, REST API, message queue, etc.) The recommended strategy changes significantly depending on whether the system supports transactions, idempotency keys, or can be mocked.