Cypress architecture (runs in browser) - Deep Dive

Overview - Cypress architecture (runs in browser)

What is it?

Cypress is a tool for testing web applications by running tests directly inside the browser. It controls the browser and interacts with the web page just like a user would, but automatically and with precise control. Unlike other tools that run outside the browser, Cypress runs in the same environment as the app, giving it unique access to the page and its code. This helps testers see exactly what happens during a test and catch problems early.

Why it matters

Running tests inside the browser solves many problems like timing issues and hard-to-debug errors that happen when tests run separately from the app. Without Cypress's architecture, tests might miss real user problems or be flaky and unreliable. This means developers spend more time fixing tests than fixing the app. Cypress makes tests faster, clearer, and more trustworthy, improving software quality and developer confidence.

Where it fits

Before learning Cypress architecture, you should understand basic web testing concepts and how browsers work. After this, you can learn how to write Cypress tests, use its commands, and integrate it into development workflows. Later, you might explore advanced topics like network stubbing, custom commands, and continuous integration with Cypress.

Mental Model

Core Idea

Cypress runs tests inside the browser alongside the app, giving it direct control and visibility to test web pages like a real user but with automation power.

Think of it like...

Imagine testing a car by sitting inside it and controlling the steering wheel, pedals, and dashboard yourself, instead of watching from outside. You can feel every movement and fix problems immediately because you are inside the action.

┌───────────────────────────────┐
│         Cypress Test Runner    │
│  (Runs inside browser window) │
│                               │
│  ┌───────────────┐            │
│  │ Web Application│           │
│  │  (Your app)    │           │
│  └───────────────┘            │
│                               │
│  Direct access to DOM & JS    │
│  Controls app like a user     │
└───────────────────────────────┘
            ↑
            │
┌───────────────────────────────┐
│      Cypress Node Process      │
│  (Runs outside browser)        │
│  Manages test files, reports, │
│  and browser launching         │
└───────────────────────────────┘

Build-Up - 7 Steps

1

Foundation

What is Cypress and its purpose

Concept: Introduce Cypress as a browser-based testing tool for web apps.

Cypress is a tool that helps developers test their websites by running automated tests inside the browser. It simulates user actions like clicking buttons and typing text, then checks if the app behaves correctly. This helps catch bugs early and ensures the app works as expected.

Result

Learners understand Cypress is a tool that runs tests inside the browser to check web apps.

Knowing Cypress runs tests inside the browser sets it apart from other tools and explains its unique advantages.

2

Foundation

Basic browser environment for testing

Concept: Explain how browsers load and run web pages and scripts.

Browsers load web pages by fetching HTML, CSS, and JavaScript. They build a page structure called the DOM (Document Object Model) and run scripts to make pages interactive. Testing tools need to interact with this environment to simulate user actions and check results.

Result

Learners grasp the browser's role in running web apps and why tests must interact with the DOM and scripts.

Understanding the browser environment is essential to see why running tests inside it gives better control and accuracy.

3

Intermediate

Cypress runs inside the browser window

🤔Before reading on: Do you think Cypress runs tests outside the browser or inside it? Commit to your answer.

Concept: Cypress executes test code inside the same browser window as the app, sharing the environment.

Unlike many testing tools that control the browser from outside, Cypress injects its test code directly into the browser page. This means tests run in the same JavaScript environment as the app, allowing Cypress to see everything the app does and control it precisely.

Result

Learners realize Cypress's tests run inside the browser, not externally.

Knowing Cypress shares the browser environment explains why it can access app internals and avoid timing issues common in other tools.

4

Intermediate

How Cypress controls the app and DOM

🤔Before reading on: Do you think Cypress controls the app by simulating user events or by modifying code directly? Commit to your answer.

Concept: Cypress interacts with the app by controlling the DOM and triggering real browser events.

Cypress uses JavaScript commands to find elements on the page and simulate user actions like clicks and typing. Because it runs inside the browser, these actions are real browser events, not just code simulations. This makes tests more reliable and closer to real user behavior.

Result

Learners understand Cypress controls the app by triggering real browser events inside the page.

