AGENTS.md · cypress-io/cypress

Sections

1. Overview
2. Workspaces
3. Task runbooks
4. Prerequisites
5. Common Commands
6. Architecture
7. Code Conventions
8. Runtime targets
9. Pull Requests
10. CI/CD
11. Cloud agent environments

First lines (shown under the repo's MIT license)

# Cypress Monorepo — AGENTS.md

## Overview

Cypress is an open-source end-to-end and component testing framework for the modern web. This monorepo ships the Cypress desktop application and CLI (`cypress`), the JavaScript driver that runs tests in the browser, the Electron-based test runner, a suite of published npm packages (component testing adapters, webpack/vite dev-server integrations, plugins), and the internal tooling used to build and release all of it. Cypress is used by millions of developers to test web applications across Chrome, Firefox, Edge, WebKit, and Electron.

## Workspaces

- **`cli/`** — The main `cypress` npm package (CLI entry point) and co-located component testing framework adapters (`@cypress/react`, `@cypress/vue`, `@cypress/angular`, `@cypress/svelte`, `@cypress/mount-utils`)
- **`packages/`** — Core internal packages: the test driver, Electron app, HTTP server, proxy, launcher, frontend Vue app, launchpad, reporter, config, data-context, telemetry, types, errors, and more
- **`npm/`** — Publicly published npm packages: bundler integrations, component testing adapters, plugins, and dev tooling
- **`tooling/`** — Internal build tooling: V8 snapshot creation, `packherd` dependency bundler, and `electron-mksnapshot`
- **`system-tests/`** — Full end-to-end system test suite: `test/` runs against the dev app, `test-binary/` against a built Cypress binary
- **`scripts/`** — Internal build, release, and CI automation scripts

## Task runbooks

Step-by-step procedures live in [`guides/`](./guides/) — start there for any multi-step workflow ([release process](./guides/release-process.md), [writing the changelog](./guides/writing-the-cypress-changelog.md), [V8 snapshots](./guides/v8-snapshots.md), and others indexed in [`guides/README.md`](./guides/README.md)). They are the canonical source for humans and agents alike.

`.claude/skills/*/SKILL.md` adds a thin layer on top for the two workflows that need agent-specific execution guidance — which permissions a phase needs, long-running commands, and host quirks that would be noise in a contributor guide. Claude Code loads them on demand; **other agents should read the file directly**, since nothing loads them automatically:

- [`building-cypress-binary`](./.claude/skills/building-cypress-binary/SKILL.md) — `binary-build` / `binary-package` / `binary-zip`, non-interactive flags, `ELECTRON_RUN_AS_NODE`, macOS signing.
- [`debugging-cypress-artifacts`](./.claude/skills/debugging-cypress-artifacts/SKILL.md) — bugs that only reproduce in packaged output, the commit/build/clean/reset loop, `CYPRESS_RUN_BINARY`.

`.claude/rules/*.md` is a second thin layer, for facts that are only correct in one part of the tree — which test runner a package uses, which runtime floor a directory is bound by, how a given kind of snapshot is regenerated. Each file carries a `paths:` glob, and Claude Code loads it when it opens a matching file. They are pointers, not sources of truth: every one links back to the guide or `AGENTS.md` section that owns the topic, so **other agents can skip them** and lose nothing.

Add new guidance to a guide by default. A skill is only warranted when the content is about *running* the task rather than doing it correctly — if a contributor doing the task by hand would need to know it, it belongs in the guide. A rule is only warranted when the guidance is wrong outside a specific path. See [Choosing where guidance goes](./CONTRIBUTING.md#choosing-where-guidance-goes).

## Prerequisites

- **Node**: Use the node version specified in the `.node-version` file (check with `node -v`; run `nvm use` to manage versions)
- **Package manager**: Yarn 1 (`yarn@1.22.22`) — do not use npm or pnpm
- **Lerna**: Orchestrated via root `package.json` scripts; installed as a dev dependency
- **Electron** (for binary builds): handled automatically by `@packages/electron` during build

## Common Commands

### Setup & Development

```bash
# Install all dependencies (runs post-install hooks automatically)
yarn

# Start Cypress in dev mode (watch, rebuilds on change)
yarn dev

# Open the Cypress GUI in dev + global mode
yarn start

```

### Testing

```bash
# Run a single package's tests (go through the workspace, not the root test script —
# the root script hardcodes its own --scope flags and lerna unions them, so
# `yarn test --scope <pkg>` runs the whole default suite plus that package)
yarn workspace @packages/server test

# Target a specific vitest spec file (packages that use vitest)
yarn workspace @packages/config test -- <path-to-spec>

# Target a specific vitest spec by glob pattern
yarn workspace @packages/net-stubbing test -- "<glob-pattern>"

# Target a specific mocha spec file (packages that use mocha)
yarn workspace @packages/server test-unit -- <path-to-spec>

# Filter mocha tests by name pattern
yarn workspace @packages/server test-unit -- --grep "<pattern>"

# @packages/data-context is the one package on jest, not vitest or mocha
yarn workspace @packages/data-context test-unit -- <path-to-spec>

# Run system test specs whose file name contains a fragment (not a path);
# see system-tests/AGENTS.md
yarn test-system go_spec --browser electron

# Run Cypress headlessly against a specific spec (dev mode)
yarn cypress:run -- --spec "path/to/spec.cy.ts"

# Run Cypress component tests against a specific spec (dev mode)
yarn cypress:run:ct -- --spec "path/to/spec.cy.ts"
```

### Type Checking

```bash
# Type-check all TypeScript across the monorepo
yarn type-check

# Lerna-only type check pass
yarn check-ts
```

### Linting & Formatting

```bash
# Lint all packages (no bail, concurrency 2)
yarn lint

# Lint and auto-fix specific scopes
yarn lint:fix
```

> **Note**: This project does **not** use Prettier. All formatting is enforced via ESLint.

The repo is mid-migration between two ESLint configs, so ignore rules live in two places: `ignorePatterns` in the root `.eslintrc.js` for the packages still on eslintrc, and the `ignores` block in `packages/eslint-config/src/baseConfig.ts` for the packages on flat config. Build output (`cjs/`, `esm/`, `dist/`) is already ignored in both; do not add a per-package `.eslintignore` for it, since patterns in those files that contain a `/` silently match nothing. [The ESLint migration guide](./guides/eslint-migration.md#6-ignore-build-output-centrally) explains the mechanism.

### Build

```bash
# Full monorepo build
yarn build

# Build V8 snapshot (dev)
yarn build-v8-snapshot-dev

# Build V8 snapshot (prod)
yarn build-v8-snapshot-prod

# Clean all build artifacts
yarn clean

# Clean and reinstall (nuclear)
yarn clean-deps && yarn
```

## Architecture

Orientation, not a registry — the directories under `packages/`, `npm/`, and `tooling/` are the authoritative list, and each carries its own `AGENTS.md` with the detail. Read a package's own file before working in it rather than relying on the one-liner here.

### CLI & Distribution

- **`cypress` (`cli/`)** — The `cypress` npm package users install. Entry point for `cypress open`, `cypress run`, `cypress install`, etc. The published version is set by semantic-release, not by `cli/package.json` (which stays `0.0.0-development`).

### Test Runner & Driver

- **`@packages/driver`** — The JavaScript test driver that executes user test code inside the browser. Implements Cypress commands, assertions, retries, and all `cy.*` APIs.
- **`@packages/runner`** — The webpack-bundled runner UI that hosts the AUT (application under test) iframe and driver communication layer.
- **`@packages/app`** — The Vue 3 frontend for the Cypress GUI / Launchpad. Main visual interface for the desktop app.
- **`@packages/launchpad`** — Project creation, onboarding, and test file scaffold UI.
- **`@packages/frontend-shared`** — Shared Vue components and design system tokens used by `app` and `launchpad`.
- **`@packages/reporter`** — The test results reporter UI component (pass/fail tree, log panel).

### Server & Network

- **`@packages/server`** — HTTP server responsible for serving test files, handling browser launching, socket communication, and orchestrating the test run.
- **`@packages/proxy`** — HTTP/S proxy that intercepts all browser traffic during a test run.
- **`@packages/net-stubbing`** — The `cy.intercept` surface: driver-side command, types, and the server-side glue.
- **`@packages/network-interception`** — Transport-agnostic core behind `cy.intercept`: route matching, subscription planning, handler merging, and config policy. Holds the rules, none of the I/O — every transport is injected behind an interface.
- **`@packages/network`** — Low-level network protocol utilities.
- **`@packages/network-tools`** — Higher-level networking helpers used across packages.
- **`@packages/https-proxy`** — HTTPS proxy implementation for TLS interception.

### Configuration & Data

- **`@packages/config`** — Configuration types, defaults, validation, and the public `defineConfig` API.
- **`@packages/data-context`** — Centralized GraphQL data access layer for the Cypress app (projects, specs, runs, settings).
- **`@packages/scaffold-config`** — Logic for scaffolding new testing setups via Launchpad (framework detection, config file generation).