Q9 of 48 · Cypress
What is the role of cypress.config.ts (or .js)?
Short answer
Short answer: It's the single source of truth for Cypress configuration — baseUrl, viewport, timeouts, retries, environment variables, and per-mode (e2e/component) setup. Cypress reads it on startup and merges it with CLI flags and env vars.
Detail
cypress.config.ts exports a defineConfig({...}) object. The most-used keys:
baseUrl— base for relativecy.visitcalls.viewportWidth/viewportHeight— default browser size.defaultCommandTimeout— how long retried commands wait (default 4000 ms).retries—{ runMode: 2, openMode: 0 }retries failed tests in CI but not locally.env— custom environment variables, accessed viaCypress.env('key').e2e/componentblocks — per-mode config includingsetupNodeEvents(Node-side hooks, plugins, file loading).
The merge order at runtime: defaults → cypress.config.ts → CLI flags (--config) → env vars (CYPRESS_*). CLI wins.
Per-environment overrides usually come from passing --config-file cypress.staging.config.ts, or from CYPRESS_baseUrl=https://staging... at run time. Avoid hard-coding environment URLs in specs — drive them through config.
setupNodeEvents is the place to register Node-side tasks (cy.task handlers), modify the browser launch, hook into spec results, or load environment-specific config from disk.
// EXAMPLE
cypress.config.ts
import { defineConfig } from 'cypress';
export default defineConfig({
e2e: {
baseUrl: process.env.CYPRESS_BASE_URL ?? 'http://localhost:3000',
specPattern: 'cypress/e2e/**/*.cy.ts',
supportFile: 'cypress/support/e2e.ts',
setupNodeEvents(on, config) {
on('task', {
seedDb({ user }) {
// Node-side seeding
return null;
},
});
return config;
},
},
retries: { runMode: 2, openMode: 0 },
defaultCommandTimeout: 5000,
viewportWidth: 1280,
viewportHeight: 800,
env: {
apiUrl: process.env.CYPRESS_API_URL ?? 'http://localhost:4000',
},
});