Cypress Architecture Explained: Key Components and Monorepo Structure

The Cypress architecture consists of a monorepo containing specialized packages including the CLI, Test Driver, Runner UI, Desktop GUI, Server, Proxy, and Network Stubbing modules that work together to execute end-to-end and component tests inside real browsers.

Cypress is built as a monorepo that combines a desktop GUI, test runner, JavaScript driver, and supporting services into a unified testing framework. Understanding the Cypress architecture helps developers debug issues, write custom commands, and extend the framework. The source code lives in the cypress-io/cypress repository, where each workspace under packages/ and cli/ handles a specific aspect of the testing workflow.

Core Components of the Cypress Architecture

CLI and Distribution Layer

The cli/ directory contains the cypress npm package that users install globally or locally. This layer handles command parsing for cypress open, cypress run, and cypress install, serving as the entry point to the entire system.

The CLI entry point is implemented in cli/src/index.ts, which validates the environment and delegates to the appropriate binary.

Test Driver

The Test Driver (packages/driver) is the heart of Cypress execution. It runs inside the browser and implements all cy.* commands, automatic retries, and assertions.

Key implementation files include:

• packages/driver/src/main.ts – Initializes the driver and sets up the Cypress global
• packages/driver/src/cy/commands/navigation.ts – Implements cy.visit()
• packages/driver/src/cy/commands/query.ts – Implements cy.get() and querying logic

Runner UI

The Runner (packages/runner) is a Webpack-bundled web application that hosts the Application-Under-Test (AUT) iframe. It wires the driver to the AUT and provides the visual interface showing tests running in real-time.

The main entry point is packages/runner/src/index.ts, which coordinates between the driver and the browser environment.

Desktop GUI and Launchpad

The Desktop GUI consists of two Vue 3 applications:

• packages/app – The main Desktop application (Launchpad) where users select projects, browsers, and specs
• packages/launchpad – The project scaffolding UI for onboarding and generating test files

Entry points include packages/app/src/App.vue and packages/launchpad/src/Launchpad.vue.

Reporter

The Reporter (packages/reporter) renders test results including the pass/fail tree and log panels. Implemented in packages/reporter/src/Reporter.vue, this component displays the command log and error messages during test execution.

Server and Proxy

The Server (packages/server) orchestrates the test run by:

• Serving test files over HTTP
• Launching browsers via the launcher
• Managing WebSocket connections between the driver and GUI

The Proxy (packages/proxy) intercepts all HTTP/S traffic from the browser, enabling network stubbing and request modification. Both components are initialized through packages/server/src/index.ts and packages/proxy/src/index.ts.

Network Stubbing

The Net-Stubbing package (packages/net-stubbing) implements cy.intercept() functionality, handling request matching and response manipulation. The core logic resides in packages/net-stubbing/src/index.ts, which works with the proxy to intercept and modify network traffic.

Code Rewriter

The Rewriter (packages/rewriter) transforms test and application code on the fly, injecting instrumentation, polyfills, and Cypress-specific modifications. This ensures the AUT can communicate with the driver and that test code runs correctly in the browser context.

Main entry: packages/rewriter/src/index.ts.

Configuration System

The Config package (packages/config) provides TypeScript definitions, default values, validation logic, and the public defineConfig API. This ensures type safety and consistent configuration across the monorepo.

Source: packages/config/src/index.ts.

Data Context

The Data Context (packages/data-context) implements a GraphQL layer that stores project state, spec files, run history, and UI settings. This enables the Desktop GUI to query and mutate application state efficiently.

Entry point: packages/data-context/src/index.ts.

Browser Launcher and Electron Runtime

The Launcher (packages/launcher) detects installed browsers (Chrome, Firefox, Edge, WebKit) and manages their launch parameters. The Electron package (packages/electron) wraps the Electron runtime, handling binary building and auto-updates.

Key files:

• packages/launcher/src/index.ts
• packages/electron/src/index.ts

WebExtension

The Extension (packages/extension) is injected into browsers to enable cross-origin features and automation hooks required for Cypress to control the browser securely.

Background script: packages/extension/src/background.ts.

Component Testing Adapters

Under npm/@cypress/, the architecture includes adapters for component testing:

• @cypress/react, @cypress/vue – Provide mount APIs for framework-specific component testing
• @cypress/webpack-dev-server, @cypress/vite-dev-server – Launch development servers for component tests

