Technology handbook
Cypress — End-to-End Testing & Network Control
End-to-end web testing with commands, network control, retries, fixtures and time-travel debugging.
- Topics
- 18
- Sections
- 5
Browser basics
Commands and chaining
Compose retryable commands to query, interact with and inspect the application.
- Each command yields to the next rather than returning a value to a variable.
- The chain is queued and then run, which is why a value read outside it is undefined.
- Retryability belongs to the last query in a chain, not to the whole chain.
Interacting with forms
Fill, submit and validate forms through the same controls a user operates.
- Fields are filled and submitted through the same controls a person operates.
- Typing fires the events the application listens for, which setting a value does not.
- A disabled or covered control fails the action rather than silently doing nothing.
cy.get and querying
Query application controls with retryable Cypress commands and stable selectors.
- Controls are queried with retryable commands and selectors that survive a restyle.
- A selector tied to a styling class breaks on a change that alters nothing functional.
- A dedicated test attribute is the selector least likely to move.
Command queue
Understand Cypress's queued commands and why values are yielded rather than returned synchronously.
- Commands are enqueued and executed later, not run where they are written.
- A value assigned inside a callback is not readable on the next line.
- Mixing synchronous code into the chain runs it before any command does.
Aliases
Name elements, requests and data for readable later assertions.
- Elements, requests and data are named for use in a later assertion.
- An alias to an element re-queries rather than holding a stale node.
- An alias defined in one hook is not visible from another spec.
Cross-origin testing
Handle origin changes explicitly with cy.origin and safe test setup.
- An origin change is handled explicitly with cy.origin.
- Code inside the block runs in the other origin and cannot see outer variables.
- Crossing origins without it stops the test at the boundary.
Test design
Assertions
Assert on the rendered browser state so Cypress can retry through asynchronous updates.
- Assertions describe rendered browser state, so Cypress can retry until it holds.
- A retried assertion is what removes the arbitrary wait an async update would need.
- An assertion with a side effect is re-run on every retry.
Component testing
Mount a component in a real browser and assert on its rendered interactions.
- A component is mounted in a real browser and asserted on directly.
- It runs the real styles and layout, which a virtual DOM renderer does not.
- Mounting bypasses routing and data loading, so those stay untested here.
Network control
Network interception
Observe or stub requests with cy.intercept while keeping the tested contract visible.
- cy.intercept observes or replaces a request while leaving the contract visible in the test.
- Intercepting by route keeps the test readable when the call site moves.
- An intercept registered after the request is made never matches it.
wait for network
Alias and await requests instead of sleeping for an arbitrary duration.
- A request is aliased and awaited instead of sleeping for a guessed duration.
- Waiting on the request ties the test to the event rather than to the clock.
- A fixed sleep is both slower than needed and still occasionally too short.
Request stubbing
Control success, latency and failure responses at the HTTP boundary.
- Success, latency and failure are controlled at the HTTP boundary.
- Stubbing an error path is how a failure state is tested at all.
- A stubbed response that the real server would never send tests nothing.
Configuration
Fixtures and test data
Load deterministic data and reset state so tests do not depend on execution order.
- Deterministic data is loaded and state reset so order never decides the result.
- A test that depends on a previous test's leftovers fails alone and passes in a suite.
- Resetting before rather than after is what survives a crashed run.
Fixtures
Load reusable data and keep test setup explicit and isolated.
- Reusable data is loaded from a file so setup is explicit rather than implied.
- A fixture is shared, so editing it changes every test that loads it.
- A fixture drifting from the real response makes a green test meaningless.
Custom commands
Extract repeated workflows into typed commands without hiding important assertions.
- Repeated workflows are extracted into typed commands of their own.
- Hiding an assertion inside a command removes it from the test that needed it.
- A command that logs in through the interface repeats that cost in every test.
cy.session
Cache authenticated browser sessions safely to reduce repeated login work.
- An authenticated session is cached and restored between tests.
- Restoring a session skips a repeated sign-in without skipping the sign-in test.
- The cache key must include whatever makes one session differ from another.
Debugging
Debugging and retries
Use command logs, snapshots and controlled retries to diagnose flaky browser behavior.
- Command logs, snapshots and retries show what the page looked like at each step.
- Time travel is what turns a failure message into a visible cause.
- Retries hide a real race unless the underlying timing is then fixed.
Screenshots and videos
Capture visual evidence automatically when CI tests fail.
- Visual evidence is captured automatically when a run fails.
- A recording of the failing run is what makes a CI-only failure diagnosable.
- Artifacts accumulate, so retention has to be bounded.
Flake detection
Use retries as diagnostic evidence while fixing the timing or state leak underneath.
- Retries are read as evidence of a race rather than as a fix for it.
- A test that passes only on retry is reporting a real timing or state leak.
- Leaving retries on without investigating converts a bug into noise.