Cypress 01 ๐ฒ Why Cypress โ In-browser execution & time-travel debugging
Cypress runs inside the browser, in the same event loop as the application under test. That architectural choice is the source of its defining features: the time-travel debugger that lets you hover over a command and see the DOM as it was at that moment, the automatic waiting that retries assertions until they pass, and the network stubbing that intercepts requests without a proxy. It is also the source of its defining limitations: no multi-tab support, no native events, and a JavaScript-only test runner that executes in the same process as the app.
This chapter covers the in-browser architecture, the time-travel debugger, and the trade-offs that architecture produces. The sections that follow walk through the execution model, the debugging workflow, and the limitations that teams should understand before choosing Cypress over Playwright or Selenium.
Key point: Cypress executes the test code and the application code in the same browser event loop, which enables time-travel debugging and automatic waiting but imposes real limits on multi-tab, multi-origin, and native-event testing.
Why Cypress exists
The flakiness problem. A Selenium test that clicks a button before it is visible fails, and the fix is a Thread.sleep or a WebDriverWait that the test author has to guess. Cypress’s commands are queued and retried: cy.get('.btn').click() waits for the element to exist, be visible, and be actionable before clicking, and cy.get('.msg').should('contain', 'Saved') retries the assertion until it passes or the timeout expires . The test author writes the command, not the wait.
The debugging problem. A Selenium test failure produces a stack trace and a screenshot. Cypress produces a command log: every command is listed in a sidebar, and hovering over a command snapshots the DOM as it was at the moment that command ran. The developer can inspect the element, see its CSS, and read the console output from that point in time . This is the “time-travel” feature, and it is the reason many teams adopt Cypress despite its limitations.
The network problem. Cypress can intercept and stub network requests with cy.intercept(), which lets a test run against a predictable API without a backend or with a specific error state. The interception is built into the runner, not bolted on with a proxy, because the runner is already in the browser and can hook XMLHttpRequest and fetch .
a. The in-browser execution model
Cypress has a Node.js process and a browser process. The Node process starts the browser, serves the test runner, and proxies network requests; the browser process runs the application and the test code in the same event loop. The test code is not a separate script that drives the browser from outside; it is loaded into the same page as the application, and cy commands execute in that context.
// The test runs inside the browser, alongside the app
describe("login", () => {
it("signs in", () => {
cy.visit("/login");
cy.get('[data-testid="email"]').type("user@example.com");
cy.get('[data-testid="password"]').type("password123");
cy.get('button[type="submit"]').click();
cy.url().should("include", "/dashboard");
});
});
The same-process execution is why Cypress can see the application’s network requests, why it can stub them, and why the command log can snapshot the DOM. It is also why the test cannot open a second tab: the browser’s tab model is outside the event loop the test runs in. The multi-tab limitation is not a missing feature; it is a consequence of the architecture.
The architecture also means the test code and the app share the same JavaScript realm. A global variable set by the app is visible to the test, and a test that modifies window affects the app. This is convenient for some debugging and a source of cross-test leakage if the state is not reset.
b. The command log and time-travel debugging
The command log is the sidebar that lists every command in the order it ran. Each entry shows the command name, the selector or value, and the result. Hovering over an entry restores the DOM snapshot from that moment and highlights the element the command targeted .
cy.get('[data-testid="email"]') // log: get, found 1 element
.type("user@example.com") // log: type
.should("have.value", "user@example.com"); // log: assert
The snapshot is the feature that separates Cypress from a console-driven test runner. When a test fails, the developer does not need to reproduce the failure to inspect the DOM at the point of failure; the snapshot is already there. The cy.debug() command pauses the test at that point and opens the browser’s debugger, and cy.pause() pauses the command queue for step-through execution .
The time-travel is limited to the DOM. It does not rewind the application’s JavaScript state, so a test that depends on a variable set before the snapshot does not see the variable’s past value. The snapshot shows the DOM, the console output, and the network requests from that moment, not the full application state.
c. The trade-offs the architecture imposes
The in-browser model produces three limitations that a team should weigh before adopting Cypress.
Multi-tab is not supported. The test cannot open a second browser tab or window, because the test runs inside one tab’s event loop. A workflow that requires a second tabโa payment flow that opens a new window, an OAuth redirect that opens a popupโcannot be tested in Cypress without workarounds .
Multi-origin is restricted. Cypress can visit different origins, but the test loses the application’s state when it does, and the commands between origins are limited. The cy.origin() command exists to handle cross-origin flows, but the ergonomics are different from a runner that drives the browser from outside .
Native events are limited. Cypress dispatches synthetic events, not native OS-level events. A test that needs to simulate a real file drop, a native drag-and-drop, or a browser-level keyboard shortcut cannot do so reliably. The limitation is inherent to running inside the browser’s JavaScript context .
The contrast with Playwright is the context model: Playwright drives the browser from outside, so it can create multiple contexts, visit multiple origins, and dispatch events through the browser’s protocol. The trade-off is that Playwright does not have the in-browser command log, and its debugging is the trace viewer rather than the hover-to-snapshot log.
Complete Example Session
// ============================================
// PART 1: THE TEST
// ============================================
// cypress/e2e/login.cy.js
describe("login", () => {
it("signs in and shows the dashboard", () => {
cy.visit("/login");
// Each command is logged; hovering shows the DOM snapshot
cy.get('[data-testid="email"]').type("user@example.com");
cy.get('[data-testid="password"]').type("password123");
cy.get('button[type="submit"]').click();
// Assertion retries until the URL matches or times out
cy.url().should("include", "/dashboard");
cy.get("h1").should("contain", "Dashboard");
});
});
// ============================================
// PART 2: THE TIME-TRAVEL LOG
// ============================================
// visit /login
// get [data-testid="email"] found 1 element
// type user@example.com
// get [data-testid="password"] found 1 element
// type password123
// get button[type="submit"] found 1 element
// click
// url should include /dashboard passed
// get h1 found 1 element
// should contain Dashboard passed
//
// Hovering any entry restores the DOM snapshot at that moment.
// ============================================
// PART 3: THE LIMITATION
// ============================================
// A test that needs a second tab:
// cy.window().then((win) => win.open("/other")); // does not work
// The new tab is outside the test's event loop.
The parts covered the test with its commands, the command log that enables time-travel, and the multi-tab limitation that the architecture imposes.
Quick Reference
Cypress vs Playwright
| Aspect | Cypress | Playwright |
|---|---|---|
| Execution | In-browser, same event loop | Out-of-browser, protocol |
| Debugging | Command log, time-travel | Trace viewer |
| Multi-tab | Not supported | Supported via contexts |
| Multi-origin | cy.origin() workaround | Native |
| Native events | Synthetic only | Protocol-level |
| Language | JavaScript/TypeScript only | Multiple via bindings |
| Auto-waiting | Yes (commands + assertions) | Yes (actions + assertions) |
Debugging Commands
| Command | Effect |
|---|---|
| Hover log entry | Restore DOM snapshot |
cy.debug() | Pause at command, open debugger |
cy.pause() | Pause the command queue |
cy.log() | Add a message to the command log |
Known Limitations
| Limitation | Cause |
|---|---|
| No multi-tab | Same event loop |
| Multi-origin restrictions | Same-origin policy |
| No native events | Synthetic dispatch |
| JavaScript only | Test runs in the browser |
Best Practices
โ Do This:
// Use the command log for debugging
cy.get('[data-testid="submit"]').click(); // โ
// Use cy.origin for cross-origin flows
cy.origin("https://auth.example.com", () => { ... }); // โ
// Use data-testid for stable selectors
cy.get('[data-testid="email"]'); // โ
// Use cy.intercept for network stubbing
cy.intercept("GET", "/api/users", { fixture: "users.json" }); // โ
โ Don’t Do This:
// Try to open a second tab
cy.window().then((win) => win.open("/other")); // not supported // โ
// Use hard-coded waits
cy.wait(2000); // use assertions instead // โ
// Rely on CSS classes for selectors
cy.get(".btn-primary"); // breaks on style refactor // โ
// Assume native events work
cy.get("input").trigger("drop"); // synthetic, not native // โ
Common Pitfalls
| Pitfall | Why It Happens | Fix |
|---|---|---|
| Multi-tab test fails | Architecture limitation | Use Playwright or a workaround |
| Cross-origin state lost | Origin isolation | Use cy.origin() |
| Flaky test | Hard-coded wait | Use retrying assertions |
| Selector breaks on refactor | CSS class selector | Use data-testid |
Real-World Examples
1. Visit and assert
cy.visit("/");
cy.title().should("include", "My App");
2. Type into a field
cy.get('[data-testid="email"]').type("a@b.com");
3. Retrying assertion
cy.get(".message").should("contain", "Saved");
4. Network stub
cy.intercept("GET", "/api/users", { fixture: "users.json" });
5. Cross-origin
cy.origin("https://auth.example.com", () => {
cy.get("#login").click();
});
6. Debug
cy.get(".btn").debug().click();
7. Pause
cy.pause();
8. Custom command
Cypress.Commands.add("login", (email, password) => { ... });
9. Fixture
cy.fixture("user.json").then((user) => { ... });
10. Screenshot
cy.screenshot("after-login");
Visual
The Two-Process Architecture
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ NODE PROCESS โ
โ โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ โ
โ โ Starts browser, serves runner, proxies โ โ
โ โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ โ
โ โ โ
โ โผ โ
โ BROWSER PROCESS โ
โ โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ โ
โ โ Application + test code, same event loop โ โ
โ โ cy commands execute here โ โ
โ โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ โ
โ โ
โ Same process โ can stub network, snapshot DOM โ
โ Same process โ cannot open a second tab โ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
Time-Travel Debugging
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ COMMAND LOG โ
โ โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ โ
โ โ visit /login โ โ
โ โ get [data-testid="email"] โโโ hover โ โ
โ โ type user@example.com โ โ
โ โ click button[type="submit"] โ โ
โ โ url should include /dashboard โ โ
โ โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ โ
โ โ โ
โ โผ โ
โ Hover restores the DOM snapshot from that moment โ
โ Inspect the element, CSS, console at that point โ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
Architecture Trade-offs
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ ENABLED LIMITED โ
โ โโโโโโโโโโโโโโโโโโโโโโโโ โโโโโโโโโโโโโโโโโโโโโโโโ โ
โ โ Time-travel log โ โ Multi-tab โ โ
โ โ Network stubbing โ โ Multi-origin โ โ
โ โ Auto-waiting โ โ Native events โ โ
โ โ Same-process debug โ โ Non-JS test languages โ โ
โ โโโโโโโโโโโโโโโโโโโโโโโโ โโโโโโโโโโโโโโโโโโโโโโโโ โ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
Summary
| Item | Value |
|---|---|
| Execution model | In-browser, same event loop |
| Debugging | Command log, time-travel snapshots |
| Auto-waiting | Commands and assertions retry |
| Network stubbing | cy.intercept() |
| Multi-tab | Not supported |
| Multi-origin | cy.origin() workaround |
| Native events | Synthetic only |
| Language | JavaScript/TypeScript |
Key takeaways:
- Cypress runs in the browser, not outside it. The test code and the application share an event loop, which is what enables the command log, the network stubbing, and the automatic waiting .
- Time-travel debugging is the defining feature. Hovering over a command in the log restores the DOM snapshot from that moment, so the developer can inspect the page at the point of failure without reproducing it .
- The architecture imposes real limits. No multi-tab, restricted multi-origin, and synthetic events are consequences of running inside the browser’s JavaScript context, not missing features that will arrive later .
- The command log is not the trace viewer. Cypress shows the DOM at each step; Playwright records a trace that includes network, console, and snapshots. The two serve similar purposes with different interfaces.
- The choice against Cypress is a choice about architecture. A team that needs multi-tab or native events chooses Playwright or Selenium; a team that values the in-browser debugging experience accepts the limits.
Remember: Cypress’s value is the in-browser execution, and its cost is the same thing. The command log and time-travel debugging come from running in the same event loop as the app; the multi-tab and native-event limitations come from the same place. Choose Cypress when the debugging experience is the priority and the application’s flows fit within a single tab and a single origin. Choose Playwright when the flows cross those boundaries, and accept that the debugging is a trace viewer rather than a hoverable log.
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!