What Are the Best Ways to Debug Cypress Tests?
If you've ever run a Cypress test and it failed without a clear reason, you know how tricky debugging can be. Small issues like timing problems, unexpected page behavior, or minor coding errors can make tests fail even when the code looks correct.
Cypress offers several tools to help uncover what went wrong. From reading stack traces to using commands like .debug() and .pause(), these tools let you inspect tests step by step and see exactly where issues occur.
In this article, I will walk through practical ways to debug Cypress tests. You will learn how to read stack traces, use the debugger, add console logs, and leverage commands like .debug() and .pause().
Benefits of Debugging in Cypress
Debugging Cypress tests provides a clear view of how tests interact with the application. It exposes hidden issues, helps stabilize test execution, and allows testers to make precise corrections.
- Pinpoint Asynchronous Failures: Step-through debugging reveals delays, race conditions, and DOM changes that often cause tests to fail unpredictably.
- Enhance Test Accuracy: Inspecting each command execution ensures assertions are based on the actual state of the application, not assumptions or timing artifacts.
- Optimize Test Structure: Debugging highlights fragile selectors, redundant waits, or poorly scoped queries, guiding improvements for maintainable test suites.
- Accelerate Issue Resolution: Real-time observation of test execution reduces repeated test runs and guesswork, helping developers fix problems faster.
- Reveal Application Behavior: Understanding how the application responds during test scenarios uncovers hidden bugs, logic gaps, and edge cases that might be missed in manual review.
How to debug in Cypress: Top 5 Methods
Debugging in Cypress can feel overwhelming at first, but the framework provides several tools to inspect test execution and understand why a test fails. Using these methods systematically helps uncover hidden issues and ensures tests remain stable and maintainable.
Below are the top five ways to debug Cypress tests effectively.
1. Using Stack Traces to Debug Cypress Tests
When a test fails, Cypress automatically generates a stack trace showing where the failure occurred. Stack traces provide details about the exact command, the file, and the line number, which is critical for pinpointing the source of the problem.
Example:
it('should display the correct title', () => {
cy.visit('/dashboard')
cy.get('h1').should('contain', 'Dashbord') // typo causes failure
})
Cypress will output an error with a stack trace pointing to the line with 'Dashbord'. Reviewing the stack trace quickly identifies the assertion failure and the affected test step.
Best Practices:
- Always check the Cypress Test Runner console for the full trace.
- Use stack traces in combination with command logs to understand the sequence leading to failure.
2. Using the Debugger to Debug Cypress Tests
Cypress integrates seamlessly with JavaScript’s debugger statement. When Cypress encounters a debugger, it pauses execution, allowing you to inspect variables and DOM state in the browser’s DevTools.
Example:
it('checks user profile', () => {
cy.visit('/profile')
cy.get('.user-name').then(($el) => {
debugger // execution pauses here
expect($el.text()).to.equal('John Doe')
})
})
Tips:
- Open Chrome DevTools and navigate to the Sources tab to inspect variables and DOM elements.
- Step through code line by line to see how Cypress commands interact with the page.
3. Using Console Logs to Debug Cypress Tests
Console logs are simple but powerful. Adding cy.log() or console.log() statements helps track variable values, test flow, and conditional logic.
Example:
it('verifies cart total', () => {
cy.get('.cart-item').then(($items) => {
console.log('Number of items in cart:', $items.length)
cy.log('Cart contains ' + $items.length + ' items')
})
})
Benefits:
- cy.log() outputs to the Cypress Test Runner, keeping logs contextual.
- console.log() appears in the browser DevTools, providing additional debugging details.
4. Using the .debug() Command in Cypress
The .debug() command pauses the test at a specific Cypress command and prints the current subject in the console. This is useful for inspecting elements or state without stopping the entire test suite.
Example:
cy.get('.todo-item').first().debug().should('contain', 'Buy milk')
Key Points:
- .debug() works inline with Cypress commands, allowing selective inspection.
- The current subject is displayed in DevTools, letting you see exactly what Cypress is working with at that moment.
5. Using the .pause() Command in Cypress
.pause() halts test execution entirely, letting you interact with the page manually in the Cypress Test Runner. This is ideal for investigating intermittent issues or complex UI interactions.
Example:
cy.get('#checkout-button').click()
cy.pause()
cy.get('.confirmation-message').should('be.visible')
How to Use:
- While paused, navigate the Test Runner to inspect DOM elements.
- Resume execution using the play button in the Cypress UI.
.pause() or .debug(): Which Cypress Command Should You Use?
Both .pause() and .debug() are essential tools in Cypress, but they serve slightly different purposes.
.pause() stops the entire test, giving you a chance to manually interact with the page and observe its state, which is useful for complex workflows or intermittent issues. .debug(), on the other hand, focuses on a specific Cypress command or element, printing its current state to the console without halting the rest of the test flow.
| Feature | .pause() | .debug() |
| Execution Halt | Stops the entire test | Pauses only the current subject |
| Interactivity | Allows manual inspection | Only prints current element/subject in console |
| Best Use | Complex flows or intermittent failures | Quick inspection of a specific element or variable |
| Integration | Test Runner pause button | DevTools console inspection |
Rule of Thumb: Use .pause() when you want to interact with the application during a test. Use .debug() when you need to inspect the current element or state without stopping the test flow.
How to Debug Cypress Tests in VS Code
Debugging Cypress tests directly in VS Code combines the power of Cypress commands with a familiar development environment. Setting up VS Code to run Cypress in debug mode allows you to set breakpoints, inspect variables, and step through test execution line by line.
This is especially helpful for complex tests or when diagnosing issues that do not reproduce consistently in the Cypress Test Runner.
Setting Up VS Code for Cypress Debugging:
- Install the Debugger Extension: Ensure the VS Code Debugger for Chrome or Edge is installed to enable browser-based debugging.
- Configure Launch Settings: Create a launch.json file in the .vscode folder with the following configuration:
{
"version": "0.2.0",
"configurations": [
{
"type": "chrome",
"request": "launch",
"name": "Debug Cypress Tests",
"url": "http://localhost:8080",
"webRoot": "${workspaceFolder}"
}
]
}
- Start Cypress in Interactive Mode: Run npx cypress open to open the Test Runner and select the test to debug.
- Set Breakpoints: In your test file, click beside the line number in VS Code to set breakpoints at critical points in the test.
- Attach Debugger: Launch the debug configuration in VS Code to connect to the running Cypress instance. The test will pause at your breakpoints, allowing full inspection.
Once the debugger is attached, you can step through your tests, inspect variables, and observe DOM changes in real time. For issues that only appear in specific browsers or devices, tools like BrowserStack let you run the same tests across multiple real environments in the cloud. This helps ensure that what you debug locally matches how the application behaves for actual users.
Troubleshooting Common Debugging Issues in Cypress Tests
Even with Cypress’s built-in tools, testers often encounter common issues that make debugging harder. These can include timing problems, flaky assertions, or elements not being visible when expected. Understanding these pitfalls helps fix tests faster and prevent repeated failures.
- Timing Issues: Commands may execute before elements are fully loaded. Use cy.wait(), cy.intercept(), or built-in retries to handle asynchronous behavior.
- Flaky Selectors: Dynamic or overly generic selectors can break tests intermittently. Use unique data attributes or robust CSS selectors to improve stability.
- Hidden or Detached Elements: Elements may exist in the DOM but not be visible or attached. Use { force: true } carefully or adjust assertions to check visibility.
- Incorrect Assertions: Tests may fail due to mismatched expectations. Inspect the element state and confirm the actual value before asserting.
- Browser-Specific Behavior: Some issues appear only in certain browsers or device setups. Running tests across multiple browsers and real devices with tools like BrowserStack helps identify these inconsistencies early, making debugging faster and more reliable.
Conclusion
Debugging Cypress tests is essential for creating reliable and maintainable test suites. Using stack traces, console logs, .debug(), .pause(), and VS Code breakpoints helps uncover why tests fail and provides clear insight into how your application behaves during automated testing.
Tools like BrowserStack make this process even smoother by letting tests run across multiple browsers and real devices in the cloud. This ensures that environment-specific issues are caught early, so debugging reflects real-world conditions and delivers more dependable results.
Data-rich bug reports loved by everyone
Get visual proof, steps to reproduce and technical logs with one click
Put your knowledge to practice
Try Bird on your next bug - you’ll love it
“Game changer”
Julie, Head of QA
Overall rating: 4.7/5
Try Bird later, from your desktop
