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(<number>), { 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.

…