Cypress 10 ๐ฒ Configuration โ cypress.config.ts and baseUrl
Cypress configuration lives in a single file at the project root: cypress.config.js, cypress.config.ts, or cypress.config.mjs. The file replaced the cypress.json of older versions, and it is an executable Node module rather than a static JSON file, which means it can read environment variables, compute values, and register plugins. The e2e.baseUrl option is the one setting that every project needs: it makes cy.visit("/login") resolve to the application’s origin, and it lets the same test run against localhost, staging, and production by changing the config, not the test.
This chapter covers the config file structure, the baseUrl and the environment overrides, and the options that control the test run. The sections that follow walk through the config shape, the baseUrl patterns, and the per-environment configuration that switches the target without changing the tests.
Key point: cypress.config.ts exports a defineConfig object with an e2e block; e2e.baseUrl makes relative cy.visit paths resolve against the configured origin, and CYPRESS_BASE_URL or --config baseUrl=... overrides it per run without editing the file.
a. The config file structure
The config file exports a configuration object. The defineConfig helper provides type inference for the object, and it is the recommended form for a TypeScript config. The e2e block holds the end-to-end testing options, and the component block holds the component testing options.
// cypress.config.ts
import { defineConfig } from "cypress";
export default defineConfig({
e2e: {
baseUrl: "http://localhost:3000",
specPattern: "cypress/e2e/**/*.cy.{js,jsx,ts,tsx}",
supportFile: "cypress/support/e2e.ts",
viewportWidth: 1280,
viewportHeight: 720,
video: false,
retries: {
runMode: 2,
openMode: 0,
},
setupNodeEvents(on, config) {
// register plugins, tasks, and event listeners
return config;
},
},
});
The setupNodeEvents function is the Node-side hook. It receives the on object for registering event listeners and the config object for reading and modifying the configuration. The plugins that used to live in cypress/plugins/index.js are registered here.
The specPattern controls which files are treated as specs. The default is cypress/e2e/**/*.cy.{js,jsx,ts,tsx}, and a project that colocates its tests elsewhere changes the pattern. The supportFile is the file that runs before every spec; it is where the custom commands and the global beforeEach hooks are registered.
The env block holds the environment variables that the tests read with Cypress.env(). The values can be static, or they can be computed in setupNodeEvents.
export default defineConfig({
e2e: {
baseUrl: "http://localhost:3000",
env: {
apiUrl: "http://localhost:3001/api",
coverage: false,
},
},
});
b. baseUrl and the relative visit
The baseUrl is the origin that cy.visit uses when the argument is a relative path. cy.visit("/login") navigates to ${baseUrl}/login, and the test does not hard-code the host.
// cypress.config.ts
export default defineConfig({
e2e: {
baseUrl: "http://localhost:3000",
},
});
// In the test
cy.visit("/login"); // http://localhost:3000/login
The baseUrl can also be a full URL with a path. cy.visit("dashboard") resolves relative to the base URL’s path, while cy.visit("/dashboard") resolves from the origin. The distinction is the leading slash: a path without the slash is relative to the base URL’s path, and a path with the slash is relative to the origin.
The baseUrl is set in the config, but it can be overridden per run. The CYPRESS_BASE_URL environment variable overrides it, and the --config baseUrl=... CLI flag does the same.
# Override for a staging run
CYPRESS_BASE_URL=https://staging.example.com npx cypress run
# Or with the config flag
npx cypress run --config baseUrl=https://staging.example.com
The override is the pattern for CI. The config file points at localhost for the local run, and the CI job sets CYPRESS_BASE_URL to the deployed environment. The tests do not change; only the config does.
c. Per-environment configuration and the run options
A project that runs against multiple environments uses the env block and the environment variables together. The CYPRESS_ prefix is how Cypress reads an environment variable into the config, and the value overrides the config file’s value.
# Read by Cypress as Cypress.env("apiUrl")
CYPRESS_apiUrl=https://staging.example.com/api npx cypress run
The env block in the config sets the default, and the CYPRESS_ variable overrides it per run. The test reads Cypress.env("apiUrl") and gets the value for the current environment.
The run options control how the tests execute. The retries option sets the retry count for a failed test, and the video option controls whether the run records a video. The viewportWidth and viewportHeight set the browser size, and the defaultCommandTimeout sets the per-command timeout.
export default defineConfig({
e2e: {
baseUrl: "http://localhost:3000",
retries: { runMode: 2, openMode: 0 },
video: true,
videoUploadOnPasses: false,
viewportWidth: 1280,
viewportHeight: 720,
defaultCommandTimeout: 6000,
},
});
The retries object has two keys: runMode for cypress run and openMode for cypress open. The openMode is usually 0 because the developer is watching and can retry manually; the runMode is the CI retry count.
The video option is the recording of the run, and the videoUploadOnPasses option decides whether a passing spec’s video is kept. The video is the debugging artifact for a CI failure that cannot be reproduced locally.
Complete Example Session
// ============================================
// PART 1: THE CONFIG FILE
// ============================================
// cypress.config.ts
import { defineConfig } from "cypress";
export default defineConfig({
e2e: {
baseUrl: "http://localhost:3000",
specPattern: "cypress/e2e/**/*.cy.ts",
supportFile: "cypress/support/e2e.ts",
viewportWidth: 1280,
viewportHeight: 720,
video: false,
retries: { runMode: 2, openMode: 0 },
defaultCommandTimeout: 6000,
env: {
apiUrl: "http://localhost:3001/api",
},
setupNodeEvents(on, config) {
return config;
},
},
});
// ============================================
// PART 2: THE RELATIVE VISIT
// ============================================
// cypress/e2e/login.cy.ts
describe("login", () => {
it("visits the login page", () => {
cy.visit("/login"); // http://localhost:3000/login
cy.get('[data-cy="email"]').type("user@example.com");
});
});
// ============================================
// PART 3: THE OVERRIDE
// ============================================
// CI run against staging
// CYPRESS_BASE_URL=https://staging.example.com npx cypress run
// ============================================
// PART 4: THE ENV ACCESS
// ============================================
describe("api", () => {
it("uses the configured api url", () => {
cy.request(`${Cypress.env("apiUrl")}/health`).its("status").should("eq", 200);
});
});
The parts covered the config file, the relative visit, the CYPRESS_BASE_URL override, and the Cypress.env access.
Quick Reference
Config Structure
| Block | Purpose |
|---|---|
e2e | E2E testing options |
component | Component testing options |
env | Environment variables |
setupNodeEvents | Node-side plugin hook |
Key Options
| Option | Default | Purpose |
|---|---|---|
baseUrl | โ | Relative visit origin |
specPattern | cypress/e2e/**/*.cy.* | Spec discovery |
supportFile | cypress/support/e2e.* | Global setup |
viewportWidth | 1000 | Browser width |
retries | 0 | Retry count |
video | true | Record the run |
defaultCommandTimeout | 4000 | Per-command timeout |
Overrides
| Mechanism | Example |
|---|---|
CYPRESS_BASE_URL | CYPRESS_BASE_URL=https://staging... |
--config | --config baseUrl=... |
CYPRESS_<key> | CYPRESS_apiUrl=... |
Best Practices
โ Do This:
// Set baseUrl in the config
baseUrl: "http://localhost:3000" // โ
// Use relative visits
cy.visit("/login"); // โ
// Override per run
CYPRESS_BASE_URL=https://staging.example.com npx cypress run // โ
โ Don’t Do This:
// Hard-code the host in the test
cy.visit("http://localhost:3000/login"); // โ
// Put secrets in the config
env: { password: "secret" } // โ
// Use `cypress.json`
// (removed in Cypress 10) // โ
Common Pitfalls
| Pitfall | Why It Happens | Fix |
|---|---|---|
cy.visit fails | No baseUrl | Set e2e.baseUrl |
| Staging run hits localhost | No override | CYPRESS_BASE_URL |
| Config not read | Wrong file name | cypress.config.ts |
| Secret leaked | Hard-coded in config | Use CYPRESS_ env var |
Real-World Examples
1. Config file
export default defineConfig({ e2e: { baseUrl: "http://localhost:3000" } });
2. Relative visit
cy.visit("/login");
3. Base URL override
CYPRESS_BASE_URL=https://staging.example.com npx cypress run
4. Env block
env: { apiUrl: "http://localhost:3001/api" }
5. Env access
Cypress.env("apiUrl")
6. Spec pattern
specPattern: "cypress/e2e/**/*.cy.ts"
7. Retries
retries: { runMode: 2, openMode: 0 }
8. Video
video: true
9. Viewport
viewportWidth: 1280, viewportHeight: 720
10. setupNodeEvents
setupNodeEvents(on, config) { return config; }
Visual
The Config File
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ cypress.config.ts โ
โ โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ โ
โ โ export default defineConfig({ โ โ
โ โ e2e: { โ โ
โ โ baseUrl, specPattern, supportFile โ โ
โ โ viewport, retries, video, env โ โ
โ โ setupNodeEvents โ โ
โ โ } โ โ
โ โ }) โ โ
โ โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ โ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
The Base URL Resolution
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ baseUrl: "http://localhost:3000" โ
โ โ
โ cy.visit("/login") โ http://localhost:3000/login โ
โ cy.visit("login") โ http://localhost:3000/login โ
โ cy.visit("https://other.com") โ absolute, baseUrl ignored โ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
Per-Environment Override
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ LOCAL โ
โ cypress.config.ts: baseUrl localhost โ
โ npx cypress open โ localhost โ
โ โ
โ CI โ
โ CYPRESS_BASE_URL=https://staging.example.com โ
โ npx cypress run โ staging โ
โ โ
โ The tests do not change. โ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
The CYPRESS_ Prefix
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ env: { apiUrl: "http://localhost:3001/api" } โ
โ โ
โ CYPRESS_apiUrl=https://staging.example.com/api โ
โ โ โ
โ โผ โ
โ Cypress.env("apiUrl") โ staging value โ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
Summary
| Item | Value |
|---|---|
| Config file | cypress.config.ts |
| Helper | defineConfig |
| E2E block | e2e |
| Base URL | e2e.baseUrl |
| Override | CYPRESS_BASE_URL |
| Spec pattern | e2e.specPattern |
| Support file | e2e.supportFile |
| Env access | Cypress.env(key) |
Key takeaways:
- The config file is a Node module, not JSON.
cypress.config.tsexports adefineConfigobject with thee2eblock, and thesetupNodeEventsfunction is where the Node-side plugins are registered. baseUrlmakescy.visitrelative. The test writescy.visit("/login"), and the config decides whether that resolves to localhost, staging, or production.- The override is how the same tests run against different environments.
CYPRESS_BASE_URLor--config baseUrl=...changes the target without editing the config file, which is the pattern for CI. - The
envblock holds the test-visible variables.Cypress.env("apiUrl")reads the value, and theCYPRESS_apiUrlenvironment variable overrides it per run. - The run options control the CI behavior.
retries.runModesets the retry count,videorecords the run, anddefaultCommandTimeoutsets the per-command timeout.
Remember: The config is the one place where the environment-specific values live. baseUrl is the setting every project needs, because it lets the tests use relative paths and lets the CI job point at a different deployment. The env block and the CYPRESS_ prefix are the mechanism for the other environment-specific values, and the override is the reason the same test file runs against localhost and staging without a code change.
Stop using slow, ad-bloated tool sites! ๐คฎ
๐ Search “KandZ Tools” on Google to use many professional utilities for free.
KandZ.me is the ultimate minimalist hub for:
โ
Finance (Mortgage, Interest, Inflation)
โ
Tech (Base64, JSON, Dev Suite, IP)
โ
Health (BMI, BMR, TDEE)
โ
Productivity (Timer, Workspace, QR)
โก๏ธ Fast & Private
๐ No data leaves your device
๐ 100% Free
๐ Use it now: https://tools.kandz.me
๐ Bookmark itโyouโll need it later!