Cypress Test Runner

What the Test Runner Shows You

When you run npx cypress open, Cypress launches a real browser split into two areas: a command log on the left listing every command and assertion as it executes, and a live preview of your application on the right.

Because Cypress takes a DOM snapshot before and after every command, you can click any entry in the command log and see exactly what the page looked like at that moment, without re-running the test.

cy.visit('/cart');
cy.get('[data-cy="item-count"]').should('have.text', '3');
cy.get('[data-cy="checkout"]').click();

Each of these three lines appears as its own entry in the command log, each clickable for a DOM snapshot at that exact point.

Main Test Runner Areas

Command Log (left)   -> every command, assertion, and event
App Preview (right)  -> live rendering of your app under test
Selector Playground  -> tool for testing selectors interactively

• The command log highlights the currently selected command and shows pass/fail state with color.
• Hovering a command log entry highlights the corresponding element in the app preview.
• The selector playground (crosshair icon) lets you click an element to generate a suggested selector.
• A pinned command "freezes" its snapshot so you can inspect the DOM in your browser's dev tools.

Test Runner Quick Reference

Common interactions you will use constantly while debugging in the Test Runner.

Time-Travel Debugging

Cypress's "time travel" feature comes from storing a DOM snapshot for every command as it runs. Instead of re-running your app to figure out what state it was in when a test failed, you click backward through the command log and see it directly.

This is especially useful for flaky-looking failures: you can compare the snapshot immediately before a failing assertion against the one right after, often revealing that an element was present but not yet in the expected state.

• Click any passed or failed command to view its "before" and "after" DOM snapshot.
• Pin a snapshot to keep it active while you open your browser's own DevTools.
• The final failed command's snapshot is shown automatically when a test fails.

Using the Selector Playground

The selector playground, accessible via the crosshair icon in the Test Runner toolbar, lets you hover or click any element on the page and immediately see a suggested Cypress selector, along with how many matching elements it finds.

// Selector Playground suggestion for a clicked button:
cy.get('[data-cy=checkout-button]')

Prefer selectors the playground marks as matching exactly one element, and prefer data-cy attributes when available.

Common Mistakes

• Only reading the final error message and ignoring the command log entries leading up to the failure.
• Not pinning a snapshot before trying to inspect an element with native browser DevTools.
• Relying on the selector playground's first suggestion without checking whether it targets a stable, semantic attribute.
• Debugging exclusively in headless mode when the interactive Test Runner would show the problem immediately.

Key Takeaways

• The Test Runner shows a command log alongside a live preview of your application.
• Every command stores a DOM snapshot, enabling true time-travel debugging.
• Pinning a snapshot lets you use native browser DevTools against a frozen moment in the test.
• The selector playground helps you quickly find and validate selectors interactively.