Understanding Cypress uses real events inside the browser clarifies why tests are more accurate and less flaky.

5

Intermediate

Role of Cypress Node process outside browser

Concept: Explain the separate Node.js process that manages test files and browser launching.

Cypress has two parts: the test runner inside the browser and a Node.js process outside. The Node process reads your test files, starts the browser, and shows test results. It communicates with the browser to coordinate running tests but does not control the app directly.

Result

Learners see Cypress has a split architecture: browser for tests, Node for management.

Knowing the split helps understand how Cypress balances control and reporting between browser and outside processes.

6

Advanced

Automatic waiting and retry mechanism

🤔Before reading on: Do you think Cypress requires manual waits or automatically waits for elements? Commit to your answer.

Concept: Cypress automatically waits for elements and commands to complete before moving on.

Because Cypress runs inside the browser, it can watch for changes in the DOM and network. It automatically retries commands like finding elements until they appear or time out. This removes the need for manual waits and reduces flaky tests caused by timing issues.

Result

Learners understand Cypress's automatic waiting improves test stability.

Knowing Cypress handles waiting internally explains why tests are simpler and less error-prone.

7

Expert

Security and sandboxing in Cypress architecture

🤔Before reading on: Do you think Cypress runs test code with full access to the app's JavaScript or in a restricted sandbox? Commit to your answer.

Concept: Cypress runs test code with full access to the app's JavaScript context but isolates it to prevent interference.

Cypress injects its scripts into the app's page, sharing the same JavaScript context. This allows deep inspection and control but raises security concerns. Cypress uses a controlled environment and sandboxing techniques to isolate test code from external interference and protect the app's integrity during tests.

Result

Learners appreciate the balance Cypress strikes between access and security.

Understanding Cypress's sandboxing reveals how it safely runs powerful tests without risking app stability or security.

Under the Hood

Cypress architecture consists of two main parts: a Node.js process running outside the browser and a test runner running inside the browser window. The Node process manages test files, launches browsers, and handles reporting. The test runner injects JavaScript into the browser page, running tests in the same environment as the app. This allows Cypress to directly access the DOM, listen to network requests, and trigger real browser events. Communication between Node and browser happens over a WebSocket connection, coordinating test execution and results.

Why designed this way?

Cypress was designed to solve problems with traditional testing tools that run outside the browser and communicate remotely, causing timing issues and flaky tests. Running tests inside the browser gives Cypress direct access to the app's internals and real user events, making tests more reliable and easier to debug. The split architecture allows Cypress to manage tests and browsers efficiently while keeping test execution close to the app. Alternatives like Selenium run tests externally, which can cause synchronization problems and harder debugging.

┌───────────────────────────────┐          ┌───────────────────────────────┐
│       Cypress Node Process     │◄────────►│      Browser with Test Runner  │
│  - Reads test files            │          │  - Runs tests inside browser   │
│  - Launches browser            │          │  - Injects test code & app JS  │
│  - Shows test results          │          │  - Controls DOM & triggers UI │
└───────────────────────────────┘          └───────────────────────────────┘
                 ▲                                         ▲
                 │                                         │
          WebSocket communication                   Shared JS environment
                 │                                         │
                 ▼                                         ▼
        Test orchestration                      Direct access to app internals

Myth Busters - 4 Common Misconceptions

Quick: Do you think Cypress runs tests outside the browser controlling it remotely? Commit to yes or no before reading on.

Common Belief: Cypress runs tests outside the browser and controls it remotely like Selenium.

Reality: Cypress runs tests inside the browser window, sharing the same JavaScript environment as the app.

Why it matters: Believing tests run externally leads to misunderstanding Cypress's speed and reliability advantages.

Quick: Do you think Cypress requires manual waits to handle slow page loads? Commit to yes or no before reading on.

Common Belief: Testers must add manual waits or sleeps to handle asynchronous page behavior in Cypress.

Reality: Cypress automatically waits and retries commands until elements appear or actions complete, reducing flaky tests.

Why it matters: Misunderstanding this causes unnecessary waits, slowing tests and complicating code.

