# How Cypress Features Are Implemented Within the Monorepo: A Complete Architectural Guide

> Discover how Cypress implements features within its monorepo architecture. Learn about the roles of packages driver server proxy and net stubbing communicating via WebSocket and GraphQL.

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

---

**Cypress implements features through a modular monorepo architecture where `packages/driver` runs commands in the browser, `packages/server` orchestrates test runs, `packages/proxy` intercepts network traffic, and `packages/net-stubbing` powers request mocking—all communicating via WebSocket and GraphQL protocols.**

The Cypress testing framework is organized as a large, well-structured monorepo that separates concerns into focused, independently testable packages. Each major feature area—the test driver, server, proxy, network stubbing layer, and UI—lives in its own package under `packages/`, sharing common utilities for types, logging, and error handling. This architecture keeps the codebase modular while enabling tight integration between browser-based test execution and server-side orchestration.

---

## Core Architectural Packages

Understanding how Cypress features are implemented within the monorepo starts with mapping the primary packages to their runtime roles and interactions.

| Feature | Package | Primary Role | Key Runtime Interaction |
|---------|---------|--------------|------------------------|
| **Test Driver** | `packages/driver` | Implements the `cy.*` command API running inside the AUT browser. Handles command queuing, retries, and privileged communication. | Loaded via Cypress runner; communicates with server through WebSocket (`@packages/socket`) |
| **Server** | `packages/server` | HTTP server serving test files, launching browsers, orchestrating test runs. Handles CLI commands (`cypress run`, `cypress open`). | Starts driver, proxies traffic, streams results to UI |
| **Proxy** | `packages/proxy` | HTTP/HTTPS proxy intercepting all AUT requests. Injects scripts, rewrites responses. | Inserted into browser network stack via Chrome DevTools Protocol or Playwright |
| **Network Stubbing** | `packages/net-stubbing` | Request/response interception and mocking via `cy.intercept` API | Runs inside proxy using `net-stubbing/lib/server` middleware |
| **UI** | `packages/app` & `packages/launchpad` | Vue-based GUI for test runner, command log, project management | Consumes server data via GraphQL (`@packages/data-context`) |
| **Shared Utilities** | `packages/types`, `@packages/errors`, `@packages/logger` | TypeScript definitions, error objects, logging helpers | Imported across all packages for type safety |

---

## How a Test Runs Through the Monorepo

The monorepo implementation creates a clear execution pipeline that demonstrates how Cypress features are implemented within the monorepo through package coordination:

1. **CLI Invocation** – `cypress run` boots the **server** from [`packages/server/src/main.ts`](https://github.com/cypress-io/cypress/blob/main/packages/server/src/main.ts)
2. **Browser Launch** – Server spawns browser via `@packages/launcher`
3. **Proxy Injection** – Browser routes traffic through **proxy** (`packages/proxy/lib/http`)
4. **Driver Injection** – Cypress inserts **driver** scripts; driver registers `cy` global and opens WebSocket to server
5. **Test Execution** – Test code queues commands; each command travels over the privileged channel to the server, which may:
   - Execute browser commands (navigation, clicks)
   - Intercept network via **net-stubbing** middleware
   - Log results back to UI
6. **Result Streaming** – Server streams real-time state to UI via GraphQL

---

## Deep Dive: Core Package Implementations

### Driver Package (`packages/driver`)

The driver represents the browser-side implementation of how Cypress features are implemented within the monorepo. It creates the `cy` global and manages the entire command lifecycle.

**Entry point**: [`src/main.ts`](https://github.com/cypress-io/cypress/blob/main/src/main.ts) – loads driver, sets up privileged channel, registers commands.

Key source files:

| File | Purpose |
|------|---------|
| [`src/util/config.ts`](https://github.com/cypress-io/cypress/blob/main/src/util/config.ts) | Reads server configuration; exposes `Cypress.config()` |
| [`src/util/commandAUTCommunication.ts`](https://github.com/cypress-io/cypress/blob/main/src/util/commandAUTCommunication.ts) | WebSocket communication (`window.__CypressTelemetry`) |
| [`src/dom/window.ts`](https://github.com/cypress-io/cypress/blob/main/src/dom/window.ts) | Polyfills DOM APIs (`window.focus`, visibility) |
| [`src/util/queue.ts`](https://github.com/cypress-io/cypress/blob/main/src/util/queue.ts) | Command queue, retries, timeout logic |
| `src/util/serialization/*` | Cross-channel serialization for errors and logs |

**Command execution flow**: Calling `cy.get('.btn')` creates a command object pushed to `Queue`, sends a command request to the server, which executes, captures results, and returns serialized responses for driver resolution.

```javascript
// Conceptual driver command flow
cy.get('.btn')           // Driver creates command object
  ↓
Queue.push(command)      // packages/driver/src/util/queue.ts
  ↓
WebSocket → Server       // packages/driver/src/util/commandAUTCommunication.ts
  ↓
Server executes          // packages/server/src/util/socket.ts
  ↓
Serialized response → Driver resolves

```

**Source**: [[`packages/driver/src/main.ts`](https://github.com/cypress-io/cypress/blob/main/packages/driver/src/main.ts)](https://github.com/cypress-io/cypress/blob/develop/packages/driver/src/main.ts)

---

### Server Package (`packages/server`)

The server demonstrates how Cypress features are implemented within the monorepo through orchestration and process management.

**Entry points**: [`packages/server/v8-snapshot-entry.js`](https://github.com/cypress-io/cypress/blob/main/packages/server/v8-snapshot-entry.js) (bundled) and [`src/main.ts`](https://github.com/cypress-io/cypress/blob/main/src/main.ts) (unbundled).

Key source files:

| File | Purpose |
|------|---------|
| [`src/util/args.ts`](https://github.com/cypress-io/cypress/blob/main/src/util/args.ts) | CLI argument parsing and config merging |
| [`src/util/socket.ts`](https://github.com/cypress-io/cypress/blob/main/src/util/socket.ts) | WebSocket management for driver communication |
| [`src/util/project.ts`](https://github.com/cypress-io/cypress/blob/main/src/util/project.ts) | Project lifecycle, spec scanning, scaffolding |
| [`src/util/plugins/child/require_async_child.ts`](https://github.com/cypress-io/cypress/blob/main/src/util/plugins/child/require_async_child.ts) | Plugin isolation in child processes |
| [`src/util/network-proxy.ts`](https://github.com/cypress-io/cypress/blob/main/src/util/network-proxy.ts) | Proxy process startup and wiring |
| `src/util/cloud/*` | Cypress Cloud integration |

The server receives driver commands, forwards to internal services, and streams events to the UI via GraphQL.

**Source**: [[`packages/server/v8-snapshot-entry.js`](https://github.com/cypress-io/cypress/blob/main/packages/server/v8-snapshot-entry.js)](https://github.com/cypress-io/cypress/blob/develop/packages/server/v8-snapshot-entry.js)

---

### Proxy Package (`packages/proxy`)

The proxy enables network-level features by intercepting all AUT traffic.

**Main file**: [`lib/http/index.ts`](https://github.com/cypress-io/cypress/blob/main/lib/http/index.ts) — HTTP/HTTPS proxy pipeline.

Key source files:

| File | Purpose |
|------|---------|
| [`lib/http/request-middleware.ts`](https://github.com/cypress-io/cypress/blob/main/lib/http/request-middleware.ts) | Request interception, Cypress identifiers, net-stubbing forwarding |
| [`lib/http/response-middleware.ts`](https://github.com/cypress-io/cypress/blob/main/lib/http/response-middleware.ts) | Response handling, script injection, header rewriting |
| `lib/http/util/*` | Stream handling, CSP manipulation, cookie normalization, AST rewriting |
| [`lib/resourceTypeAndCredentialManager.ts`](https://github.com/cypress-io/cypress/blob/main/lib/resourceTypeAndCredentialManager.ts) | Resource type and credential classification |

All AUT network traffic passes through this proxy, enabling automatic waiting, request mocking, and polyfill injection.

**Source**: [[`packages/proxy/lib/http/index.ts`](https://github.com/cypress-io/cypress/blob/main/packages/proxy/lib/http/index.ts)](https://github.com/cypress-io/cypress/blob/develop/packages/proxy/lib/http/index.ts)

---

### Network Stubbing Package (`packages/net-stubbing`)

This package implements `cy.intercept`, a flagship feature showing how Cypress features are implemented within the monorepo through middleware architecture.

**Main module**: [`lib/server/index.ts`](https://github.com/cypress-io/cypress/blob/main/lib/server/index.ts) — registers `cy.intercept` middleware.

Key source files:

| File | Purpose |
|------|---------|
| [`middleware/request.ts`](https://github.com/cypress-io/cypress/blob/main/middleware/request.ts) | Request parsing, rule matching, mock/pass-through decisions |
| [`middleware/response.ts`](https://github.com/cypress-io/cypress/blob/main/middleware/response.ts) | Response modification (status, headers, body) |
| [`intercepted-request.ts`](https://github.com/cypress-io/cypress/blob/main/intercepted-request.ts) | `InterceptedRequest` class with `reply`, `delay`, `abort` methods |
| [`handle-intercept-request.ts`](https://github.com/cypress-io/cypress/blob/main/handle-intercept-request.ts) | Bridges proxy streams to test callbacks |

**`cy.intercept` flow**:

1. Test registers interceptor → server stores matching rule
2. Proxy request middleware checks rules
3. Matching requests wrapped in `InterceptedRequest`
4. Test manipulates via `req.reply({ body: 'mocked' })`
5. Response streamed back through proxy

```javascript
// Test usage maps to monorepo implementation
cy.intercept('GET', '/api/users', { fixture: 'users.json' }).as('getUsers')
//           ↓
// packages/net-stubbing/lib/server/index.ts stores rule
//           ↓
// packages/proxy/lib/http/request-middleware.ts matches and intercepts
//           ↓
// packages/net-stubbing/middleware/response.ts returns mock

```

**Source**: [[`packages/net-stubbing/lib/server/index.ts`](https://github.com/cypress-io/cypress/blob/main/packages/net-stubbing/lib/server/index.ts)](https://github.com/cypress-io/cypress/blob/develop/packages/net-stubbing/lib/server/index.ts)

---

### UI Packages (`packages/app` & `packages/launchpad`)

The Vue 3-based UI demonstrates how Cypress features are implemented within the monorepo for developer experience.

**Entry point**: [`src/main.ts`](https://github.com/cypress-io/cypress/blob/main/src/main.ts)

Key source files:

| File | Purpose |
|------|---------|
| [`src/components/CommandLog.vue`](https://github.com/cypress-io/cypress/blob/main/src/components/CommandLog.vue) | Hierarchical command log with retries/screenshots |
| [`src/components/Runner.vue`](https://github.com/cypress-io/cypress/blob/main/src/components/Runner.vue) | AUT iframe hosting, event forwarding |
| [`src/graphql/client.ts`](https://github.com/cypress-io/cypress/blob/main/src/graphql/client.ts) | GraphQL client for server polling |
| [`src/store/index.ts`](https://github.com/cypress-io/cypress/blob/main/src/store/index.ts) | Vuex store for run state, specs, preferences |

The Electron or web app loads the Vue bundle, connects via GraphQL, and displays live results from `command:log`, `test:failed`, and `run:finished` events.

**Source**: [[`packages/app/src/main.ts`](https://github.com/cypress-io/cypress/blob/main/packages/app/src/main.ts)](https://github.com/cypress-io/cypress/blob/develop/packages/app/src/main.ts)

---

### Shared Infrastructure

| Package | Purpose | Key Files |
|---------|---------|-----------|
| `packages/types` | Single source of truth for TypeScript | [`src/types.ts`](https://github.com/cypress-io/cypress/blob/main/src/types.ts), [`src/protocol.ts`](https://github.com/cypress-io/cypress/blob/main/src/protocol.ts), [`src/video.ts`](https://github.com/cypress-io/cypress/blob/main/src/video.ts) |
| `@packages/errors` | Consistent error definitions | [`src/index.ts`](https://github.com/cypress-io/cypress/blob/main/src/index.ts), `src/templates/*.ts` |
| `@packages/logger` | Structured cross-package logging | [`src/logger.ts`](https://github.com/cypress-io/cypress/blob/main/src/logger.ts) |

These utilities ensure type safety and consistent behavior across the monorepo boundary.

---

## Practical Implementation Examples

### Using `cy.intercept` with Monorepo Awareness

```javascript
// test/spec.cy.js
describe('API mocking', () => {
  it('stubs a GET request', () => {
    // Registers rule in packages/net-stubbing
    cy.intercept('GET', '/api/users', { fixture: 'users.json' }).as('getUsers')

    // Driver queues visit; proxy matches request
    cy.visit('/users')
    
    // Driver waits for net-stubbing completion signal
    cy.wait('@getUsers')
    
    // Standard driver command execution
    cy.get('.user').should('have.length', 3)
  })
})

```

**Cross-package flow**: Driver (`cy.intercept`) → Server stores rule → Proxy intercepts → Net-stubbing executes mock → Driver receives completion.

### Custom Command Extending Driver

```javascript
// cypress/support/commands.js
Cypress.Commands.add('login', (username, password) => {
  // Driver command: serialized → server → Node http client
  cy.request('POST', '/api/login', { username, password })
    .its('body')
    .then((data) => {
      // Driver writes to AUT localStorage
      window.localStorage.setItem('authToken', data.token)
    })
})

```

### Server-Injected Configuration

```javascript
// packages/driver/src/util/config.ts (excerpt)
export function getCypressConfig () {
  return window.__CypressConfig // Injected by server at browser launch
}

```

The server reads [`cypress.config.ts`](https://github.com/cypress-io/cypress/blob/main/cypress.config.ts) via `@packages/config` and injects merged configuration for driver consumption.

---

## Key Source Files for Exploration

| Feature | Files | GitHub Link |
|---------|-------|-------------|
| Driver core | [`src/main.ts`](https://github.com/cypress-io/cypress/blob/main/src/main.ts), [`src/util/queue.ts`](https://github.com/cypress-io/cypress/blob/main/src/util/queue.ts), [`src/util/commandAUTCommunication.ts`](https://github.com/cypress-io/cypress/blob/main/src/util/commandAUTCommunication.ts) | [driver/src/main.ts](https://github.com/cypress-io/cypress/blob/develop/packages/driver/src/main.ts) |
| Server bootstrap | [`v8-snapshot-entry.js`](https://github.com/cypress-io/cypress/blob/main/v8-snapshot-entry.js), [`src/util/args.ts`](https://github.com/cypress-io/cypress/blob/main/src/util/args.ts), [`src/util/socket.ts`](https://github.com/cypress-io/cypress/blob/main/src/util/socket.ts) | [server/v8-snapshot-entry.js](https://github.com/cypress-io/cypress/blob/develop/packages/server/v8-snapshot-entry.js) |
| Proxy middleware | [`lib/http/request-middleware.ts`](https://github.com/cypress-io/cypress/blob/main/lib/http/request-middleware.ts), [`lib/http/response-middleware.ts`](https://github.com/cypress-io/cypress/blob/main/lib/http/response-middleware.ts), [`lib/http/util/csp-header.ts`](https://github.com/cypress-io/cypress/blob/main/lib/http/util/csp-header.ts) | [proxy/lib/http/request-middleware.ts](https://github.com/cypress-io/cypress/blob/develop/packages/proxy/lib/http/request-middleware.ts) |
| Network stubbing | [`lib/server/index.ts`](https://github.com/cypress-io/cypress/blob/main/lib/server/index.ts), [`middleware/request.ts`](https://github.com/cypress-io/cypress/blob/main/middleware/request.ts), [`intercepted-request.ts`](https://github.com/cypress-io/cypress/blob/main/intercepted-request.ts) | [net-stubbing/lib/server/index.ts](https://github.com/cypress-io/cypress/blob/develop/packages/net-stubbing/lib/server/index.ts) |
| UI implementation | [`src/main.ts`](https://github.com/cypress-io/cypress/blob/main/src/main.ts), [`src/components/CommandLog.vue`](https://github.com/cypress-io/cypress/blob/main/src/components/CommandLog.vue), [`src/graphql/client.ts`](https://github.com/cypress-io/cypress/blob/main/src/graphql/client.ts) | [app/src/main.ts](https://github.com/cypress-io/cypress/blob/develop/packages/app/src/main.ts) |
| Shared types | [`src/types.ts`](https://github.com/cypress-io/cypress/blob/main/src/types.ts), [`src/protocol.ts`](https://github.com/cypress-io/cypress/blob/main/src/protocol.ts) | [types/src/types.ts](https://github.com/cypress-io/cypress/blob/develop/packages/types/src/types.ts) |
| Error handling | [`src/index.ts`](https://github.com/cypress-io/cypress/blob/main/src/index.ts) | [errors/src/index.ts](https://github.com/cypress-io/cypress/blob/develop/packages/errors/src/index.ts) |
| Browser launcher | [`src/index.ts`](https://github.com/cypress-io/cypress/blob/main/src/index.ts) | [launcher/src/index.ts](https://github.com/cypress-io/cypress/blob/develop/packages/launcher/src/index.ts) |

---

## Summary

Understanding how Cypress features are implemented within the monorepo reveals a carefully architected system:

- **`packages/driver`** — Browser-side command execution, queuing, and AUT communication
- **`packages/server`** — Test orchestration, browser launching, CLI handling, and UI streaming
- **`packages/proxy`** — Network traffic interception for all AUT requests
- **`packages/net-stubbing`** — `cy.intercept` implementation through middleware matching
- **`packages/app`/`packages/launchpad`** — Vue-based developer interface consuming GraphQL data
- **Shared packages** (`types`, `errors`, `logger`) — Cross-cutting concerns for consistency

The monorepo structure enables independent package development while maintaining tight runtime integration through WebSocket driver-server communication, proxy-based network control, and GraphQL UI data flow.

---

## Frequently Asked Questions

### Where is the `cy` command API actually defined?

The `cy` global and all command implementations reside in **`packages/driver`**. The entry point [`src/main.ts`](https://github.com/cypress-io/cypress/blob/main/src/main.ts) registers commands, while [`src/util/queue.ts`](https://github.com/cypress-io/cypress/blob/main/src/util/queue.ts) manages execution order, retries, and timeouts. Commands serialize across a WebSocket to `packages/server` for execution.

### How does `cy.intercept` intercept network requests?

`cy.intercept` rules stored in **`packages/net-stubbing`** are evaluated by **`packages/proxy`** request middleware. Matching triggers an `InterceptedRequest` object that test code can manipulate via `req.reply()`, with responses streamed back through the proxy—no actual network request reaches the destination when mocked.

### Why does Cypress use a proxy architecture?

The proxy in **`packages/proxy`** enables universal request interception regardless of browser or request origin (XHR, fetch, iframe, WebSocket). This allows automatic waiting, header rewriting, script injection, and the `cy.intercept` API without modifying application code or requiring browser extensions.

### What role does the server play versus the driver?

The **driver** (`packages/driver`) runs JavaScript commands inside the browser and manages the `cy` API surface. The **server** (`packages/server`) launches browsers, serves test files, executes privileged operations Node.js can perform, and streams results to the UI. They communicate via WebSocket through `@packages/socket`.