# Where Is the Cypress Driver Code Located? A Deep Dive into the `packages/driver` Directory

> Discover where the Cypress driver code lives within the cypress-io/cypress repository. Explore the packages/driver directory for browser-side JavaScript, the cy API, and command queue.

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

---

**The Cypress driver code is located in the `packages/driver` directory of the `cypress-io/cypress` repository, which contains the JavaScript implementation that runs inside the browser to provide the `cy.*` API, command queue, and DOM interaction layer.**

The Cypress driver serves as the test execution engine that operates within the browser, bridging the test runner and the application under test. This critical package handles everything from command queuing to network interception, and understanding its location helps contributors and advanced users debug issues or extend functionality.

## The Core Location: `packages/driver`

All driver-related source files reside under **`packages/driver/src/`** in the Cypress monorepo. This package is distinct from the CLI and desktop GUI components, focusing exclusively on the code that executes within the browser context.

### Entry Point and Initialization

The driver bootstrap sequence begins in **[`src/main.ts`](https://github.com/cypress-io/cypress/blob/main/src/main.ts)**, which initializes the driver, registers the global `Cypress` object, and starts the command runner. This file serves as the primary entry point that sets up the entire browser-side testing environment.

### The `cy` API Implementation

The chainable `cy` object that users interact with in test files is defined in **[`src/cypress/cy.ts`](https://github.com/cypress-io/cypress/blob/main/src/cypress/cy.ts)**. This module exposes all user-facing commands including `cy.visit()`, `cy.get()`, and `cy.type()`. The actual command implementations live in **[`src/cypress/commands.ts`](https://github.com/cypress-io/cypress/blob/main/src/cypress/commands.ts)**, which contains the core logic for element querying, form interactions, and assertions.

### Command Queue Architecture

Cypress commands execute asynchronously through a sophisticated queue system managed in **[`src/cypress/command_queue.ts`](https://github.com/cypress-io/cypress/blob/main/src/cypress/command_queue.ts)**. This file implements the queue that stores and executes commands in order, handling retries and ensuring deterministic test execution. The queue manages the timing between commands and coordinates with the browser's event loop.

## Key Subsystems in the Driver

Beyond the core API, the driver contains specialized modules for DOM interaction, network handling, and error formatting.

### DOM Utilities and Visibility Logic

Element selection and visibility detection reside in **`src/dom/*`** (specifically **`src/dom/elements/`**). These utilities handle:

- Element lookup and shadow DOM traversal
- Visibility calculations and dimension checks
- Position verification for clickability assertions

These helpers ensure that commands like `cy.should('be.visible')` accurately reflect user-perceivable state.

### Network Stubbing and Interception

The `cy.intercept()` functionality for request mocking is implemented in **[`src/cypress/network_utils.ts`](https://github.com/cypress-io/cypress/blob/main/src/cypress/network_utils.ts)**. This module supports network stubbing by intercepting XMLHttpRequest and fetch calls, allowing tests to mock API responses without modifying application code.

### Error Handling and Stack Traces

Rich error formatting occurs in **[`src/cypress/error_utils.ts`](https://github.com/cypress-io/cypress/blob/main/src/cypress/error_utils.ts)**, which produces the detailed stack traces and user-friendly error messages displayed in the Cypress UI. This module translates JavaScript errors into actionable debugging information.

### Configuration Management

Driver configuration reading happens in **[`src/util/config.ts`](https://github.com/cypress-io/cypress/blob/main/src/util/config.ts)**, which parses the Cypress config (including `baseUrl`, environment variables, and viewport settings) and makes these values available to all driver components.

## Directory Structure Overview

The `packages/driver` organization follows this structure:

```

cypress/
 └─ packages/
     └─ driver/
         ├─ src/
         │   ├─ cypress/
         │   │   ├─ cy.ts
         │   │   ├─ commands.ts
         │   │   ├─ command_queue.ts
         │   │   ├─ network_utils.ts
         │   │   └─ error_utils.ts
         │   ├─ dom/
         │   │   └─ elements/
         │   ├─ util/
         │   │   └─ config.ts
         │   └─ main.ts
         ├─ tsconfig.json
         └─ vite.config.mjs

```

## How the Driver Works in Practice

When you write a test using the `cy` API, the driver code in `packages/driver` executes these commands in the browser. Here is how the implementation maps to typical test usage:

```typescript
// example.spec.ts – a typical Cypress test file
describe('Todo app', () => {
  it('adds a new todo', () => {
    // visit() implemented in src/cypress/cy.ts
    cy.visit('/index.html')
    
    // get() and type() commands defined in src/cypress/commands.ts
    cy.get('[data-test=new-todo]').type('Buy milk{enter}')
    
    // Visibility check uses DOM helpers in src/dom/elements/
    cy.contains('li', 'Buy milk').should('be.visible')
  })
})

```

The driver injects these scripts into the browser, creates the command queue, and manages the asynchronous execution flow between your test code and the application under test.

## Summary

- The **Cypress driver code** lives in **`packages/driver`** within the `cypress-io/cypress` repository.
- **[`src/main.ts`](https://github.com/cypress-io/cypress/blob/main/src/main.ts)** bootstraps the driver and attaches `window.Cypress`.
- **[`src/cypress/cy.ts`](https://github.com/cypress-io/cypress/blob/main/src/cypress/cy.ts)** exposes the `cy` global and chainable commands.
- **[`src/cypress/command_queue.ts`](https://github.com/cypress-io/cypress/blob/main/src/cypress/command_queue.ts)** manages the async command execution and retry logic.
- **`src/dom/`** contains utilities for element selection, visibility detection, and shadow DOM handling.
- **[`src/cypress/network_utils.ts`](https://github.com/cypress-io/cypress/blob/main/src/cypress/network_utils.ts)** implements `cy.intercept()` for request mocking.
- **[`src/cypress/error_utils.ts`](https://github.com/cypress-io/cypress/blob/main/src/cypress/error_utils.ts)** formats stack traces and creates rich error messages.

## Frequently Asked Questions

### What is the main entry point for the Cypress driver?

The main entry point is **[`packages/driver/src/main.ts`](https://github.com/cypress-io/cypress/blob/main/packages/driver/src/main.ts)**. This file initializes the driver instance, registers the global `Cypress` object on the browser window, and starts the command runner that processes your test code.

### Where are the `cy.visit()` and `cy.get()` commands implemented?

These commands are defined in **[`packages/driver/src/cypress/cy.ts`](https://github.com/cypress-io/cypress/blob/main/packages/driver/src/cypress/cy.ts)**, with core implementations in **[`packages/driver/src/cypress/commands.ts`](https://github.com/cypress-io/cypress/blob/main/packages/driver/src/cypress/commands.ts)**. The [`cy.ts`](https://github.com/cypress-io/cypress/blob/main/cy.ts) file sets up the chainable API surface, while [`commands.ts`](https://github.com/cypress-io/cypress/blob/main/commands.ts) contains the actual logic for navigation, element querying, and user interactions.

### How does Cypress handle DOM visibility checks?

Visibility logic resides in **`packages/driver/src/dom/`**, specifically within the elements subdirectory. These modules calculate whether elements are visible to users by checking CSS properties, dimensions, and positioning, separate from the DOM presence checks that the browser provides.

### Is the driver code written in TypeScript?

Yes, the entire `packages/driver` source is written in TypeScript. Files use `.ts` extensions (including [`src/main.ts`](https://github.com/cypress-io/cypress/blob/main/src/main.ts) and [`src/cypress/cy.ts`](https://github.com/cypress-io/cypress/blob/main/src/cypress/cy.ts)), and the package includes a [`tsconfig.json`](https://github.com/cypress-io/cypress/blob/main/tsconfig.json) for type checking. The build process compiles these TypeScript files for browser execution via the Vite configuration defined in `vite.config.mjs`.