Principle:Cypress io Cypress Project Configuration
| Knowledge Sources | |
|---|---|
| Domains | Configuration, Testing |
| Last Updated | 2026-02-12 00:00 GMT |
Overview
A layered configuration resolution mechanism that merges defaults, config file values, environment variables, and CLI overrides into a single resolved configuration object.
Description
Project configuration in a test framework must support multiple sources of configuration with clear precedence rules. Cypress uses a layered resolution pipeline: hardcoded defaults form the base, the user's cypress.config.{ts,js} file overrides those defaults, environment variables (prefixed with CYPRESS_) override the config file, and CLI flags take highest precedence.
Each configuration option is defined with a name, default value, validation function, and metadata about which override levels are permitted (suite-level, test-level, or never).
Usage
Use this principle when understanding how Cypress resolves its runtime configuration. It applies to both E2E and Component testing modes, with certain options having different defaults per testing type (e.g., slowTestThreshold is 10000ms for E2E, 250ms for component).
Theoretical Basis
The configuration resolution follows a strict merge order:
Priority (lowest to highest):
1. Default values (from options.ts definitions)
2. Config file values (cypress.config.ts)
3. Environment variables (CYPRESS_*)
4. CLI flags (--config key=value)
5. Suite/test overrides (Cypress.config() at runtime)
Each option defines its permitted overrideLevels: any (all levels), suite (config file + suite), or never (only default/config file).