Principle:Cypress io Cypress Configuration Validation
| Knowledge Sources | |
|---|---|
| Domains | Configuration, Validation |
| Last Updated | 2026-02-12 00:00 GMT |
Overview
A schema-based validation mechanism that ensures configuration values, browser definitions, and client certificates conform to expected types and constraints before test execution.
Description
Configuration validation prevents runtime errors by catching invalid configuration at startup. Each configuration option defines a validation function that checks type constraints, value ranges, and structural requirements. Browser objects must have required fields (name, family, version, path, majorVersion). Client certificate configurations must have valid URL patterns and file paths.
Validation produces structured error results (ErrResult) that contain the key, value, and expected type, enabling detailed error messages that guide users to fix their configuration.
Usage
Use this principle during configuration resolution, after all sources have been merged. It runs before any test execution begins and rejects invalid configurations with descriptive error messages.
Theoretical Basis
Validation Pipeline:
1. Merge all config sources (defaults + file + env + CLI)
2. For each config option:
a. Check if value matches option.validation function
b. If invalid → ErrResult { key, value, type }
3. Validate browser list:
a. Each browser must have: name (string), family (chromium|firefox|webkit),
displayName (string), version (string), path (string), majorVersion (string|number)
4. Validate client certificates:
a. URL pattern, cert file, key file must exist
5. Return validated config or throw with all errors