Cypress

The shop’s twelve journeys in Cypress on one screen — native, or a workaround

The question a team brings to this page is whether Cypress fits its product, and the honest way to answer it is journey by journey. Below are the twelve journeys from the End-to-end testing page — the same online shop — as the shop would write them in Cypress. The third column says what Cypress needs to do each one; the fourth gives a verdict. Native means the ordinary APIAPIApplication Programming Interface — contract between programsThe rules one program follows to call another: which requests it may send, in what shape, and what comes back. To the caller it is a contract — everything behind it stays a black box, which is exactly what lets the other side be rewritten without breaking you.Full article →All terms does it. A workaround means it can be done, with a setting, a separate block or an experimental flag, and with a cost the row names. Later sections cite the journeys by number.

A team can avoid the iframeiframea page inside a pageAn HTML element that embeds another document inside a page — a payment form, a video, a sign-in box. When it comes from another origin, the browser walls it off from the page around it, which is why a test tool may or may not be able to type into it.All terms by paying through the provider’s API with a test token instead of typing a card. The journey then runs everywhere, and it stops proving the seam it exists for — row 4 on the End-to-end testing page, that the total on the screen is the amount the provider is asked to charge. That is the shape of most Cypress decisions. The tool offers a way around each edge, and each way around moves the test a little further from what a customer does.

The test lives in the tab — and the four trade-offs Cypress calls permanent

Most browser automation is remote control: the test is a program somewhere else that sends instructions to a browser and reads answers back. Cypress inverts it. Your application is loaded into an iframe, the test is loaded beside it in the same tab, and both run on the same JavaScript event loopevent loopone thread taking turnsA loop on a single thread that takes finished work from a queue — a reply that has arrived, a timer that has fired — and runs its callback, one at a time. It lets one thread juggle thousands of waits, and it stops for everyone while any single callback runs.Full article →All terms. There is no wire between the test and the page, so the test can reach into the application the way a script on the page could. Anything outside the browser — a file, a database, the test inbox — goes through a second, Node.js process that the test talks to with cy.task().

Since Cypress 16, released on 1 September 2026, one part of that picture moved. In Chrome, Chromium and Edge, Cypress now intercepts test traffic on the browser’s own network instead of routing it through its proxy, so the application is tested over HTTPHTTPHyperText Transfer Protocol — the protocol of the webThe protocol browsers and servers talk in: the client sends a method and an address, the server answers with a status code and a body. It keeps no memory between requests — every request stands alone, which is why anything that must be remembered is carried explicitly.All terms/2 and HTTP/3 with its real certificate. Firefox, WebKit and Electron still take the old path through the proxy. The same cy.intercept() therefore runs over two different network paths depending on the browser, and a few of its behaviours differ between them.

Cypress’s own documentation lists the costs of living in the tab under the heading “Trade-offs”, and it calls four of them permanent. They are worth reading in its words, because they are not configuration problems a later version will remove.

The same page lists three “temporary” ones that Cypress hopes to address: there is no cy.hover(), there is no support for native or mobile events, and iframe support “is somewhat limited” — same-origin frames can be queried, cross-origin ones cannot. The last of those is the one that decided four of the shop’s verdicts.

Commands are queued, not run — why `await`, `try/catch` and `if` misbehave

The consequence people meet first is that Cypress commands are not what they look like. The documentation puts it plainly: commands “don’t do anything at the moment they are invoked, but rather enqueue themselves to be run later.” A line asking for an element does not fetch it and does not return it. It appends a command to a queue that starts running only after the whole test function has finished. So a value cannot be assigned from a command into a variable and used on the next line: when the next line is read, nothing has run yet.

The queue also explains the debugging experience people choose Cypress for. Because the runner executes each command itself, inside the page, it keeps a snapshot of the page for every command, and the Command Log lets you hover over a step and see the page as it was at that moment. Commands run one after another, never in parallel, and the documentation calls that an intentional decision rather than a technical limit: the point is a test that behaves identically from one run to the next.

Retry-ability since Cypress 12: a chain of queries retries from the top

Cypress does not wait a fixed time for the page. It splits commands into kinds and retries the ones that only read. Queries — cy.get(), .find(), .contains(), .eq() and the like — link up with the assertions after them, and if an assertion fails, Cypress runs the whole chain of queries again from the top, for up to four seconds by default. Actions such as .click() and .type() are not queries: they wait until the element is actionable, re-running the queries before them while they wait, and then act once.

Advice written before December 2022, and much that still copies it, says the opposite: that only the last query before an assertion retries, so a list that re-renders leaves the test holding a detached element. That was Cypress up to version 11. Cypress 12 changed it, and the rule that replaced it has one boundary worth learning. An assertion in the middle of a chain locks the subject once it passes; queries after it retry from that locked subject, not from the top. If the page re-renders between the two assertions, the locked element is gone and the test fails.

Isolation, sessions and the Node side

