Skip to main content
Cypress App

Debugging

Your Cypress test code runs in the same run loop as your application, so you have access to the code running on the page, as well as the things the browser makes available to you, like document, window, and debugger.

Based on those statements, you might be tempted to throw a debugger into your test, like so:

it('let me debug like a fiend', () => {
cy.visit('/my/page/path')

cy.get('[data-testid="selector-in-question"]')

debugger // Doesn't work
})

The debugger statement may not work exactly as you are expecting. As you may remember from the Introduction to Cypress, cy commands enqueue an action to be taken later. Can you see what the test above does given that perspective?

Both cy.visit() and cy.get() return immediately, having enqueued their work to be done later, and debugger executes before any of the commands have actually run. You can expect the same behavior in Component Tests when using cy.mount().

Let's use .then() to tap into the Cypress command during execution and add a debugger at the appropriate time:

it('let me debug when the after the command executes', () => {
cy.visit('/my/page/path')

cy.get('[data-testid="selector-in-question"]').then(($selectedElement) => {
// Debugger is hit after the cy.visit
// and cy.get commands have completed
debugger
})
})

Now we're in business! When you're visiting a page or mounting a component for the first time, (shown above with the cy.get()chain and its .then() attached) Cypress enqueues the commands to execute. The it block exits, and Cypress starts its work:

  1. In an end-to-end test, Cypress visits the page and waits for it to load. Alternatively, Cypress mounts and renders the component in a Component Test.
  2. Cypress queries the element, and automatically waits and retries for a few moments if it doesn't find the element immediately.
  3. Cypress executes the function passed to .then(), yielding the found element to it.
  4. Within the context of the .then() function, the debugger statement runs, halting the browser and calling focus to the Developer Tools.
  5. You're in! Inspect the state of your application like you normally would if you'd dropped the debugger into your application code.

Using .debug()​

Cypress also exposes a shortcut for debugging commands, .debug(). Let's rewrite the test above using this helper method:

it('let me debug like a fiend', () => {
cy.visit('/my/page/path')

cy.get('[data-testid="selector-in-question"]').debug()
})

Cypress exposes the current subject that cy.get() yields as the variable subject within your Developer Tools so that you can interact with it in the console.

Debugging Subject

Use .debug() to quickly inspect any (or many!) part(s) of your application during the test. You can attach it to any Cypress chain of commands to have a look at the system's state at that moment.

Step through test commands​

You can run the test command by command using the .pause() command.

it('adds items', () => {
cy.pause()
cy.get('[data-testid="new-todo"]')
// more commands
})

Stepping with cy.pause() stops after each command, so you can inspect the web application, the DOM, the network, and any storage to make sure everything happens as expected.

Debug with an AI agent​

Everything above puts you in front of the Cypress app. If you are working with an AI coding agent, it can read the same information from the terminal with the cypress tap CLI: run the spec you just changed, poll the run's status, read the failing test's Command Log and error, and inspect the DOM of the app under test at the moment a command ran.

Reading that information from the terminal closes the loop without you relaying failures back and forth. Start Cypress with cypress open, then let your agent drive it from another terminal.

npx cypress tap run cypress/e2e/checkout.cy.ts
npx cypress tap status --json
npx cypress tap reporter --test-id <id>

The cypress-tap skill is the easiest way to hand this loop to your agent: it packages these commands so your agent drives them correctly, without you writing the steps by hand. For the full workflow, or a snippet you can drop into your agent's instructions file yourself, see driving Cypress from the terminal with an AI agent.

When the failure happened in CI rather than locally, and you recorded the run to Cypress Cloud, your agent can triage it from the terminal too. The cypress-cloud-cli skill drives the Cloud CLI to read the failing run, its tests, and their Test Replay data, so the agent can find the likely cause from the recorded run before reproducing it locally with cypress tap.

Using the Developer Tools​

Though Cypress has built out an excellent application to help you understand what is happening in your application and your tests, there's no replacing all the amazing work browser teams have done on their built-in development tools. Once again, we see that Cypress goes with the flow of the modern ecosystem, opting to use these tools wherever possible.

info

See it in action!​

You can see a walk-through of debugging some application code from Cypress in this segment from our React tutorial series.

Get console logs for commands​

