How to Run Tests Within the Cypress Monorepo

To run tests in the Cypress monorepo, use yarn test-unit at the root for all packages, or yarn workspace @packages/<name> test-unit for specific packages, with optional file paths or grep patterns to filter specs.

The Cypress codebase is a Lerna-managed Yarn workspace containing dozens of interdependent packages. Understanding how to run tests within the Cypress monorepo is essential for validating changes to the server, driver, CLI, or other core components. The repository provides standardized scripts that leverage workspace commands to execute unit, integration, and end-to-end suites efficiently.

Prerequisites: Bootstrap the Repository

Before executing any test suite, you must install dependencies and build native components. Running yarn at the repository root installs dependencies for all workspaces, triggers post-install hooks, and builds the V8 snapshot required for the Electron binary.

yarn

Running Unit Tests

Unit tests in the Cypress monorepo are distributed across individual packages, with most using Vitest or Mocha as their test runner according to the source configuration.

Run All Unit Tests Across the Monorepo

To validate the entire codebase, execute the root-level test command. In the root package.json (lines 68-69), the test-unit script is defined to invoke Lerna and run the unit test suite in every workspace that exposes it:

yarn test-unit

Run Tests for a Specific Package

For rapid feedback during development, target a single workspace rather than the entire monorepo. Use the yarn workspace command followed by the package name and test-unit script. For example, to run tests only for the server package as defined in packages/server/package.json (line 21):

yarn workspace @packages/server test-unit

Similarly, the CLI package defines its test script in cli/package.json (lines 16-18), which you can invoke with:

yarn workspace @packages/cli test-unit

Filter Tests by File Path or Pattern

When debugging a specific module, append the file path after a double dash to limit the test scope. The server package uses node ./test/scripts/run.js as its test runner entry point, which accepts additional arguments:

yarn workspace @packages/server test-unit -- test/unit/api_spec.unit.ts

You can also filter by test title using the --grep flag, documented in packages/server/AGENTS.md (lines 12-15):

yarn workspace @packages/server test-unit -- --grep "handles request"

Running Integration and End-to-End Tests

After unit tests pass, validate the complete Cypress application using the integration and E2E suites.

Development Mode

To open the Cypress GUI for interactive development, use the dev-mode scripts. These commands watch and rebuild source changes, then launch the Electron application:

yarn dev    # Watches and rebuilds source

yarn start  # Launches the Cypress GUI

Headless E2E Execution

For CI validation or headless runs, execute the full test suite against a sample project. The root AGENTS.md documents the cypress:run command, which wraps the CLI entry point:

yarn cypress:run -- --project system-tests/projects/e2e --browser chrome --headless

Understanding the Test Architecture

The monorepo structure provides specific advantages for testing at scale.

Workspace Isolation

Each package maintains its own test configuration and runner. This isolation allows @packages/driver to evolve independently of @packages/server without framework conflicts, as detailed in the workspace-level AGENTS.md files.

CI Pipeline Optimization

The CI configuration in .circleci/AGENTS.md leverages the workspace commands to parallelize test execution. Critical packages like @packages/server and @packages/driver run in parallel jobs, while less-critical packages are tested on-demand locally using yarn workspace.

Summary

• Execute yarn test-unit at the root to run all unit tests across every Lerna-managed workspace.
• Target specific packages with yarn workspace @packages/<name> test-unit to reduce feedback time.
• Filter individual specs by appending file paths or use --grep to match test titles.
• Launch the interactive GUI with yarn dev followed by yarn start, or run headless E2E tests via yarn cypress:run.
• Reference package.json scripts and AGENTS.md files for package-specific command variations.

Frequently Asked Questions

Can I run tests for multiple specific packages at once?

Yes. While yarn test-unit runs everything, you can use Lerna filters or chain workspace commands. For example, yarn lerna run test-unit --scope @packages/server --scope @packages/driver executes tests only for the specified scopes, as implemented in the root package.json scripts.

What test frameworks does the Cypress monorepo use?

The monorepo primarily uses Vitest for unit testing, though some legacy packages still utilize Mocha. Each package declares its specific runner in its local package.json and test scripts, allowing frameworks to migrate independently per workspace needs.

How do I debug a failing test in a specific package?

Use the workspace filter to isolate the package, then append the specific spec path. For example: yarn workspace @packages/server test-unit -- path/to/failing.spec.ts. You can also add --inspect to the Node.js flags in the test script for debugger attachment, depending on the package's AGENTS.md instructions.

Where are the integration test fixtures located?

System and integration test fixtures reside in the system-tests/projects/ directory. When running yarn cypress:run, point to these directories using the --project flag, such as --project system-tests/projects/e2e, to execute the E2E suites against standardized fixtures.

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