Cypress 11 ๐ฒ Time Travel โ Command Log Snapshots and Debugging
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
| Interaction | Effect |
|---|---|
| Hover | Restore the DOM snapshot |
| Click | Pin the snapshot |
| Snapshot menu | Switch before/after |
| Click entry | Show consoleProps in DevTools |
Cypress.log Methods
| Method | Purpose |
|---|---|
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
| Value | Effect |
|---|---|
true (default) | Ends when the command returns |
false | Stays 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
| Pitfall | Why It Happens | Fix |
|---|---|---|
| Custom command is a black box | No Cypress.log | Add the log and snapshots |
| Log ends before async work | autoEnd default | Set autoEnd: false |
| Snapshot shows stale custom element | JS state not restored | Use attributes |
| High memory usage | Too many snapshots retained | Lower 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
| Item | Value |
|---|---|
| Time travel | Hover a Command Log entry |
| Pin | Click an entry |
| Before/after | Snapshot menu on an action |
| Custom log | Cypress.log({ autoEnd: false }) |
| Snapshots | log.snapshot("before"/"after") |
| Console data | log.set({ consoleProps }) |
| Memory | numTestsKeptInMemory |
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.loggives 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 structuredconsoleProps.autoEnd: falseis required for async commands. The log stays open untillog.end()is called, which is what allows theaftersnapshot 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.
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!