# What Is the Role of the Runner in Cypress? Core Architecture Explained

> Discover the Cypress Runner, the in-browser environment that connects your tests to the application. Learn its core role in bundling the test driver and reporter.

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

---

**The Cypress Runner is the in-browser execution environment that bundles the test driver and reporter into a single bundle, exposes them through a global `UnifiedRunner` object, and serves as the live bridge between the Cypress server and the Application Under Test.**

The **Cypress Runner** sits at the heart of the test execution lifecycle, transforming your spec files into actual browser interactions. As implemented in the `cypress-io/cypress` repository, this component operates as the **execution nucleus** that loads the JavaScript driver, renders the reporter UI, and manages the real-time communication layer between the server process and the browser iframe.

## Core Responsibilities of the Cypress Runner

### Bundling the Test Execution Engine

The runner's primary responsibility is packaging the **test execution engine**. It bundles `@packages/driver`—the JavaScript library that implements the `cy.*` commands, automatic retries, and DOM interactions—together with `@packages/reporter` (the React-based UI that visualizes test results). This compilation produces a single script called [`cypress_runner.js`](https://github.com/cypress-io/cypress/blob/main/cypress_runner.js), which is injected into the test runner iframe. Once loaded, this bundle provides test code with a fully-featured driver and a live reporter interface.

### Exposing the UnifiedRunner API

According to [`packages/runner/unified-runner.tsx`](https://github.com/cypress-io/cypress/blob/main/packages/runner/unified-runner.tsx), the runner injects a global object called **`UnifiedRunner`** into the browser window. This object aggregates the driver, a jQuery shim, keyboard shortcuts, React, MobX, and helper utilities for creating React roots. Test code and UI extensions can access the core driver API through `window.UnifiedRunner.CypressDriver` or the jQuery instance via `window.UnifiedRunner.CypressJQuery`.

### Initializing the UI Environment

The runner initializes the visual environment through a minimal JSX entry point. In [`packages/runner/src/main.jsx`](https://github.com/cypress-io/cypress/blob/main/packages/runner/src/main.jsx), the runner simply attaches `UnifiedRunner` to the global `window` object, making the driver and reporter discoverable as soon as the iframe loads. Additionally, [`packages/runner/src/index.js`](https://github.com/cypress-io/cypress/blob/main/packages/runner/src/index.js) imports shared SCSS ([`main.scss`](https://github.com/cypress-io/cypress/blob/main/main.scss)) containing legacy Cypress and reporter styles, ensuring visual components render correctly inside the runner frame.

### Bridging Server and Browser Communication

While `@packages/server` handles file serving, browser launching, and socket management, the **Runner** resides entirely within the browser process. It receives commands from the server via **WebSocket**, drives the AUT (Application Under Test), executes test steps (including hooks and network stubbing), collects results, and forwards them back to the server. This architecture makes the runner the *live execution engine* that interprets server directives into browser actions.

## How the Runner Exposes APIs to Test Code

The following snippets illustrate how the Runner's exported objects are constructed and used internally:

```javascript
// packages/runner/src/main.jsx – expose UnifiedRunner globally
import { UnifiedRunner } from '../unified-runner'

window.UnifiedRunner = UnifiedRunner

```

```tsx
// packages/runner/unified-runner.tsx – what the Runner makes available
export const UnifiedRunner = {
  // jQuery shim that the driver uses
  CypressJQuery: $Cypress.$,

  // Full driver API (cy.* commands, retry logic, etc.)
  CypressDriver: $Cypress,

  // Keyboard shortcuts for the reporter UI
  shortcuts,

  // React and MobX are re‑exported for the UI components
  React,
  MobX,

  // Helper to mount React roots inside the runner iframe
  ReactDOM: { createRoot },

  // The visual test reporter
  Reporter,
}

```

```javascript
// Simplified driver interaction pattern
function runCommand (command) {
  // The driver receives a command from the server,
  // executes it against the AUT, and reports results.
  UnifiedRunner.CypressDriver.execute(command)
}

```

## Key Source Files in the Runner Architecture

Understanding the role of the runner requires familiarity with these specific files in the `cypress-io/cypress` repository:

- **[`packages/runner/README.md`](https://github.com/cypress-io/cypress/blob/main/packages/runner/README.md)** – Documents the high-level responsibilities and deprecation roadmap of the runner package.
- **[`packages/runner/unified-runner.tsx`](https://github.com/cypress-io/cypress/blob/main/packages/runner/unified-runner.tsx)** – Declares the `UnifiedRunner` object that aggregates driver, reporter, and UI helpers.
- **[`packages/runner/src/main.jsx`](https://github.com/cypress-io/cypress/blob/main/packages/runner/src/main.jsx)** – Entry point that attaches `UnifiedRunner` to the browser's `window` object.
- **[`packages/runner/src/index.js`](https://github.com/cypress-io/cypress/blob/main/packages/runner/src/index.js)** – Imports SCSS and JSX entry points; the primary file bundled into [`cypress_runner.js`](https://github.com/cypress-io/cypress/blob/main/cypress_runner.js).
- **[`packages/driver/src/index.ts`](https://github.com/cypress-io/cypress/blob/main/packages/driver/src/index.ts)** – Implements the `cy.*` command API and retry logic that the runner ultimately exposes.
- **[`packages/reporter/src/main.tsx`](https://github.com/cypress-io/cypress/blob/main/packages/reporter/src/main.tsx)** – Renders the visual test progress and results inside the runner iframe.

## Summary

- The **Cypress Runner** is the in-browser execution environment that bundles the driver and reporter into [`cypress_runner.js`](https://github.com/cypress-io/cypress/blob/main/cypress_runner.js).
- It exposes a global **`UnifiedRunner`** object providing access to `CypressDriver`, `CypressJQuery`, keyboard shortcuts, and UI components.
- It initializes the test environment through [`main.jsx`](https://github.com/cypress-io/cypress/blob/main/main.jsx) and handles styling via [`main.scss`](https://github.com/cypress-io/cypress/blob/main/main.scss).
- It acts as the bridge between the server (receiving WebSocket commands) and the Application Under Test (executing commands and streaming results).

## Frequently Asked Questions

### What is the difference between the Cypress Runner and the Cypress Driver?

The **Runner** is the iframe environment that bundles and exposes the APIs, while the **Driver** (`@packages/driver`) is the JavaScript library that actually implements the `cy.*` commands, retry logic, and DOM interaction. The runner loads the driver and makes it available via `window.UnifiedRunner.CypressDriver`, but the driver contains the actual implementation of the test API.

### How does the runner communicate with the Cypress server?

The runner receives commands from the server via **WebSocket** connections. It executes these commands against the Application Under Test within the browser, then streams the results back to the server for logging and reporting. This architecture keeps the heavy execution logic in the browser while the server coordinates multiple test instances.

### Why is the UnifiedRunner exposed as a global window object?

The `UnifiedRunner` is attached to `window` in [`packages/runner/src/main.jsx`](https://github.com/cypress-io/cypress/blob/main/packages/runner/src/main.jsx) to ensure the driver, reporter, and utility libraries (React, MobX) are immediately discoverable by test code and browser extensions as soon as the iframe loads, without requiring module imports from within the spec files themselves.

### What files are bundled into cypress_runner.js?

The bundle includes [`packages/runner/src/index.js`](https://github.com/cypress-io/cypress/blob/main/packages/runner/src/index.js) (which imports the SCSS and JSX entry points), the driver from `@packages/driver`, the reporter from `@packages/reporter`, and all supporting UI libraries. This creates the complete execution environment loaded into the browser iframe at test startup.