cypress-flake-fixer skill

Cypress Flake Fixer

Audit an existing Cypress suite for the code patterns that cause intermittent failures, then fix them without hiding the problem behind retries, longer timeouts, or force: true.

When to Use This Skill

• A Cypress spec passes locally and fails in CI, or fails once in every few runs
• The suite contains cy.wait(), { force: true }, or tests that only pass in order
• Errors mention "detached from the DOM", "timed out retrying", or a subject that "is no longer attached"
• The project is upgrading Cypress across a major version (12 through 16)
• A review of Cypress test code is requested

For writing new Cypress tests from scratch, coding standards are enough. This skill is for diagnosing and repairing an existing suite.

Prerequisites

• Node.js 18 or later to run the scanner (it has no dependencies and does not need Cypress installed)
• The Cypress version, read from package.json. Fixes differ by major version

Workflow

1. Scan

node ./scripts/scan-cypress.mjs <project-root>
node ./scripts/scan-cypress.mjs <project-root> --json          # machine-readable
node ./scripts/scan-cypress.mjs <project-root> --strict        # add low-confidence rules
node ./scripts/scan-cypress.mjs cypress/e2e/checkout.cy.ts     # one file

The scanner reads the Cypress version from the nearest package.json and grades removed APIs as error when the installed major already rejects them and warn when they break on upgrade. Run --list-rules for the catalog.

Findings are heuristic. Open each location and confirm before editing.

2. Measure before changing anything

When the goal is to fix a specific flaky spec, record how often it fails first. Without a baseline there is no way to tell a fix from luck.

for i in $(seq 1 20); do npx cypress run --spec "cypress/e2e/checkout.cy.ts" --quiet || echo "FAIL $i"; done

A spec that fails 1 run in 10 needs about 30 clean runs after the fix before the fix is believable.

3. Fix in this order

Before-and-after code for every rule is in references/anti-patterns.md. Replacements for removed APIs are in references/removed-apis.md. Read the section for the rule being fixed; do not load both files upfront.

4. Replace each fixed wait with the condition it was standing in for

Do not delete a cy.wait(n) or swap it for a guess. Work out what the delay covered:

5. Verify

1. Run the changed spec alone, then repeat it at least as many times as the baseline run.
2. Rerun the scanner and compare counts per rule.
3. Run the full suite once to catch order dependence exposed by the change.

Rules for the fix itself

• Change test code only. If the test exposes an application bug (double submit, missing loading state, race in the UI), report it instead of working around it.
• Do not raise defaultCommandTimeout, add retries, or add { force: true } to make a test pass. Each one converts a visible failure into a slower or hidden one.
• Do not replace cy.wait(2000) with cy.wait(5000), or with .should('exist') on an element that was already present.
• Keep one rule category per commit so a regression can be bisected.
• Fix shared custom commands in cypress/support first. A fixed wait inside a command runs in every test that calls it.

Gotchas

• Register cy.intercept() before the request can fire. For requests made on page load that means before cy.visit(). An intercept registered after the request has left never matches, and cy.wait('@alias') times out intermittently depending on network speed.
• Each cy.wait('@alias') consumes one request. If the app calls the endpoint twice, the first wait resolves on the first call and the assertion runs against stale data. Wait once per expected call, or assert on the DOM.
• GraphQL uses one URL for every operation. Alias inside the handler: cy.intercept('POST', '/graphql', (req) => { if (req.body.operationName === 'GetOrders') req.alias = 'getOrders' }).
• .should('not.exist') passes before the element has rendered. Using it to wait for a spinner to disappear succeeds instantly on a slow page. Assert the positive end state.
• Server-rendered apps accept clicks before handlers are attached. In Next.js, Nuxt, SvelteKit, and Remix the button is visible and enabled in the server HTML, so Cypress clicks it during hydration and nothing happens. Have the app set a marker when hydration completes (for example a data-hydrated attribute on from a mount effect) and assert on it after cy.visit().
• A .should() in the middle of a chain pins the subject. Queries after it cannot re-query past the assertion, so a re-render produces a detached-DOM error. Split the chain at the assertion.
• .then() breaks the retry chain even with no assertion inside. Everything before it runs once.
• Cypress 16 types with no delay between keys (keystrokeDelay default changed from 10 to 0). Inputs that re-render per keystroke or debounce on input may now drop characters or fire once. Assert the field value after typing instead of restoring the delay.
• Cypress 16 turned cookie and storage getters into queries. cy.getCookie(), cy.getCookies(), cy.getAllCookies(), cy.getAllLocalStorage(), and cy.getAllSessionStorage() now retry chained .should() assertions, which removes the need for waits around auth cookies.
• The page is blank after cy.session(). A missing cy.visit() after it looks like a flaky selector failure.
• testIsolation: false shares state across tests. If the config sets it, every order-dependent failure is expected behavior, not flake. Check the config before diagnosing.
• Retries hide flake unless configured to report it. To find flaky tests instead of masking them, use the experimental strategy that retries and still fails:

retries: {
    experimentalStrategy: 'detect-flake-but-always-fail',
    experimentalOptions: { maxRetries: 2, stopIfAnyPassed: true },
    openMode: true,
    runMode: true,
  }

• CY005 is a judgement call. cy.get(input).clear().type('x') on an input that never re-renders is fine. Split the chain when the element belongs to a list, a form library that remounts fields, or anything driven by async state.

Report format

## Cypress flake audit: <scope>

- Cypress version: <range>, major <n>
- Files scanned: <n>
- Baseline: <spec> failed <f> of <n> runs

| Rule | Before | After | Notes |
|---|---|---|---|
| CY001 fixed-wait | 14 | 0 | 9 replaced by intercept aliases, 5 by assertions |

### Not fixed
- <location>: <reason, for example needs an application change>

### Application issues found
- <behavior the tests exposed>

### Verification
- <spec>: <n> of <n> runs passed after the change

Troubleshooting

References

• references/anti-patterns.md: before-and-after code for every scanner rule
• references/removed-apis.md: removed APIs by Cypress major, with migration code for Cypress.env() and cy.exec()
• Cypress retry-ability
• Cypress migration guide