# How to Run Tests Within the Cypress Monorepo > Learn to run tests in the Cypress monorepo using yarn test-unit at the root or yarn workspace for specific packages. Filter specs with file paths or grep patterns. - Repository: [Cypress.io/cypress](https://github.com/cypress-io/cypress) - Tags: how-to-guide - Published: 2026-08-06 --- **To run tests in the Cypress monorepo, use `yarn test-unit` at the root for all packages, or `yarn workspace @packages/ 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. ```bash 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`](https://github.com/cypress-io/cypress/blob/main/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: ```bash 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`](https://github.com/cypress-io/cypress/blob/main/packages/server/package.json) (line 21): ```bash yarn workspace @packages/server test-unit ``` Similarly, the CLI package defines its test script in [`cli/package.json`](https://github.com/cypress-io/cypress/blob/main/cli/package.json) (lines 16-18), which you can invoke with: ```bash 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: ```bash 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`](https://github.com/cypress-io/cypress/blob/main/packages/server/AGENTS.md) (lines 12-15): ```bash 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: ```bash 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`](https://github.com/cypress-io/cypress/blob/main/AGENTS.md) documents the `cypress:run` command, which wraps the CLI entry point: ```bash 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`](https://github.com/cypress-io/cypress/blob/main/AGENTS.md) files. ### CI Pipeline Optimization The CI configuration in [`.circleci/AGENTS.md`](https://github.com/cypress-io/cypress/blob/main/.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/ 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`](https://github.com/cypress-io/cypress/blob/main/package.json) scripts and [`AGENTS.md`](https://github.com/cypress-io/cypress/blob/main/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`](https://github.com/cypress-io/cypress/blob/main/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`](https://github.com/cypress-io/cypress/blob/main/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`](https://github.com/cypress-io/cypress/blob/main/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.