Since Cypress 12, test isolation is on by default. Before each test Cypress visits about:blank and clears cookiescookiedata the browser sends backA small piece of data a website asks the browser to keep and send back with every request to that site — which is how a server remembers that you are signed in. Because the browser attaches it automatically, even to a request another site triggered, a session cookie needs its flags set and an anti-forgery check on the server.All terms, localStorage and sessionStorage in all domains, so one journey does not inherit another’s state. The difference from Playwright is worth knowing exactly. Playwright gives each test a new browser contextbrowser contextan isolated profile in one browserAn isolated session inside one running browser, with its own cookies, storage and permissions, as Playwright uses it. Opening one takes milliseconds rather than a browser launch, so each test can start as a fresh user, and two contexts in one test are two users who cannot see each other.Full article →All terms, a whole new profile. Cypress cleans the same browser between tests, and its documentation says what it leaves: “IndexedDB and other browser storage mechanisms are not cleared.” A shop that kept a guest basket in IndexedDB would have to clear it itself before journey 11.

Reaching into the application deserves a warning of its own. Because the test shares the page, it can call the application’s functions, read its store or spy on a method. That is excellent for arranging state that would take six clicks to reach, and poor for asserting behaviour: a check written against internals is coupled to how the feature is built, so a refactor that changes nothing a customer sees breaks the suite. Arrange through the inside; assert through what a person sees.

Parallel by spec file, orchestrated by Cypress Cloud

Cypress runs one browser at a time per machine, so a faster suite means more machines. Its parallelization is file-based: whole spec files are handed to machines, never single tests. The handing out is done by Cypress Cloud. Each machine runs cypress run --record --parallel, Cloud estimates every spec’s duration from earlier runs, and it gives each machine one spec at a time until none are left. Without Cloud a team can still split specs across machines by hand, but the split is static and does not learn.

Cloud is also where a CI failure is debugged. Test Replay, added in Cypress 13 in August 2023, records the DOM, network requests and console of each test in CI and lets a developer step through the run in the browser afterwards; the documentation says it is available on all Cloud plans at no extra cost, subject to usage limits. Video recording has been off by default since the same release. Both facts point one way: the parts of the Cypress experience that matter most in CI — balancing and replay — are a hosted service, which is a choice to make with open eyes, not a detail to discover.

Four changes underneath working suites

Each of these is a dated change published by Cypress itself. None is a defect. Each moved something a suite had come to rely on, and the third column is what made the move an afternoon instead of a week.

Where it does not help, and how it compares

Living inside the tab is a genuine architectural commitment, and every limit below follows from it. None is a scandal; each is worth knowing before choosing, because a later version will not remove it.

• A cross-origin iframe — a payment form, an embedded sign-in — cannot be automated without switching off web security, and that works only in Chrome-family browsers.
• One browser at a time, so two users acting together — a live chat, an agent watching a customer’s screen — is stubbed on one side rather than tested.
• WebKit is experimental and arrives through Playwright’s WebKit build; it is not Safari either.
• Parallelism is by spec file across machines, and balancing it well is a Cloud service.
• Native dialogs, file pickers and anything at the level of the operating system are outside the page, and so outside reach.
• cy.prompt(), in beta, writes steps from plain English and marks a step that recovered as “Self-healed”. A healed step is a changed test, and it deserves the review any other change gets.

Anti-patterns worth naming

• Waiting a fixed number of milliseconds — the habit the retry model exists to make unnecessary.
• Signing in through the interface at the start of every test, five seconds a case to prove what cy.session() proved once.
• Conditional test logic based on what is on the page, which produces a test that cannot fail because it adapts to anything.
• Stubbing every request until the suite tests no integration at all, then reporting it as end-to-end coverage.
• One spec file per feature, so the longest feature sets the floor of every run.
• chromeWebSecurity: false switched on for the whole suite to reach one iframe, so every journey quietly stops running in Firefox and WebKit.

When to use it

Related pages

• QAPlaywrightPlaywright is an open-source browser automation library and test runner from Microsoft that drives Chromium, Firefox and WebKit from outside the browser. The page opens with the twelve journeys from End-to-end testing written in Playwright — the mechanism each one leans on, and the config that runs them in about four minutes — then covers the one connection everything follows from, the browsers it actually runs, auto-waiting, contexts and workers, what a test can reach besides the page, traces and retries, four changes underneath working suites, and where it does not help.
• QASeleniumSelenium is an open-source set of browser automation tools built on W3C WebDriver, a standard that browser vendors implement in drivers of their own. The page opens with the twelve journeys from End-to-end testing written in Selenium — who supplies each — and the one run only Selenium can add to the shop’s suite: the browsers customers actually install, Safari on an iPhone included. Then the protocol and its drivers, waiting, sessions and the lane one Mac sets, WebDriver BiDi, the grid and its open door, five changes underneath working suites, and where it does not help.
• QAEnd-to-end testingEnd-to-end testing walks a business process through the assembled system from start to finish, the way a customer would, in conditions close to production. The page opens with one shop’s whole suite — twelve journeys, the seam only each one proves, and what is real and what is replaced — then covers what no lower level can prove, the shapes a portfolio takes, what a red journey costs, how to choose journeys and keep them trustworthy, and three failures where a test stopped one step short.