Where to Find Cypress Internal APIs Documentation: A Developer’s Guide

Cypress internal APIs are documented directly in the TypeScript source code within the packages/ directory of the cypress-io/cypress monorepo, with each package exposing its public interface through top-level index.ts files containing JSDoc comments and type definitions.

The cypress-io/cypress repository is organized as a monorepo where Cypress internal APIs live alongside the implementation code. Unlike the public user-facing documentation, these internal interfaces are not published as a separate website; instead, the source files themselves serve as the authoritative reference for developers extending or contributing to the framework.

Core Internal API Packages

The monorepo splits functionality into self-contained npm packages under the packages/ directory. Each package exports its internal API through a main entry point, typically src/index.ts or lib/index.ts, accompanied by TypeScript definitions and inline documentation.

Configuration API

The Configuration API handles how Cypress reads, validates, and normalizes configuration objects. The primary entry point is packages/config/src/index.ts, which exports defineConfig for creating type-safe configuration objects and validation utilities for merging user settings with defaults.

Test Driver API

Located in packages/driver/src/index.ts, the Test Driver API implements the cy.* command system that executes inside the browser. This package contains command registration logic, retry mechanisms, and the custom command API used to extend Cypress functionality.

Server and Proxy API

The Server and Proxy API manages the HTTP server, browser launcher, proxy interception, and WebSocket communication. The main implementation resides in packages/server/lib/api/server.ts, exposing the Server class for handling incoming requests and socket messages.

Network Stubbing API

For request interception and mocking, the Network Stubbing API in packages/net-stubbing/lib/adapters/index.ts provides the underlying implementation for cy.intercept. This includes stubbing adapters, matcher logic, and response shaping utilities.

Error Handling API

Centralized error management lives in packages/errors/src/index.ts. The Error Handling API defines CypressError and its subclasses, along with formatting utilities used across the codebase to maintain consistent error reporting.

Telemetry and Snapshot APIs

Additional specialized packages include the Telemetry API (packages/telemetry/src/index.ts), which wraps OpenTelemetry for internal event tracking, and the V8 Snapshot Require API (packages/v8-snapshot-require/src/index.ts), which implements a custom require loader for pre-bundled V8 snapshots used by the Electron application.

Navigating the Source Code for API Documentation

To locate Cypress internal APIs documentation within the repository:

1. Open the packages/ directory to view the monorepo structure.

2. Select the relevant package based on functionality (e.g., config, driver, server).

3. Look for the top-level index.ts or index.js file in the src/ or lib/ folder, which re-exports the public members of that package.

4. Read the JSDoc comments and TypeScript definitions, which serve as the primary documentation for method signatures, parameter types, and return values.

Practical Examples: Importing Internal APIs

The following examples demonstrate how internal APIs are imported and used within Cypress's own packages. These patterns are intended for developers building plugins or contributing to the framework, not for end-users writing test specifications.

Importing the Configuration API

import { defineConfig, getConfig } from '@packages/config'

// Create a custom config object
const myConfig = defineConfig({
  e2e: {
    baseUrl: 'http://localhost:3000',
    specPattern: 'cypress/e2e/**/*.cy.ts',
    video: false,
  },
})

// Retrieve the resolved configuration (merged with defaults)
const resolved = getConfig()
console.log('Resolved config:', resolved)

Source: packages/config/src/index.ts

Using the Test Driver API

import { cy } from '@packages/driver'

// Register a custom command
cy.addCommand('login', (username: string, password: string) => {
  cy.request('POST', '/login', { username, password })
    .its('status')
    .should('eq', 200)
})

// Use the command in a test (inside the AUT browser)
cy.login('alice', 'secret')

Source: packages/driver/src/index.ts

Interacting with the Server API

import { Server } from '@packages/server/lib/api/server'

// Create a temporary server instance for integration tests
const server = new Server({ port: 0 })   // 0 => auto-assign port
await server.start()

// Send a custom WebSocket message
server.send({ event: 'custom:event', data: { foo: 'bar' } })

Source: packages/server/lib/api/server.ts

Working with Network Stubbing

import { createStub } from '@packages/net-stubbing/lib/adapters'

// Stub all GET requests to /api/users
createStub({
  method: 'GET',
  url: '/api/users',
  response: { statusCode: 200, body: [{ id: 1, name: 'Alice' }] },
})

Source: packages/net-stubbing/lib/adapters/index.ts

Summary

• Cypress internal APIs are not published as standalone documentation; the TypeScript source code serves as the primary reference.
• The repository follows a monorepo structure under packages/, with each package exposing its API through index.ts entry points.
• Key packages include config (configuration), driver (test commands), server (HTTP/proxy), and net-stubbing (request interception).
• JSDoc comments and TypeScript definitions in files like packages/config/src/index.ts and packages/driver/src/index.ts provide method signatures and usage details.
• Import paths follow the @packages/ prefix convention when working within the Cypress codebase.

Frequently Asked Questions

Are Cypress internal APIs stable for third-party plugin development?

No, Cypress internal APIs are considered private implementation details and may change without notice between versions. Plugins should rely on the public API surface documented on the official Cypress documentation site. Use internal APIs only when contributing to the core repository or when absolutely necessary, acknowledging that future updates may require code changes.

How do I import internal APIs when developing within the Cypress repository?

When working inside the cypress-io/cypress monorepo, import internal modules using the @packages/ prefix followed by the package name. For example, use import { defineConfig } from '@packages/config' or import { Server } from '@packages/server/lib/api/server'. The repository's build system resolves these aliases to the corresponding packages/ subdirectories.

What is the difference between public and internal Cypress APIs?

Public APIs are the documented, stable interfaces exposed to end-users writing tests, such as cy.visit() or Cypress.config(), and are guaranteed to follow semantic versioning. Cypress internal APIs are the supporting infrastructure used by the framework itself—such as the Server class in packages/server/lib/api/server.ts or configuration validators in packages/config/src/index.ts—which are not covered by the public API contract and can change between releases.

Where are TypeScript definitions for internal APIs located?

TypeScript definitions for Cypress internal APIs are co-located with the implementation files, typically in *.d.ts files or as inline JSDoc comments within the source. The main entry points—such as packages/config/src/index.ts, packages/driver/src/index.ts, and packages/errors/src/index.ts—export fully typed interfaces that serve as the authoritative documentation for function parameters, return types, and class methods.

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