Q35 of 48 · Cypress
How would you architect a large Cypress test suite for a multi-team monorepo?
Short answer
Short answer: One Cypress install at the monorepo root, but tests organised by team or product area in their own folders. Share configuration via a base config + per-area overrides. Run only the changed area on PR (test impact analysis or path-based CI rules). Standardise commands and fixtures in a shared package consumed by every team.
Detail
A monorepo with five product teams running Cypress runs into three problems quickly: duplicated setup, divergent conventions, and a CI bottleneck. The architecture that scales:
1. Single Cypress install at the root. Avoid per-package installs — they explode node_modules size, complicate CI caching, and create version drift. One cypress dependency, one config file, one runner.
2. Per-area folders inside cypress/e2e/ — cypress/e2e/auth/, cypress/e2e/checkout/, cypress/e2e/admin/. Code-owners (CODEOWNERS) per folder so the right team is paged for failures.
3. Shared support package. A @org/cypress-support package (still in the same monorepo) exposes the custom commands, fixtures helpers, page object bases, and CI utilities every team needs. Each team imports from it; nobody re-implements cy.loginAs.
4. Per-area config overrides. A base cypress.config.ts that extends with area-specific settings:
// cypress.config.ts (base)
export default defineConfig({
e2e: {
baseUrl: 'http://localhost:3000',
specPattern: 'cypress/e2e/**/*.cy.ts',
},
retries: { runMode: 2, openMode: 0 },
});
// cypress.checkout.config.ts (area override)
import base from './cypress.config';
export default defineConfig({
...base,
e2e: { ...base.e2e, specPattern: 'cypress/e2e/checkout/**/*.cy.ts' },
env: { ...base.env, paymentSandbox: 'https://sandbox.example.com' },
});
5. Path-based CI selection. GitHub Actions / Buildkite gates: a PR touching /checkout/ only runs cypress/e2e/checkout/. A PR touching shared libs runs everything. Tools like nx affected or Bazel can compute this for you; otherwise hand-write the rules.
6. Sharded execution per area. Even within an area, shard across runners by spec to keep wall time under 10 minutes. Cypress Cloud or duration-balanced sharding both work.
7. Quality bars enforced in CI. No .only in committed specs (ESLint rule). Flaky tests must be quarantined within 7 days or deleted. New specs require code-owner approval. Each area publishes its escape rate quarterly.
The senior signal: you know the technical setup is the easy part — the harder part is enforcing standards across teams and giving each team enough autonomy without divergence.