These adapters bridge the gap between the driver and modern frontend frameworks.

How the Cypress Architecture Works Together

When you run cypress open or cypress run, the following execution flow occurs:

1. CLI parses commands and loads configuration via defineConfig from packages/config
2. Server spins up an HTTP server, starts the Proxy, and opens a browser via the Launcher
3. Inside the browser, the Driver executes user test code, exposing the cy.* API
4. The Runner UI hosts the AUT iframe and communicates with the driver via WebSockets
5. The Rewriter patches source files on the fly to inject Cypress instrumentation
6. Network traffic is intercepted by the Proxy; cy.intercept logic executes via Net-Stubbing
7. Test results stream back to the Reporter UI in the Desktop App (App package)
8. All components share common Types and Error handling libraries for consistency

Practical Code Examples

End-to-End Test Implementation

This example demonstrates how the driver commands execute inside the browser:

// cypress/e2e/spec.cy.js
describe('Navigation', () => {
  it('visits the home page', () => {
    // Implemented in packages/driver/src/cy/commands/navigation.ts
    cy.visit('https://example.cypress.io')
    
    // Implemented in packages/driver/src/cy/commands/query.ts
    cy.get('h1').should('contain', 'Kitchen Sink')
  })
})

Network Interception

The cy.intercept command leverages the net-stubbing architecture:

// cypress/e2e/network.cy.js
describe('API Stubbing', () => {
  it('mocks user data', () => {
    // Implemented in packages/net-stubbing/src/index.ts
    cy.intercept('GET', '/api/users', { fixture: 'users.json' })
    
    cy.visit('/users')
    cy.get('.user').should('have.length', 3)
  })
})

Component Testing with React Adapter

Component tests use the same driver but mount components instead of visiting pages:

// MyButton.spec.jsx
import MyButton from '../../src/MyButton'

describe('MyButton', () => {
  it('renders with label', () => {
    // Provided by npm/@cypress/react/src/index.tsx
    cy.mount(<MyButton label="Submit" />)
    cy.contains('Submit').should('be.visible')
  })
})

CLI Usage

# Entry point: cli/src/index.ts

cypress run --spec "cypress/e2e/login.cy.js"
cypress open --browser chrome

Summary

• Cypress architecture is organized as a monorepo with distinct packages under packages/ and cli/
• The Driver (packages/driver) runs inside the browser and implements all cy.* commands
• The Server (packages/server) and Proxy (packages/proxy) handle file serving and network interception
• Net-Stubbing (packages/net-stubbing) powers the cy.intercept() API for mocking HTTP requests
• The Rewriter (packages/rewriter) transforms code to enable Cypress instrumentation
• Desktop GUI components (packages/app, packages/launchpad) provide the Vue 3-based user interface
• Component testing extends the architecture through framework-specific adapters in npm/@cypress/

Frequently Asked Questions

What is the Cypress driver and where does it run?

The Cypress driver is the JavaScript library that executes inside the browser alongside your application. Located in packages/driver/src/main.ts, it implements all cy.* commands, assertion logic, and retry mechanisms. Unlike Selenium-based tools that run outside the browser, the driver operates within the same event loop as the Application-Under-Test, enabling native access to DOM and network events.

How does Cypress proxy and intercept network requests?

Cypress uses the Proxy package (packages/proxy/src/index.ts) to intercept all HTTP/S traffic between the browser and external servers. When you call cy.intercept(), the Net-Stubbing package (packages/net-stubbing/src/index.ts) matches requests against your patterns and can modify responses or requests in real-time. This architecture allows Cypress to stub network traffic without modifying your application's code.

What is the difference between the App and Launchpad packages?

The App package (packages/app) contains the main Desktop GUI where users select projects, browsers, and specs during active testing. The Launchpad package (packages/launchpad) handles project scaffolding, onboarding flows, and initial project setup. While app/src/App.vue manages the test-running interface, launchpad/src/Launchpad.vue manages the pre-test configuration and project creation workflows.

How does Cypress support component testing?

Cypress extends its architecture for component testing through adapter packages in npm/@cypress/. These adapters (like @cypress/react and @cypress/vue) provide a mount function that renders components in isolation using the same driver infrastructure. The Webpack and Vite dev server packages (npm/@cypress/webpack-dev-server, npm/@cypress/vite-dev-server) compile components on the fly, allowing the driver to interact with them using the same cy.* commands used for end-to-end tests.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}