| | |

Cypress 11 ๐ŸŒฒ Time Travel โ€” Command Log Snapshots and Debugging

โฑ๏ธ Estimated read: 9 min | |

Cypress’s time-travel debugging is the feature that made the framework famous. Every cy command in the Command Log is interactive: hovering over an entry restores the Application Under Test to the state it had when that command resolved, and clicking pins the snapshot so it stays fixed while the developer inspects the DOM . The mechanism is a snapshot taken at each command’s resolution, and the Command Log is the interface for stepping backward through the test’s execution without re-running it.

This chapter covers the Command Log’s time-travel behavior, the pinning and snapshot menu that expose the before and after states, and the Cypress.log API that gives a custom command the same visibility as a built-in one. The sections that follow walk through the hover and pin interactions, the snapshot capture for actions that change the DOM, and the custom-command logging that turns a black box into a debuggable step.

Key point: Hovering a Command Log entry restores the DOM snapshot from when that command resolved, clicking pins it, and Cypress.log({ autoEnd: false }) with log.snapshot('before')/log.snapshot('after') gives a custom command the same time-travel tabs as a built-in action.


a. The Command Log and the hover restore

The Command Log is the left panel of the Cypress Test Runner. It lists every command and assertion in the order they ran, nested under the test and the hooks that produced them . Each entry is interactive, and hovering over it restores the Application Under Test to the state it had when that command executed .

cy.visit("/dashboard");          // hover โ†’ the page as it was after load
cy.get('[data-cy="email"]')      // hover โ†’ the email input highlighted
  .type("user@example.com");     // hover โ†’ the input with the typed value
cy.get('[data-cy="submit"]')     // hover โ†’ the button highlighted
  .click();                      // hover โ†’ the page after the click

The hover restore is the “time travel.” The developer moves the mouse up the Command Log, and the right-hand preview rewinds through the test’s states. The URL is restored along with the DOM, so a test that navigates is previewable at the step before and after the navigation .

The snapshot is taken when the command resolves, not when it is enqueued. A cy.get that retried for two seconds has a snapshot from the moment the element was found, which is the state the assertion ran against. The retry itself is visible in the Command Log as the command’s duration, but the snapshot is the resolved state.


b. Pinning and the snapshot menu

Clicking a Command Log entry pins its snapshot. The pinned state stays fixed while the developer hovers other entries, which is the interaction for inspecting the DOM at a specific moment without the preview changing under the cursor .

The pinned entry exposes three details. The pinned snapshot is the DOM state, the event hitbox is the red rectangle that shows where the click or type was targeted, and the snapshot menu is the tab that switches between the before and after states for an action that changes the page .

The before/after pair is the feature that makes an action’s effect visible. A click on a submit button captures the page before the click and after the click, and the menu switches between the two. A type captures the input before the keystrokes and after, which is how the developer confirms the field received the value . The built-in actions capture both; a custom command captures only what its author tells it to.

The Command Log’s memory is finite. Cypress keeps 50 tests worth of snapshots and command data by default, and a browser with high memory consumption can lower the numTestsKeptInMemory configuration to reduce the retained snapshots . The limit is the reason a long suite does not retain every test’s DOM indefinitely.


c. Cypress.log and the custom command

A custom command without Cypress.log is a black box in the Command Log. When it fails, the log shows the command’s name and nothing elseโ€”no internal step, no data, no DOM state . The Cypress.log API is the mechanism for giving the command the same visibility as a built-in one.

Cypress.Commands.add("login", (email, password) => {
  const log = Cypress.log({
    name: "login",
    autoEnd: false, // keep the log open for the async work
  });

  log.snapshot("before"); // DOM before the login

  cy.request("POST", "/api/login", { email, password }).then((response) => {
    log.set({ consoleProps: () => ({ response: response.body }) });
    log.snapshot("after"); // DOM after the login
    log.end();             // mark the log as passed
  });
});

The autoEnd: false option is required for an async command. Without it, the log ends when the command function returns, which is before the cy.request resolves, and the snapshot('after') has no open log to attach to . The log.set call updates the consoleProps with the data that was only available after the async work, which is the response body in the example.

The named snapshots appear as labeled tabs when the log entry is pinned, the same before/after menu the built-in actions have . The consoleProps appear in the browser’s DevTools console when the entry is clicked, which is the structured data that explains what the command did .

