# Main Concepts in Cypress for Developers: Core Architecture and Package Structure

> Explore the main concepts in Cypress for developers. Understand the core architecture including Driver, Server, Runner, and Proxy systems for efficient E2E testing.

- Repository: [Cypress.io/cypress](https://github.com/cypress-io/cypress)
- Tags: architecture
- Published: 2026-06-21

---

**The main concepts in Cypress for developers center on four primary architectural layers: the Driver (browser-side command execution), the Server (Node process managing proxies and plugins), the Runner (Electron UI coordinator), and the Proxy/Net-Stubbing system for network interception, all communicating via a socket layer to enable automatic retries, real-time reloading, and cross-origin testing.**

Cypress is organized as a monorepo under `cypress-io/cypress` that packages these tightly-coupled systems into discrete modules. Understanding how these components interact is essential for extending Cypress, debugging test failures, or optimizing CI/CD pipelines.

## The Core Architectural Components

Cypress operates as a distributed system where browser automation logic runs separately from Node.js infrastructure, coordinated through an event-driven socket architecture.

### Driver: The Browser-Side Engine

The **Driver** (`@packages/driver`) is a JavaScript library loaded inside the browser that implements the `cy.*` command API, assertion retry logic, and the Mocha test lifecycle. According to the source code in `@packages/driver/README.md`, this package translates user commands into automation events and manages the state synchronization system via `Cypress.state()`.

When you write `cy.get('button').click()`, the Driver handles the DOM query, automatic retry loops, and event simulation entirely within the browser context.

### Server: The Node Process Behind the UI

The **Server** (`@packages/server`) runs as a Node.js process behind the Electron UI, hosting the HTTP proxy, serving static files, handling video recording, and executing plugin code. As implemented in `cypress-io/cypress`, this component receives automation events from the Driver via sockets and can invoke Node-side tasks like `cy.exec()` or file system operations.

### Runner: Electron UI and Test Coordination

The **Runner** (`@packages/runner`) boots the Electron application, loads the Application-Under-Test (AUT) into an iframe, and coordinates communication between the browser and Node processes. This package manages the visual interface where developers watch tests execute in real-time.

## Network Interception and Stubbing

Cypress distinguishes itself from other testing tools through its proprietary proxy architecture that enables network stubbing without external dependencies.

### The Proxy Layer

The **Proxy** (`@packages/proxy`) intercepts every HTTP request the AUT makes, enabling features like `cy.intercept` and `cy.route`. Located in `@packages/proxy/README.md`, this layer sits between the browser and the external network, allowing modification of requests and responses in real-time.

### Net-Stubbing Implementation

While the Proxy intercepts traffic, the **Net-Stubbing** package (`@packages/net-stubbing`) provides the server-side implementation of the `cy.intercept` API. This module matches request patterns against user-defined rules and can modify responses before they reach the browser, as documented in `@packages/net-stubbing/AGENTS.md`.

## Advanced Testing Capabilities

Modern web testing requires handling multiple origins and isolated UI components, which Cypress addresses through specialized subsystems.

### Cross-Origin Testing with cy.origin

The **cross-origin testing** architecture (`@packages/driver/src/util/serialization/` and [`cross-origin-testing.md`](https://github.com/cypress-io/cypress/blob/main/cross-origin-testing.md)) provides a security bridge that allows a single spec to execute commands across multiple origins safely. The `cy.origin()` command spawns a secondary Driver instance inside each foreign origin, enabling tests to interact with OAuth providers or third-party authentication flows without violating same-origin policies.

### Component Testing Adapters

For unit testing individual UI components, Cypress provides framework-specific adapters in `npm/react`, `npm/vue`, and `npm/angular`. These thin wrappers expose a Cypress-compatible API that mounts components in isolation while reusing the same Driver assertions and retry logic used in full E2E tests.

## Configuration and Extension Points

Developers customize Cypress behavior through a centralized configuration system and plugin hooks.

### Configuration System

The **Config** package (`@packages/config`) validates the `cypress.config.{js,ts}` schema and exposes the `defineConfig` helper. This package centralizes TypeScript definitions and environment variable resolution, ensuring consistent configuration across CLI and GUI modes.

### Plugin Hooks

The **Plugins** system (`@packages/plugins`) allows developers to extend Cypress by tapping into Node.js events. Through the `setupNodeEvents` function in your config file, you can hook into browser launches, task execution, and screenshot handling, with logic executed by the Server package.

## Performance Optimizations

Cypress uses **V8 Snapshots** (`@packages/v8-snapshot-require`) to dramatically reduce Electron start-up time. These pre-built snapshots cache the JavaScript heap state, allowing the application to boot nearly instantly rather than parsing thousands of modules on every launch.

## Practical Code Examples

### Basic E2E Test Implementation

```javascript
describe('Home page', () => {
  it('loads and shows the title', () => {
    cy.visit('/')                       // Driver loads the AUT URL
    cy.get('h1').should('contain', 'Welcome') // Automatic retry until assertion passes
  })
})

```

*Source: `@packages/driver/README.md`*

### Network Stubbing with cy.intercept

```javascript
cy.intercept('GET', '/api/users', { fixture: 'users.json' }).as('getUsers')
cy.visit('/users')
cy.wait('@getUsers').its('response.body').should('have.length', 5)

```

*Server-side matching logic lives in `@packages/net-stubbing`*

### Cross-Origin Testing Workflow

```javascript
cy.visit('https://app.example.com')
cy.get('a[href="https://auth.example.com"]').click()

cy.origin('https://auth.example.com', () => {
  cy.get('#login').type('bob')
  cy.get('#password').type('secret')
  cy.get('button').click()
})

```

*Bridge logic documented in `@packages/driver/cross-origin-testing.md`*

### React Component Testing

```javascript
import { mount } from '@cypress/react'

describe('Button component', () => {
  it('renders with correct label', () => {
    mount(<Button label="Click me" />)
    cy.contains('Click me').should('be.visible')
  })
})

```

*Adapter source in `npm/react`*

### Custom Plugin Hook

```javascript
// cypress.config.ts
import { defineConfig } from 'cypress'

export default defineConfig({
  e2e: {
    setupNodeEvents(on, config) {
      on('before:browser:launch', (browser = {}, launchOptions) => {
        launchOptions.args.push('--disable-gpu')
        return launchOptions
      })
    },
  },
})

```

*Plugins loaded by `@packages/server`, configuration defined in `@packages/config`*

## Key Source Files and Packages

| Package | Critical Path | Purpose |
|---------|--------------|---------|
| **Driver** | `@packages/driver/README.md` | Browser-side `cy.*` command implementation |
| **Server** | `@packages/server/README.md` | Node process for proxy, plugins, and video |
| **Proxy** | `@packages/proxy/README.md` | HTTP interception layer |
| **Net-Stubbing** | `@packages/net-stubbing/README.md` | `cy.intercept` server-side logic |
| **Cross-Origin** | `@packages/driver/cross-origin-testing.md` | `cy.origin` technical documentation |
| **Config** | `@packages/config/README.md` | Configuration schema and validation |
| **Reporter** | `@packages/reporter/README.md` | Test results UI component |
| **Launchpad** | `@packages/app` & `@packages/launchpad` | Vue-based project GUI |
| **React Adapter** | [`npm/react/README.md`](https://github.com/cypress-io/cypress/blob/main/npm/react/README.md) | Component testing for React |
| **V8 Snapshots** | `@packages/v8-snapshot-require/README.md` | Electron startup optimization |
| **Monorepo Overview** | [`AGENTS.md`](https://github.com/cypress-io/cypress/blob/main/AGENTS.md) | Workspace responsibility definitions |

## Summary

- **Driver** (`@packages/driver`): Executes commands inside the browser with automatic retry logic and assertion handling.
- **Server** (`@packages/server`): Manages the Node.js process, proxy, plugins, and video recording behind the UI.
- **Proxy & Net-Stubbing** (`@packages/proxy`, `@packages/net-stubbing`): Intercept and modify HTTP traffic to enable `cy.intercept` without external proxies.
- **Cross-Origin Testing** (`@packages/driver/src/util/serialization/`): Enables secure multi-origin testing via `cy.origin()` and secondary Driver instances.
- **Component Adapters** (`npm/react`, `npm/vue`, etc.): Bridge framework-specific component mounting to Cypress's Driver.
- **Socket Layer** (`@packages/socket`): Enables event-driven communication between browser and Node processes, supporting real-time test updates.

## Frequently Asked Questions

### What is the difference between the Driver and Server in Cypress?

The **Driver** runs inside the browser and executes your test code, handling DOM queries and assertions with automatic retries. The **Server** runs as a Node.js process outside the browser, managing the HTTP proxy, file system operations, and plugin execution. They communicate via sockets (`@packages/socket`), allowing the Driver to request Node-side actions like `cy.exec()` while maintaining isolation between browser automation and system-level tasks.

### How does cy.intercept work under the hood?

When you call `cy.intercept()`, the **Driver** sends the pattern matching rules to the **Server**, which stores them in the **Net-Stubbing** package (`@packages/net-stubbing`). The **Proxy** (`@packages/proxy`) intercepts all outgoing HTTP requests from the AUT, checks them against these rules, and can modify the request or response before it reaches the browser, enabling network stubbing without modifying your application code.

### What is the purpose of cy.origin in Cypress?

`cy.origin()` allows tests to interact with domains different from the one initially loaded, solving same-origin policy restrictions. According to `@packages/driver/cross-origin-testing.md`, this command creates a secondary Driver instance inside the foreign origin's iframe, establishing a secure serialization bridge (`@packages/driver/src/util/serialization/`) that lets you execute commands on authentication providers or third-party services while maintaining test isolation.

### How do component testing adapters integrate with Cypress?

Component adapters like `@cypress/react` or `@cypress/vue` act as thin translation layers that take framework-specific components and mount them into a blank Cypress AUT page. They reuse the standard **Driver** (`@packages/driver`) for assertions and commands, meaning you get the same automatic retry logic and debugging features used in E2E tests, but applied to isolated UI components rather than full applications.