Cypress – debugging tests: 5 tips

Writing code is fun, but what do you do when things don’t go the way they should? When you create tests in Cypress, you don’t have to go far to run into pitfalls and problems. This could be bugs in the code itself, or unexpected behavior of the application you’re testing. So how to debug effectively in Cypress? Here are some tips and tricks that might help you.

Haven’t heard of Cypress yet? Read our article about Cypress introduction and features.

1. Cypress testing and Test Replay in Cypress 13

Cypress co-founder, Brian Mann, introduced Test Replay in the Cypress Cloud during an exclusive webinar (find the full recording in this link). This feature provides developers with the ability to dig deeper into the nature of failures. It undoubtedly opens a new chapter in the field of debugging.

This is because Test Replay allows you to interact with the Document Object Model (DOM) at the exact point of test failure. It also allows you to examine network traffic events, console logs, and JavaScript errors without the need to reproduce the problem locally in a continuous integration (CI) environment. Prior to the introduction of Cypress v13, test failures in CI were historically recorded through screenshots or videos, but these sources provided limited information. Test Replay allows developers to travel back in time to the exact moment a test fails. This gives them access to detailed information, enabling faster and more accurate debugging, and increases confidence in the performance of tests in a CI environment.

2. The console is your friend

You don’t always need complex debugging tools. Sometimes you just need to open the browser console and look at the error messages or logs. You can use console.log to list the values of variables or examine how the state of objects changes between test steps.

To write values to the console, you can use the .then() method, where you write the element or value directly to the console.

it('should log information to the console', () => {
  // Získanie elementu a logovanie jeho textu do konzoly
    .then((text) => {
      console.log('Text of #my-element:', text);

  // Alternatívne môžete použiť cy.log pre zobrazenie informácií v Cypress výstupe
  cy.log('This message will appear in the Cypress log');

In this example, console.log is used to display the text from the #my-element in your browser’s console. The .then() method is used to retrieve the text from the element when the element is available.

An alternative option is to use the cy.log() method to display the message directly in the Cypress log.

3. Use Cypress debugger

Using the debugger command in Cypress is often an essential tool that allows you to add a breakpoint to your code so that you can examine the state of your application at a given test point.

The debugger command is often used directly in the code to create a breakpoint. However, in Cypress, due to the asynchronous nature of its commands, simply inserting a debugger into the code may not work quite as expected. To make the debugger statement effective, it’s often better to use it in combination with the .then() method, which allows you to stop executing statements after the previous statements have completed.

it('analyzing the element after it is retrieved', () => {
  cy.visit('/my/page/path'); // navštívi stránku
  cy.get('.my-element-class').then(($myElement) => {
    // príkaz debugger bude vykonaný až po dokončení príkazov cy.visit a cy.get,
    // čo ti umožní preskúmať stav DOM a vašej aplikácie v tomto bode

4. Use the .debug() method

The .debug()method in Cypress is a useful feature that allows you to pause the execution of tests and gives you the ability to manually examine the state of the application in the browser. Here’s an example of how you can use the .debug()method in your Cypress tests.

it('debugging a specific element', () => {
  cy.visit('/my/page/path'); // navštívi stránku
  cy.get('.my-button-class').debug(); // zastaví vykonávanie a umožní ti preskúmať stav

After executing the .debug() method, you can open the developer tool console in your browser and examine the state of the application, including the searched element and its properties.

After debugging is complete, be sure to remove or comment out any .debug() statements in the tests. It’s not a good idea to leave them in the code, as this could cause problems in future tests.

5. Visualise your tests

Debugging in test tools like Cypress is not just about code and console messages. Cypress also offers the ability to create screenshots and record videos, which can be extremely useful for understanding what’s going on in your tests. Here are some tips on how to use these features effectively.

  • Screenshots

Cypress automatically generates screenshots in case of failed tests if the tests are running in headless mode. The screenshots are then saved in the cypress/screenshots directory by default.

Cypress also allows you to manually create screenshots using the cy.screenshot() function.

// Vytvorí screenshot celej stránky

// Vytvorí screenshot konkrétneho elementu

For example, you can also specify various other criteria, such as the file name, whether the screenshot should be taken before or after the test action, and so on.

cy.screenshot('my-screenshot', {
  capture: 'viewport', // zachytáva iba viewport
  • Videos

Video recording is activated in headless mode (when running the cypress run command) as mentioned in the screenshots. The function can also be activated by changing the video value to “true” within your configuration file. If video recording is enabled, Cypress will create a video recording for each spec file.

When to use screenshots and videos

  • Screenshots are best for isolated issues or bugs that can be easily recorded in one shot.
  • Videos are useful when you need to follow the complex progress of a test or want to share an issue with your team.
  • Both methods are ideal for use in combination with a CI/CD pipeline, where you can automatically archive media files and review them if a test fails.

Debugging is an integral part of development and testing. It’s a process that requires patience, but also knowledge of the tools and methods at your disposal. I hope these tips and tricks will help you become more efficient when debugging in Cypress.

About the author

Katarína Kučáková

Software Test Engineer

Moja cesta k testovaniu softvéru sa začala v roku 2019 až po štúdiu ekonómie a pracovných skúsenostiach v iných odvetviach. To mi pomohlo vnímať IT svet v rôznych súvislostiach. Ten totiž ponúka neustále nové výzvy, pre ktoré rada hľadám riešenia. Obľubujem oddych pri čítaní, turistiku alebo lyžovanie. LinkedIn

Let us know about you