cypress-io/cypress
github.com/cypress-io/cypress ↗ · 3999 files · 15.6 MB · scan capped
Documentation | Changelog | Roadmap The web has evolved.
Overview
Cypress is a browser testing platform for developers running end-to-end and component tests locally or in CI. This monorepo combines the installable CLI and Node API, an Electron application, a browser-side command driver, Vue interfaces, and framework/bundler integrations. At commit 7d987f04740f8f5388ac3116e8ef7957373ead14, distinctive implementation details include shared interception logic across HTTP-proxy and Chromium CDP transports, GraphQL application state, and CLI attachment to existing interactive sessions.
System map
The system spans a user-Node CLI, an Electron main process, a configuration/plugin child process, and browser bundles. The application exposes GraphQL and browser communication services while coordinating projects and network interception. Distribution includes an npm module and platform-specific desktop binaries, with separate build and release machinery.
- Yarn workspaces cover cli, packages, npm, tooling, system-tests, and scripts; Lerna uses the same package layout and selects Yarn as its npm client.
- The executable entry calls CLI.init(); the module entry exports open, run, cli, defineConfig, and defineComponentFramework.
- Server startup installs the require hook before loading start-cypress; runElectron dispatches directly to modes when already inside Electron and otherwise opens an Electron child.
- ProjectConfigIpc forks configuration code with cwd at the config file's directory and execPath set to the resolved user Node; cli/package.json supports Node ^22, ^24, or >=26.
- The Vue application uses generated hash-history routes; its state backend builds a Nexus GraphQL schema with DataContext as context and a wrapped remote schema.
- createProxyRuntime and createCdpFetchRuntime compose interception transports; both receive the server-owned NetStubbingState rather than creating independent route state.
- Inspected local storage includes versioned binary caches, project/global state.json files, and PID-named interactive-session records; these serve different lifecycle owners.
- Root build runs the Lerna build, Electron binary build, and CLI build; release documentation distinguishes independently published @cypress packages from desktop binaries promoted in S3 and the cypress npm artifact.
Feature catalog
The inspected user surfaces include terminal execution, the Node API, interactive spec management, component mounting, network interception, and Cypress Cloud integration. The tap command adds discovery and control of an existing open-mode session. This catalogue groups evidenced capabilities; the bounded inspection does not enumerate every cy command, UI component, or published integration.
- cypress run exposes E2E/component selection, browser and spec filtering, config overrides, reporters, headed/headless operation, recording, parallel groups, cancellation thresholds, and POSIX exit codes.
- cypress open supports project/global mode, testing-type selection, browser/config overrides, and detached launch; install, verify, cache, version, and info provide installation and diagnostic operations.
- The Node API provides open() and run(); run() returns parsed run output or a structured failed result when the binary produces no readable results. defineConfig() and defineComponentFramework() return their input objects.
- The Specs page presents a spec list or no-specs state, opens CreateSpecModal, and subscribes to spec changes; Settings queries configuration and subscribes to configChange.
- cy.intercept accepts URL, method/URL, or matcher-object overloads and function, string-body, or static-response handlers; middleware requires a function handler.
- React mount() clears the previous root, creates a ReactDOM root, and delegates to makeMountFn; the CLI exports React, Vue, Angular, and Svelte adapters, while the Vite dev-server integration resolves project Vite and warms support/spec modules conditionally.
- Cloud-facing features include login/signup and viewer validation, recorded/parallel run orchestration, and a Runs page that selects Git-tree or project runs and refetches after connectivity returns.
- cypress tap accepts session PID, JSON output, and timeout options; CLI-owned subcommands include sessions, status, specs, run, dom, aria, and inspect, with browser driving limited to Chromium-family sessions.
Data flow
Inputs cross explicit boundaries through CLI argument translation, configuration IPC, GraphQL operations, and network-event frames. State is split between DataContext, browser route/command state, server interception state, and local persistence. Outputs include browser responses, UI subscriptions, JSON run results, process exit codes, and session discovery records.
- processRunOptions translates user options into binary flags, including --run-project, config/env, recording key, reporter, and specs; spawn.start adds cwd, userNodePath, and userNodeVersion.
- Configuration crosses into a child as project/config arguments and inherited environment; RunPlugins sends modified setupConfig and event registrations back through setupTestingType:reply.
- GraphQL socket requests parse JSON and query text, execute graphqlSchema with a request context, return results through a callback, and balance DataContext active-request accounting in finally.
- The driver annotates regex/glob matchers for transport, lowercases header matcher names, stores handlers locally by routeId, and emits route:added; the server restores matcher types and appends BackendRoute to state.routes.
- Matching excludes component dev-server paths and can synthesize preflight responses; matchRoutes orders middleware first, ordinary handlers in reverse registration order, and excludes disabled routes.
- Interception buffers request/response bodies, preserves binary content, exchanges subscription events with browser handlers, merges changes, and either ends a stubbed request or continues transport with a modified body stream.
- Interactive-session JSON holds schema, PID, resolved project root, port, session ID, and testing type; CDP/browser attachment remains in memory, while the probe reads machine/user identity at request time.
- runSpecs aggregates per-spec statistics, transforms results with createPublicRunResults, invokes after:run, and writes output; programmatic run() supplies a temporary output path and reads that JSON after the child finishes.
Behavior traces
Three concrete flows were followed across their relevant files: test-run startup/results, interception registration through response completion, and interactive-session persistence through CLI attachment. The traces below retain important branches such as dev verification bypass, recording delegation, static-response termination, and browser-readiness filtering. A supplementary startup trace explains how the interactive window becomes available.
- Run entry: bin/cypress.ts → CLI.init() → run command action → runModule.start() → processRunOptions() → spawnStart(); non-dev execution awaits binary verify.start(), while dev execution bypasses it.
- Run initialization: cypress.start() parses argv and selects run for runProject → startInMode() → runElectron() → modes factory → setCtx(makeDataContext()) and initializeMode() → modes/run.run() awaits loading and calls ready().
- Run completion: ready() discovers browsers and opens the project, validates recording parameters, and handles empty specs; runAllSpecs() calls runSpecs(), which invokes before:run → iterateThroughSpecs/runEachSpec → runSpec() → after:run → writeOutput(). Recording delegates through createRunAndRecordSpecs; POSIX mode collapses failure counts except reserved code 112.
- Intercept registration: addCommand() installs intercept → getMatcherOptions() → validateRouteMatcherOptions() → addRoute() → emitNetEvent('route:added') via Cypress.backend('net', ...) → onNetStubbingEvent() → onRouteAdded().
- Intercept request: SetMatchingRoutes() applies dev-server/preflight conditions and core.matchRoutes() → InterceptRequest() → core.handleRequest() → handleInterceptRequest() creates and registers InterceptedRequest → ensureBody() → addDefaultSubscriptions() → before:request handlers → merge changes → end() if responseSent, otherwise continueRequest().
- Intercept response: handleInterceptResponse() bypasses unmatched requests, obtains a plain-text/binary body, invokes before:response → response:callback → response subscriptions, merges response/header changes, and continues with getBodyStream(); response finish emits after:response and removes the request from server state.
- Session lifecycle: ProjectBase registers an open-mode session → addSession() creates UUID identity → persist() serializes writes and renames a temporary JSON file → CLI readLiveSessions() validates records/reaps dead PIDs → verifySessionRecord() checks the session echo and CDP /json/version → resolveSession() filters ready supported sessions → CDP attachment probes page targets for the tap binding.
- Interactive startup: modes factory starts initializeMode() → interactive.run() concurrently awaits app.whenReady() and makeGraphQLServer() → ready() loads saved state and opens the desktop window → optional 'Cypress is ready' sentinel lets detached CLI spawning destroy streams, unref the child, and resolve.
Testing signals
Tests and CI were inspected, not executed; their existence is not a passing result. The repository combines Vitest, Mocha, Jest, Cypress browser suites, and a system-test harness. Inspected coverage includes option translation, session persistence/probing, subscription behavior, configuration child failures, and browser interception. The inventory and test inspection are bounded, so local TODOs and mocks describe specific limits rather than whole-repository coverage gaps.
- Root Vitest discovers package/tooling/script project configurations and the CLI project, excludes system-tests, and configures V8 coverage plus default/JUnit reporting; server test-unit runs Mocha then Vitest, while data-context uses Jest with experimental VM modules.
- CLI run tests assert project-path rejection, conflicting headed/headless flags, testing-type choices, and POSIX argument forwarding; verify/spawn are mocked, so these tests do not establish real binary launch behavior.
- Server session tests use temporary cache directories and inspect actual JSON files, covering immutable identity, temporary-file cleanup, swallowed write failure, pending-write removal, and project-switch preservation.
- CLI session tests exercise fake HTTP sessions and closed ports, asserting rejection of recycled-port/session mismatches, malformed JSON, timeout, and stale CDP endpoints while retaining browser identity.
- InterceptedRequest Vitest tests resolve pending handlers through a mocked socket and assert enabled/disabled subscription dispatch counts; they do not exercise a real proxy or CDP transport.
- The driver interception suite asserts route state and backend event frames in browser tests, but declares 15 retries and unique route names for documented flakiness/request leakage. runEachSpec also carries an explicit TODO for a cancelled just-in-time component-run system test.
- A Jest ProjectConfigIpc test loads a real configuration child and injects EPIPE; system config tests cover invalid settings and JS/TS config filenames, and the harness offers withBinary mode. A config-spec TODO requests environment-variable coverage locally.
- Inspected CircleCI definitions gate contributor builds behind approval, select suites through pipeline parameters, add Chrome forceHttp1 smoke coverage, and aggregate browser/system/type/lint checks at ready-to-release; GitHub Actions separately checks semantic PR titles/changelog and generates release SBOMs.
Risk map
These are source observations and explicitly marked hypotheses, not confirmed vulnerabilities. Sensitive boundaries include configuration execution, privileged browser-to-server commands, filesystem access, GraphQL listeners, and CDP session control. Transport switching and V8 snapshot composition create substantial coupling. Runtime validation and broader test results remain unknown because this investigation executed no repository code.
- Configuration/plugin execution is a host-code boundary: ProjectConfigIpc inherits most process environment and forks with the user Node, while RunPlugins calls setupNodeEvents and later invokes registered handlers.
- PrivilegedCommandsManager validates channel keys and command name/args for E2E requests before dispatching env, file, origin, and task operations; hasVerifiedCommand uses find() without removing the entry despite its removal comment.
- readFile/writeFile resolve caller paths against projectRoot without a containment check in those helpers; absolute paths or parent traversal can therefore address locations outside the project. Whether a caller is authorized depends on upstream command controls.
- Hypothesis for focused review: the Launchpad GraphQL listener supplies no explicit bind host and accepts requests without Origin; its CORS denial controls browser response visibility rather than being an authentication check. Actual reachability and exploitability were not tested. (inferred)
- Session probes expose live CDP URL and machine/user identity when the URL session ID matches; session identity is persisted under the cache. The project server binds loopback, and CLI probes additionally require matching identity and reachable CDP, making local record/endpoint access a sensitive boundary.
- Transport switching must preserve the same stubbing-state object and publish mode/runtime consistently; server comments identify broken intercept matching and disagreement with the still-running browser as failure modes.
- cy.exec's server module remains imported solely for V8 snapshot composition and throws a Cypress 16 removal error; deleting this apparently obsolete stub has a documented mksnapshot failure risk.
- A successful production-build command alone does not prove type correctness: server build-prod and data-context build-prod explicitly tolerate tsc failure, while separate check-ts scripts enforce no-emit checks.
Extension points
Public customization is concentrated in Cypress command registration, setupNodeEvents, component adapters, and CLI APIs. Internal extension seams include injected network ports, ordered policies, generated frontend routes, and Nexus schema plugins. New code should enter through the owning seam because transport, generated-artifact, and process boundaries constrain implementation placement.
- Cypress.Commands supports add/addAll, overwrite, and addQuery; registration protects built-in/reserved names and derives parent/child/dual command behavior from prevSubject.
- setupNodeEvents receives registerChildEvent and initialConfig; event registrations are validated, repeated task registrations merge, and a default file preprocessor is installed only when the user supplies none.
- Plugin execution dispatch has specific wrappers for dev-server:start, file:preprocessor, browser launch, tasks, and run/spec/screenshot lifecycle events.
- NetworkInterceptionCore accepts injected policy, request/response, document preparation, capture, cookie, command-log, and browser-automation ports; effects are delegated rather than embedded in matching logic.
- NetworkPolicyRegistry.add appends policies; runPolicies filters by phase and when(exchange), applies policies sequentially with shared state, and stops after end().
- Frontend pages plug into virtual:generated-pages and generated layouts; createRouter adds default-page redirection and installs the Studio unsaved-changes navigation guard.
- GraphQL extension uses schemaTypes, remote-schema merging, and structural/runtime Nexus plugins; mutations and filesystem writes are intended to run through DataContext.actions.
- Component integration offers defineComponentFramework and a devServer contract returning port/close; tap has an ordered CLI command registry that precedes commands advertised by the running session's schema.
Contributor handoff
Tests and CI were inspected, not executed, and no repository files were changed. Future implementation work should start from package-local guidance and identify the runtime, generated artifacts, and test runner before editing. The highest-value boundaries to preserve are shared interception state, session identity/persistence, user-Node configuration execution, and public CLI/module compatibility. This is a bounded investigation rather than exhaustive inventory or verification.
- Read root/package AGENTS.md and the appropriate guides before implementation; package documentation supplies architecture and runner details, and canonical multi-step workflows belong in guides.
- Use Yarn 1 and existing workspace scripts; avoid root yarn test --scope for narrowing because its hardcoded Lerna scopes broaden the run.
- Identify the runtime before using APIs: CLI/config-child support follows cli engines, the main process follows Electron, and browser bundles have a separate browser floor.
- New code and fixtures use TypeScript and ESLint conventions; preserve single quotes, no semicolons, two-space indentation, type-only imports, and documented skip reasons.
- Edit CT adapter sources under npm rather than copied cli artifacts; regenerate Nexus/schema outputs through data-context build, and rebuild the shared session contract before CLI consumers pick up changes.
- For execution-authorized validation, target CLI Vitest files with yarn workspace cypress test-unit -- <spec>, server Mocha with test-unit-mocha, server Vitest with test-unit-vitest, and data-context Jest with test-unit -- <spec>; then run relevant check-ts/lint scripts. These commands were inspected, not run in this audit.
- Keep platform-dependent CLI tests host-independent: mock both os.arch and the arch package, avoid regenerating canonical snapshots to hide host drift, and account for util._cachedArch singleton state.
- Interception edits require both browser-CDP and forceHttp1 validation plans; preserve the server-owned state across browser switches, and treat contributor CI approval/parameter filters as execution conditions rather than proof that all suites ran.
Languages
| Language | Files | Share of source |
|---|---|---|
| TypeScript | 2862 | 58% |
| JavaScript | 1645 | 33% |
| JSON | 581 | docs/config |
| Vue | 348 | 7% |
| HTML | 333 | docs/config |
| Markdown | 302 | docs/config |
| CSS | 62 | docs/config |
| Sass | 35 | 1% |
Start reading here
Probable source entrypoint: packages/ — inferred from the directory tree and manifest, not the upstream docs.
Source roots
packages/ (1375 files)
Repository structure
| Top-level path | Files |
|---|---|
packages/ | 1375 |
system-tests/ | 1374 |
npm/ | 673 |
cli/ | 191 |
tooling/ | 146 |
scripts/ | 117 |
guides/ | 25 |
.github/ | 20 |
Docs found: AGENTS.mdCLAUDE.mdCONTRIBUTING.mdREADME.mddocs/ai/README.md
Package
package.json — cypress v0.0.0-development, 80 declared dependencies.
@aws-sdk/client-s3@aws-sdk/credential-providers@babel/eslint-parser@cypress/request@cypress/request-promise@electron/fuses@electron/notarize@graphql-codegen/add@graphql-codegen/cli@graphql-codegen/plugin-helpers@graphql-codegen/typed-document-node@graphql-codegen/typescript
CI & config entrypoints
README.md— Repository readmeAGENTS.md— Agent instructionsCLAUDE.md— Claude instructions.github/workflows/auto_approve_low_risk.yml— GitHub Actions workflow.github/workflows/semantic-pull-request.yml— GitHub Actions workflow.github/workflows/stale_issues_and_pr_cleanup.yml— GitHub Actions workflow.github/workflows/triage_add_to_project.yml— GitHub Actions workflow.github/workflows/triage_add_to_routed_project.yml— GitHub Actions workflow.github/workflows/triage_handle_new_comments.yml— GitHub Actions workflow.github/workflows/triage_update_status.yml— GitHub Actions workflow
Structural health signals
Average score 5.9/10 across 96 analyzed source files; 69 hotspots surfaced.
packages/driver/cypress/e2e/commands/net_stubbing.cy.ts— 1554 lines, score 4 (Large file, Deep nesting)packages/server/test/unit/browsers/cdp-fetch-transport_spec.ts— 1399 lines, score 4.5 (Large file, Deep nesting)system-tests/lib/system-tests.ts— 1337 lines, score 4.5 (Large file, Deep nesting)
These are deterministic review leads — size, churn, and structural signals — not proof of a bug in this project.
Recent history
7d987f04740f2026-10-02 — test: park the real pointer before mounting InlineRunAllSpecs (#34972)0021012994432026-10-02 — chore: Update v8 snapshot cache (#34963)e64db629133b2026-10-02 — chore: migrate 3 @packages/server unit specs to vitest (#34971)50c87b0fde622026-10-01 — docs: tag the released commit instead of a nonexistent version-bump commit (#34967)a91e5188431f2026-09-30 — fix: keep the cookie jar in sync when cookies are set outside the proxy (#34894)