Debugging Cypress Test Failures

A Systematic Debugging Process

Rushing straight to a fix often leads to treating symptoms rather than root causes. A more reliable process reads the actual failure message carefully first, reproduces it in an isolated, minimal way, and only then investigates and fixes the underlying cause.

// Step 1: Read the exact failure
// AssertionError: expected '[data-cy="total"]' to have text '$50' but the text was '$0'

// Step 2: Reproduce in isolation
// npx cypress run --spec "cypress/e2e/cart.cy.js"

// Step 3: Isolate: does the total update correctly outside the test, manually?

Each step narrows down whether the issue is in the test, the application, or the test's environment/setup.

The Debugging Checklist

1. Read the exact error: expected vs actual value
2. Reproduce reliably: does it fail consistently, or intermittently?
3. Isolate: run just this spec, then just this test, alone
4. Inspect: use the Test Runner's command log and snapshots
5. Fix and confirm: re-run several times to confirm stability

• Always read the exact expected-versus-actual values before forming a theory.
• Confirm whether a failure is consistent or intermittent before diagnosing it as flaky.
• Running a single isolated test/spec removes noise from unrelated tests.
• Confirm a fix by re-running multiple times, not just once, especially for suspected flakiness.

Failure Type Cheat Sheet

Common failure categories and where to start investigating each.

Reading Failure Messages Carefully

Cypress failure messages are usually specific: which command failed, what was expected, and what was actually observed. Resisting the urge to skim past this detail and jump straight to guessing saves significant time overall.

• Identify exactly which command in the chain failed, not just which test.
• Note the exact expected and actual values, they often immediately suggest the real cause.
• Check whether the failure is an assertion failure, a timeout, or an unrelated JavaScript error.

Isolating a Failure to Its Minimal Reproduction

Running only the specific failing test, with it.only() temporarily or the --spec flag, removes noise from unrelated tests and confirms whether the failure depends on test order or shared state from other tests in the same file.

npx cypress run --spec "cypress/e2e/cart.cy.js"
// If it passes alone but fails in the full suite, investigate shared state next.

Confirming a Fix Thoroughly, Not Just Once

For a suspected flaky failure specifically, re-run the fixed test multiple times (locally in a loop, or via repeated CI triggers) before considering it resolved, a single passing run after a change does not rule out intermittent behavior.

Common Mistakes

• Jumping to a fix before fully reading and understanding the actual failure message.
• Assuming every failure is "just flaky" without first checking for a legitimate, consistent application bug.
• Fixing a symptom (like adding a wait) without identifying why the underlying timing issue occurred.
• Declaring a flaky fix successful after only a single passing re-run.

Key Takeaways

• A systematic process, read, reproduce, isolate, fix, confirm, outperforms guessing on most failures.
• Failure messages usually contain enough detail to form an accurate initial theory.
• Isolating a test from the full suite reveals whether shared state or ordering is involved.
• Confirm fixes for suspected flakiness with multiple re-runs, not just one.