All of Cypress's commands, when clicked on within the Command Log, print extra information about the command, its subject, and its yielded result. Try clicking around the Command Log with your Developer Tools open! You may find some useful information here.

When clicking on .type() command, the Developer Tools console outputs the following:​

Console Log type

Errors​

Sometimes tests fail. Sometimes we want them to fail, just so we know they're testing the right thing when they pass. But other times, tests fail unintentionally and we need to figure out why. Cypress provides some tools to help make that process as easy as possible.

Anatomy of an error​

Let's take a look at the anatomy of an error and how Cypress displays it, by way of a failing test.

it('reroutes on users page', () => {
cy.contains('Users').click()
cy.url().should('include', 'users')
})

The center of the <li>Users</li> element is hidden from view in our application under test, so the test above fails.

Cypress prints several pieces of information when an error occurs during a Cypress test.

  1. Error name: The error name is the type of error (e.g. AssertionError, CypressError)
  2. Error message: The error message generally tells you what went wrong. Error messages vary in length. Some are short like in the example, while some are long, and may tell you exactly how to fix the error.
  3. Learn more: Some error messages contain a Learn more link that takes you to relevant Cypress documentation.
  4. Code frame file: The code frame file is usually the top line of the stack trace and it shows the file, line number, and column number that is highlighted in the code frame below. Clicking on this link opens the file in your preferred file opener and highlights the line and column in editors that support it.
  5. Code frame: The code frame shows a snippet of code where the failure occurred, with the relevant line and column highlighted.
  6. View stack trace: Clicking View stack trace toggles the visibility of the stack trace. Stack traces vary in length. Clicking on a blue file path opens the file in your preferred file opener.
  7. Print to console button: Click the print to console button to print the full error to your DevTools console. The lines in that stack trace are usually clickable and open the files in your DevTools.
example command failure error

Source maps​

Cypress uses source maps to enhance the error experience. Cypress translates stack traces so that they show your source files instead of the generated file that the browser loads. Source maps also enable displaying code frames. Without inline source maps, you do not see code frames.

By default, Cypress includes an inline source map in your spec file, so you get the most out of the error experience. If you modify the preprocessor, ensure that inline source maps are enabled to get the same experience. Some examples of this include:

If using TypeScript with any custom preprocessor, make sure that the TypeScript compiler is generating source maps. You can turn on source map generation by setting the sourceMap option in your tsconfig.json to true. The inlineSourceMap option is not recommended as it does not provide an accurate code frame. See our recommended tsconfig.json as a reference.

Debugging flake​

While Cypress is flake-resistant, some users do experience flake, particularly when running in CI versus locally.

tip

To debug flake in your recorded tests in CI, try out Test Replay in Cypress Cloud. Test Replay replays the test exactly as it ran in CI.

Most often in cases of flaky tests, we see that there are not enough assertions surrounding test actions or network requests before moving on to the next assertion.

If there is any variation in the speed of the network requests or responses when run locally versus in CI, then there can be failures in one over the other.

Because of this, we recommend asserting on as many required steps as possible before moving forward with the test. Asserting on each step also helps later to isolate where the exact failure is when debugging.

Flake can also occur when there are differences between your local and CI environments. You can use the following methods troubleshoot tests that pass locally but fail in CI.

  • Review your CI build process to ensure nothing is changing with your application that would result in failing tests.
  • Remove time-sensitive variability in your tests. For example, ensure a network request has finished before looking for the DOM element that relies on the data from that network request. You can use aliasing for this.

Cypress Cloud also offers Analytics that illustrate trends in your tests and can help identify the tests that flake or fail most often. Analytics could help narrow down what is causing the flake -- for example, seeing increased failures after a change to the test environment could indicate issues with the new environment.

For more advice on dealing with flake read a series of our blog posts and Identifying Code Smells in Cypress.

Log Cypress events​

Cypress emits multiple events you can listen to as shown below. Read more about logging all events in the browser.

console log events for debugging

Troubleshooting Cypress​

There are times when you encounter errors or unexpected behavior with Cypress itself. In this situation, we recommend checking out our Troubleshooting Guide.

More info​

Often debugging a failing Cypress test means understanding better how your own application works, and how the application might race against the test commands. We recommend reading these blog posts where we show common error scenarios and how to solve them: