Test retries replay side-effecting commands without deduplication

Direct answers

Does Cypress document testRetries as a full test body replay with no automatic suppression of side effects? Yes. The documented behavior is that a failing test is re-executed in its entirety, including all commands, hooks, and side-effecting operations such as cy.request(), cy.visit(), or UI interactions. Cypress does not provide built-in idempotency keys, deduplication, or rollback for commands that ran before the failure point.

Is there a documented distinction between test-level retries and command-level retry settings regarding duplicate execution? Yes. Command-level options like retryOnStatusCodeFailure and retryOnNetworkFailure apply to individual command retries within a single test attempt. They are separate from testRetries, which restarts the whole test function. Confusing the two can mask duplicate side effects because command retries may repeat a single request while test retries repeat the entire sequence.

What is the supported design expectation for tests that must avoid duplicate writes on retry? The framework expects tests using testRetries to be written idempotently or to guard side effects externally (e.g., via test-scoped database transactions, API idempotency keys, or stubbed responses). Cypress does not automatically suppress or deduplicate mutations across retry attempts.

Behavior summary

• Full replay: On failure, the test function runs again from the first line, re-running beforeEach hooks, all commands, and assertions.
• No built-in guards: Network requests, DOM mutations, and database writes execute again. Cypress does not track or suppress duplicate cy.request() calls across retries.
• Command retries ≠ test retries: cy.request({ retryOnStatusCodeFailure: true }) retries that single command; testRetries: 2 retries the whole test. They stack but serve different purposes.
• Consistent across modes: Behavior is generally the same in cypress run and cypress open for both e2e and component testing, though component tests may remount components differently on each attempt.

Verification steps

1. Check your installed version: cat node_modules/cypress/package.json | grep version (or npx cypress --version).
2. Add a visible side effect in a test, e.g., a cy.request('POST', '/api/items', { name: 'test' }) that creates a record.
3. Force a failure after the request (e.g., expect(false).to.be.true).
4. Enable testRetries: 2 in cypress.config.js or the test config.
5. Run the test and observe the API logs or database: the POST will execute once for the initial run and once for each retry attempt.

Practical patterns to avoid duplicate writes

• Use API idempotency keys (e.g., Idempotency-Key header) so duplicate POSTs are safe.
• Wrap tests in database transactions that roll back after each attempt (requires test-level setup/teardown, not built-in).
• Stub mutating requests with cy.intercept() and assert on call count instead of hitting real endpoints.
• Design assertions to be side-effect-free; keep mutations in beforeEach only if they are idempotent or rolled back.

Version assumption and review flag

This answer assumes Cypress 12.x–13.x behavior. Exact documentation phrasing and any version-specific guarantees (e.g., component test mount/unmount semantics on retry) should be verified against the testRetries section of the docs for your installed version. Flag for review: If your project uses a version prior to 12.0 or a pre-release, confirm the retry semantics in that version's changelog.