Quick: Do you think Cypress can test apps without a real browser? Commit to yes or no before reading on.

Common Belief: Cypress can run tests without launching a real browser, like headless simulation only.

Reality: Cypress always runs tests inside a real browser instance, either headed or headless mode, to interact with the actual environment.

Why it matters: Thinking otherwise leads to confusion about Cypress's capabilities and test accuracy.

Quick: Do you think Cypress test code runs isolated from the app's JavaScript? Commit to yes or no before reading on.

Common Belief: Cypress test code runs in a separate sandbox and cannot access the app's internal JavaScript variables.

Reality: Cypress test code runs in the same JavaScript context as the app, allowing deep inspection and control.

Why it matters: Not knowing this limits understanding of Cypress's powerful debugging and testing features.

Expert Zone

1

Cypress's ability to run inside the browser allows it to capture network requests and responses in real time, enabling advanced stubbing and spying features.

2

The split architecture means that while tests run in the browser, the Node process can restart browsers or rerun tests without losing state, improving developer experience.

3

Cypress's automatic waiting is based on retrying commands until success or timeout, which differs from traditional explicit waits and requires a different mindset when writing tests.

When NOT to use

Cypress is not suitable for testing non-browser environments like mobile apps or APIs without a browser. For cross-browser testing beyond Chromium-based browsers, tools like Selenium or Playwright may be better. Also, Cypress cannot test multiple tabs or browser windows simultaneously, so tests requiring multi-window interactions need alternative approaches.

Production Patterns

In production, Cypress tests are integrated into continuous integration pipelines to run on every code change. Teams use Cypress Dashboard for test analytics and parallelization. Tests often use custom commands to reuse common actions, and network stubbing to isolate tests from backend dependencies. Cypress's architecture allows fast feedback loops by running tests locally in headed mode during development and headless mode in CI.

Connections

Playwright architecture

Similar pattern of browser automation but Playwright runs tests outside the browser controlling it remotely.

Comparing Cypress and Playwright architectures helps understand tradeoffs between inside-browser and outside-browser test execution.

Event-driven programming

Cypress relies heavily on event listening and reacting inside the browser environment.

Understanding event-driven programming clarifies how Cypress detects changes and triggers retries automatically.

Human-computer interaction (HCI)

Cypress simulates real user interactions inside the browser to test usability and behavior.

Knowing HCI principles helps testers write Cypress tests that mimic real user actions more effectively.

Common Pitfalls

#1 Trying to control multiple browser tabs or windows in Cypress tests.

Wrong approach:

cy.visit('page1.html')
cy.get('a[target="_blank"]').click()
cy.switchToWindow('new-tab')
cy.get('#element').should('be.visible')

Correct approach:

Cypress does not support multiple tabs; instead, test each page separately or simulate multi-page flows within a single tab.

Root cause:

Misunderstanding Cypress's single-browser-tab limitation leads to writing unsupported test code.

#2 Adding manual waits or sleeps to handle asynchronous behavior.

Wrong approach:

cy.get('#button').click()
cy.wait(5000)
cy.get('#result').should('contain', 'Success')

Correct approach:

cy.get('#button').click()
cy.get('#result').should('contain', 'Success')

Root cause:

Not trusting Cypress's automatic waiting causes unnecessary delays and brittle tests.

#3 Trying to access app internals from outside the browser process.

Wrong approach:

In Node process: console.log(window.someAppVariable);

Correct approach:

Access app variables inside test code running in browser context using cy.window().then(win => { /* use win.someAppVariable */ })

Root cause:

Confusing the separation between Node process and browser context leads to incorrect access attempts.

Key Takeaways

Cypress runs tests inside the browser, sharing the same environment as the web app for precise control and visibility.

Its architecture splits responsibilities between a Node.js process managing tests and a browser process running test code.

Automatic waiting and retrying commands inside the browser reduce flaky tests and simplify test writing.

Cypress's design balances deep access to app internals with sandboxing to maintain security and stability.

Understanding Cypress's architecture helps write better tests and use its features effectively in real projects.