How to Debug Failing Tests

Knowing how to debug failing tests is arguably one of the most important and useful skills for you to learn. In this lesson we will discuss various tips, methods and techniques to help you debug and fix your failing tests.

Cypress UI

The Cypress UI is one of the fastest ways to figure out what went wrong with your tests.

Screenshot of Cypress Command Log with a failing test marked as red with the 'contains: 4 Courses' assertion failing and a full error message printed as 'Timed out retrying after 4000ms, expected to find 4 Courses within the element dt but never did'. There's also a stack trace highlighting the exact line of test code that failed.

It can also be incredibly useful to see all of the steps your tests took before the error was triggered. When you click on a step, Cypress will output useful information to the browser's console.

For example, in the failing test above, when clicking upon the assertion step, Cypress logs out the actual array in the console.

Screenshot of browser displaying the Cypress command log with a failed assertion on 'contains: 4 Courses' and the 'eq: 1' command highlighted in purple. The Developer Tool's console is exapanded showing log details about the 'eq' command such as the command, selector, what element it was applied to, what the command yielded, and the number of elements found.

Screenshots & Videos

When you are running Cypress in headless mode by using the cypress run command, screenshots and videos will automatically be recorded anytime there is a failure. This is incredibly useful, especially when running your tests in CI, as it provides you with not only a screenshot at the exact point of failure, but also a video of your failing test.

You can tell Cypress to take a screenshot manually by using the cy.screenshot() command.

Logging

There are two useful ways to log information from your tests. One way is to use cy.log() the other is to use console.log() . Remember Cypress is just JavaScript so you can leverage all of the helpful debugging techniques you use in JS too.

cy.log() will print a message to the Cypress Command Log

Screenshot of Cypress command log with an arrow pointing to 'log: my custom message' in the passing test's log

You can also use console.log() which will log to the browser's console.

console.log("my custom message")

Screenshot of Developer Tool's Console tab with 'my custom message' as a log in the Console

Browser Dev Tools

Since Cypress runs in the browser, you have full access to all of the information from your browser's developer tools. This means you can use the same techniques and functionality you are used to using when debugging issues with your application code to debug your failing Cypress tests too.

Screenshot of the browser showing the Cypress UI with the command log, application under test, and developer tools expanded at the bottom showing the command logs in the console