Cypress Debugging Tests

A failing test needs investigation before you can fix it. Cypress offers several built-in tools that make debugging faster compared to older testing tools. This topic covers the main techniques for finding the cause of a failure.

Reading the Command Log

The command log inside the Test Runner lists every action performed during a test. Clicking any line shows the exact page state at that specific moment. A failed step appears highlighted, showing the expected result next to the actual result.

A Simple Way to Picture It

Think of the command log as a flight recorder inside an airplane. After an incident, investigators replay the recording to see exactly what happened moment by moment. The command log lets you replay your test the same way, moment by moment.

Using cy.pause

The pause command stops test execution at a specific point, letting you inspect the page manually.

cy.get('#username').type('john_doe')
cy.pause()
cy.get('#password').type('secret123')

The test freezes right before typing the password, giving you time to examine the page in that exact state.

Using cy.debug

The debug command pauses execution and opens the browser's developer console with useful information about the current subject.

cy.get('.error-message').debug()

This command works well alongside browser developer tools already familiar to most web developers.

Debugging Flow Diagram

Test Fails
     |
     v
Check the command log for the failed step
     |
     v
Compare expected vs actual result
     |
     v
Add cy.pause or cy.debug near the failure
     |
     v
Inspect the page manually to find the root cause

Using cy.log for Custom Messages

The log command writes a custom message into the command log, useful for tracking values during a test run.

cy.get('.total').then(($total) => {
  cy.log('Total value: ' + $total.text())
})

Inspecting Screenshots and Videos

Cypress automatically captures a screenshot when a test fails during a headless run. Reviewing this screenshot often reveals visual problems that text logs alone cannot show, such as a misplaced button or an unexpected popup.

Checking Network Activity

The browser developer tools network tab shows every request made during a test, useful for spotting failed or slow API calls. Cypress tests run inside a real browser, so this standard browser feature remains fully available during debugging.

Common Failure Causes

A missing element usually points to either an incorrect selector or a page that has not finished loading. A timeout error often means an assertion never became true within the allowed wait time. An unexpected value in an assertion usually points to either bad test data or an actual application bug.

Isolating a Failing Test

Running a single test file in isolation helps confirm whether a failure depends on other tests running before it.

npx cypress run --spec "cypress/e2e/login.cy.js"

This command runs only the specified file, ignoring the rest of the test suite temporarily.

Using only and skip

Cypress supports marking a single test to run alone using it.only, ignoring every other test in the file during that run.

it.only('shows the login form', () => {
  cy.get('form').should('be.visible')
})

The skip method works the opposite way, temporarily excluding a specific test from running.

Key Points

• The command log shows every action and highlights failures clearly.
• cy.pause stops execution for manual inspection at a chosen point.
• cy.debug opens the developer console with details about the current subject.
• Screenshots and videos help review visual problems after a failed run.
• it.only and it.skip help isolate a specific test during debugging.