The time-travel snapshot has a known limitation. A custom element whose internal state is set by JavaScript rather than by attributes is rendered in its initial state in the snapshot, because the snapshot restores the DOM but does not replay the JavaScript that mutated the custom element . The workaround is to drive the element’s state from attributes, which the snapshot does restore.


Complete Example Session

// ============================================
// PART 1: THE BUILT-IN TIME TRAVEL
// ============================================
describe("checkout", () => {
  it("completes the flow", () => {
    cy.visit("/checkout");              // hover: page after load
    cy.get('[data-cy="card"]').type("4242"); // hover: input with value
    cy.get('[data-cy="pay"]').click();  // hover: page after click
    cy.get('[data-cy="status"]').should("contain", "Paid");
    // Click the click entry โ†’ pin โ†’ before/after menu
  });
});

// ============================================
// PART 2: THE CUSTOM COMMAND WITH LOG
// ============================================
Cypress.Commands.add("login", (email, password) => {
  const log = Cypress.log({ name: "login", autoEnd: false });

  log.snapshot("before");

  cy.request("POST", "/api/login", { email, password }).then((response) => {
    log.set({ consoleProps: () => ({ body: response.body }) });
    log.snapshot("after");
    log.end();
  });
});

// ============================================
// PART 3: THE TIME TRAVEL LIMITATION
// ============================================
// A custom element whose state is set by JS (not attributes)
// renders in its initial state in the snapshot.
// Workaround: drive the state from attributes.

The parts covered the built-in hover and pin, the custom command with before/after snapshots, and the custom-element limitation.


Quick Reference

Command Log Interactions

InteractionEffect
HoverRestore the DOM snapshot
ClickPin the snapshot
Snapshot menuSwitch before/after
Click entryShow consoleProps in DevTools

Cypress.log Methods

MethodPurpose
log.snapshot()Capture the current DOM
log.snapshot("name")Named snapshot tab
log.set({ ... })Update log attributes
log.end()Mark the log as passed
log.error(err)Mark the log as failed

The autoEnd Option

ValueEffect
true (default)Ends when the command returns
falseStays open until log.end()

Best Practices

โœ… Do This:

// Use before/after snapshots in a custom command
log.snapshot("before");
// async work
log.snapshot("after");                                       // โœ…

// Set autoEnd false for async commands
Cypress.log({ name: "login", autoEnd: false });               // โœ…

// Drive custom element state from attributes
// (so the snapshot restores it)                              // โœ…

โŒ Don’t Do This:

// Use Cypress.log in a custom command without snapshots
Cypress.log({ name: "login" }); // no time-travel tabs        // โŒ

// Forget log.end() with autoEnd false
// (the log stays open forever)                               // โŒ

// Rely on the snapshot for JS-mutated custom elements
// (they render in their initial state)                       // โŒ

Common Pitfalls

PitfallWhy It HappensFix
Custom command is a black boxNo Cypress.logAdd the log and snapshots
Log ends before async workautoEnd defaultSet autoEnd: false
Snapshot shows stale custom elementJS state not restoredUse attributes
High memory usageToo many snapshots retainedLower numTestsKeptInMemory

Real-World Examples

1. Hover restore

cy.get('[data-cy="email"]').type("a@b.com"); // hover the type entry

2. Pin a snapshot

// Click the click entry โ†’ the preview stays fixed

3. Before/after menu

// Click a click entry โ†’ the snapshot menu โ†’ before/after

4. Custom log

Cypress.log({ name: "login", autoEnd: false });

5. Before snapshot

log.snapshot("before");

6. After snapshot

log.snapshot("after");

7. Set console props

log.set({ consoleProps: () => ({ response }) });

8. End the log

log.end();

9. Error the log

log.error(new Error("failed"));

10. Memory limit

// cypress.config.ts: numTestsKeptInMemory: 10

Visual

The Hover Restore

โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”
โ”‚  COMMAND LOG                    PREVIEW                 โ”‚
โ”‚  โ”œโ”€โ”€ visit /checkout            โ”€โ”€โ–บ page after load     โ”‚
โ”‚  โ”œโ”€โ”€ get [data-cy="card"]       โ”€โ”€โ–บ input highlighted   โ”‚
โ”‚  โ”œโ”€โ”€ type 4242                  โ”€โ”€โ–บ input with value    โ”‚
โ”‚  โ””โ”€โ”€ click pay                  โ”€โ”€โ–บ page after click    โ”‚
โ”‚                                                         โ”‚
โ”‚  Hover an entry โ†’ the preview rewinds to that state     โ”‚
โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜

The Before/After Menu

โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”
โ”‚  Click a click entry โ†’ pin                              โ”‚
โ”‚  โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”           โ”‚
โ”‚  โ”‚ [before] [after]  โ—„โ”€โ”€ snapshot menu      โ”‚           โ”‚
โ”‚  โ”‚                                          โ”‚           โ”‚
โ”‚  โ”‚ before: the page before the click        โ”‚           โ”‚
โ”‚  โ”‚ after:  the page after the click         โ”‚           โ”‚
โ”‚  โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜           โ”‚
โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜

The Custom Log

โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”
โ”‚  Cypress.Commands.add("login", (email, password) => {   โ”‚
โ”‚    const log = Cypress.log({ name: "login", autoEnd: false });โ”‚
โ”‚    log.snapshot("before");                              โ”‚
โ”‚    cy.request(...).then(() => {                         โ”‚
โ”‚      log.snapshot("after");                             โ”‚
โ”‚      log.end();                                         โ”‚
โ”‚    });                                                  โ”‚
โ”‚  });                                                    โ”‚
โ”‚                                                         โ”‚
โ”‚  The login entry has before/after tabs.                 โ”‚
โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜

The Custom Element Limitation

โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”
โ”‚  <my-loader>                                            โ”‚
โ”‚    JS sets innerHTML = "" after load                    โ”‚
โ”‚                                                         โ”‚
โ”‚  Snapshot restores the initial innerHTML (the loader)   โ”‚
โ”‚  because the JS mutation is not replayed.               โ”‚
โ”‚                                                         โ”‚
โ”‚  Workaround: drive the state from attributes.           โ”‚
โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜

Summary

ItemValue
Time travelHover a Command Log entry
PinClick an entry
Before/afterSnapshot menu on an action
Custom logCypress.log({ autoEnd: false })
Snapshotslog.snapshot("before"/"after")
Console datalog.set({ consoleProps })
MemorynumTestsKeptInMemory

Key takeaways:

  • Hovering a Command Log entry restores the DOM snapshot from when that command resolved. The preview rewinds through the test’s states, and the URL is restored along with the DOM .
  • Clicking pins the snapshot. The pinned state stays fixed while the developer inspects it, and the snapshot menu switches between the before and after states for an action that changes the page .
  • Cypress.log gives a custom command the same visibility. Without it, the command is a black box in the Command Log; with it, the command has named snapshots and structured consoleProps .
  • autoEnd: false is required for async commands. The log stays open until log.end() is called, which is what allows the after snapshot to attach to the same entry .
  • The snapshot does not replay JavaScript for custom elements. A custom element whose state is set by JavaScript renders in its initial state in the snapshot, and the workaround is to drive the state from attributes .

Remember: Time travel is the Command Log plus the snapshots. Hover to rewind, click to pin, and use the before/after menu to see an action’s effect. A custom command is invisible to time travel unless it uses Cypress.log with autoEnd: false and named snapshots. The snapshot restores the DOM, not the JavaScript state; a custom element that mutates itself will not look the way it did during the test.

Was this helpful?


Stop using slow, ad-bloated tool sites! ๐Ÿคฎ

๐Ÿ”Ž Search “KandZ Tools” on Google to use many professional utilities for free.

KandZ.me is the ultimate minimalist hub for:
โœ… Finance (Mortgage, Interest, Inflation)
โœ… Tech (Base64, JSON, Dev Suite, IP)
โœ… Health (BMI, BMR, TDEE)
โœ… Productivity (Timer, Workspace, QR)

โšก๏ธ Fast & Private
๐Ÿ”’ No data leaves your device
๐Ÿ’Ž 100% Free

๐Ÿ”— Use it now: https://tools.kandz.me
๐Ÿ”– Bookmark itโ€”youโ€™ll need it later!