Debug Cypress Test Failures With Code Frames

Updated 8 November 2026 · Standard formula, shown below

Code frames show the source lines around a Cypress test failure, helping you connect an error message to the command or assertion that triggered it. You can use them in the Cypress runner or terminal output, then follow the stack trace and inspect the relevant test and application code. You’ll need a Cypress project with a failing test and access to its source files.

What You’ll Need

A Cypress project and a test that fails consistently or often enough to inspect.
Access to the project files, including the test, application code, and Cypress configuration.
A terminal and, for interactive debugging, a browser window in which to open the Cypress runner.
Source maps if you need to trace bundled application code back to its original files. Cypress and your build setup may provide these automatically in development.

Step-by-Step

Reproduce the failure. Run the specific spec rather than the full suite when possible. For example, use npx cypress open and select the spec in the runner, or run npx cypress run --spec "cypress/e2e/login.cy.js". Replace the path with the failing spec in your project. A smaller run makes the relevant error easier to find and reduces unrelated noise.
Read the complete failure message. Note the test name, failed command or assertion, expected and actual values, and file and line number. In the runner, select the failed test and inspect its command log. In headless output, scroll to the failure details and stack trace. Don’t stop at the first line: the most useful location may be farther down the trace.
Find the code frame. A code frame is a short excerpt of source code with the relevant line marked, often with a caret or line number. Check whether it points to the test itself, a custom command, a helper, or application code. The marked line is a starting point, not proof that the defect is on that exact line; an earlier command or asynchronous change may have caused the failure.
Open the cited file and inspect context. Read several lines before and after the marked location. Check the selector, assertion, arguments, and any setup or cleanup that affects the test. If the frame references generated or bundled code, use the stack trace and source maps to find the original source. Confirm that the file and line correspond to the current code, especially if the test or build has changed since the run.
Trace the Cypress command sequence. In the runner, use the command log to step through the test’s recorded actions and inspect snapshots where available. Identify the last command that behaved as expected and the first one that did not. This helps distinguish a bad assertion from a page that failed to load, a selector that matched the wrong element, or a state change that happened too late.
Check whether the failure is timing-related. Cypress automatically retries many queries and assertions until they pass or time out, but it cannot make every action wait for an application condition you did not express. Prefer a retryable query followed by an assertion, such as cy.get('[data-cy=message]').should('be.visible'). Avoid fixed waits such as cy.wait(1000) as a general fix; wait for a meaningful UI condition or an explicitly aliased network request instead.
Use a breakpoint when the frame is not enough. Add debugger in a test or application code location, then run the spec in the interactive runner with browser developer tools open. Execution pauses only when the browser’s JavaScript debugger is active. Inspect variables and the call stack, then resume. Remove the breakpoint afterward so it does not interrupt later runs.
Check error handling and test setup. If the frame points to a hook or helper, review before, beforeEach, custom commands, and any intercepts or fixtures the test depends on. A setup failure can make a later assertion appear to be the problem. Also check whether the test depends on data, cookies, or application state left behind by another test.
Make one targeted change and rerun. Change the suspected cause rather than weakening or deleting the assertion. Rerun the same spec, then run it again if the failure may be intermittent. Once it passes reliably, run the surrounding suite to check for side effects. Keep the error output and the before-and-after change available when asking a teammate for help.

Common Mistakes

Assuming the highlighted line is always the root cause. A failed assertion may expose an earlier navigation, data, or timing problem. Trace backward to the first unexpected command.
Using arbitrary waits to hide a race. A longer timeout can make a test slower without making it reliable. Assert the condition that indicates the page is ready.
Confusing a test failure with an application exception. Read the error type and stack trace. A Cypress assertion, an uncaught application error, and a failed network request need different fixes.
Changing the assertion to match incorrect behavior. Confirm what the product should do before updating expected values or selectors.
Ignoring source-map or build context. A frame in generated code may be hard to interpret and may not match the source you are editing. Reproduce in the development configuration and inspect the original file.

Tips

Use stable selectors intended for tests, such as dedicated data-cy attributes, rather than selectors tied to styling or changeable text.
Keep tests focused. A short test with a clear failure point is easier to diagnose than a long scenario with many unrelated assertions.
Use cy.intercept() and an alias when a test needs to wait for a particular request, then assert on the response or resulting UI.
When a failure happens only in CI, compare the exact spec, environment variables, browser, build, and test data used locally and in CI. Do not assume the code frame alone explains an environment difference.
Preserve the original failure message when reporting a bug. Include the spec path, test name, relevant stack trace, and steps to reproduce, while omitting secrets or sensitive test data.

Troubleshooting

No code frame appears: Start with the test name, stack trace, and command log. Run the spec in the interactive runner for more context, and confirm the run reports the latest source rather than stale output. Some errors, such as failures in external or generated code, may not have a useful frame.

The frame points to the wrong or unreadable file: Check the path and line in the stack trace. If it points into a bundle, enable or verify source maps in the development build and reproduce with that build. If source maps are unavailable, use the call stack and search the project for the distinctive function or error text.

The test passes locally but fails intermittently: Repeat the isolated spec and inspect the first command that differs between passing and failing runs. Look for unexpressed readiness conditions, shared state, test-order dependencies, and data that changes between runs. Replace timing assumptions with assertions or request aliases where appropriate.

The debugger does not pause: Confirm developer tools are open and that execution reaches the debugger statement. Check that the statement is in code executed by the browser, not in a Node-side task or configuration file. Remove it after diagnosis.

The stack trace is dominated by Cypress internals: Look for the first frame that references your project code and use the command log to identify the preceding test action. Cypress internals can describe how the failure surfaced without identifying the underlying application cause.

Frequently Asked Questions

What is a code frame in a Cypress failure?
A code frame is a short source excerpt around a reported error location, usually marked with a line number or caret. It helps locate where to investigate.

Where can I see Cypress failure details?
In interactive mode, select the failed test and inspect its command log. In headless mode, review the terminal output for the assertion, file location, and stack trace.

Why does the code frame point to an assertion that looks correct?
The assertion may be where Cypress detected a problem caused earlier, such as a delayed UI update, wrong data, or a failed request. Inspect preceding commands and the application state.

Should I add a fixed wait to fix a failing test?
Usually not. Prefer a retryable query and assertion, or wait for a specific aliased request when network completion is what matters.

Can code frames show the original source for bundled code?
They can when usable source maps are available and configured. Without them, the trace may point to generated files; inspect the development build and source-map setup.

What should I include when sharing a failure?
Share the spec path, test name, full relevant error and stack trace, reproduction steps, and the first unexpected command. Remove credentials and sensitive data.

Method: the standard formula for this calculation, rounded as each result states. See how the calculators work or report an error.