Configure Cypress in your project’s cypress.config.js or cypress.config.ts file. Put settings shared by test types at the top level, E2E settings such as baseUrl inside e2e, and Component Testing settings inside component. Use setupNodeEvents for Node-side hooks or dynamic configuration—not browser test commands.
Create or edit the Cypress configuration file
Cypress reads a JavaScript or TypeScript configuration file from the project. The usual names are cypress.config.js and cypress.config.ts. Cypress recommends wrapping the object in defineConfig() for editor code completion; it is not required for Cypress to parse the configuration. See the live Cypress configuration reference for supported options and current defaults.
CommonJS JavaScript
const { defineConfig } = require('cypress')
module.exports = defineConfig({
e2e: {
baseUrl: 'http://localhost:8080',
},
})Replace the example URL with the address of the application your tests exercise.
ES modules or TypeScript
import { defineConfig } from 'cypress'
export default defineConfig({
e2e: {
baseUrl: 'http://localhost:8080',
},
})Use the module syntax that fits the project’s Node settings. If a project declares "type": "module" but needs a CommonJS config, use a .cjs file. An ESM config in a CommonJS project can use .mjs or the package’s module type can be set to module.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
#1 Best Overall
Put each setting at the right level
Top-level options apply generally; options nested under a test-type block apply to that runner. A setting such as baseUrl belongs under e2e, while Component Testing configuration belongs under component.
| Configuration scope | Use it for | Examples |
|---|---|---|
| Top level | Options shared across test types, unless a test-type block provides its own value | defaultCommandTimeout |
e2e |
End-to-end browser tests | baseUrl, support file, spec matching |
component |
Component Testing runner setup | devServer, indexHtmlFile |
For example, a shared timeout and E2E base URL can coexist with a separate Component Testing block:
const { defineConfig } = require('cypress')
module.exports = defineConfig({
defaultCommandTimeout: 5000,
e2e: {
baseUrl: 'http://localhost:8080',
setupNodeEvents(on, config) {
// Register Node-side event handlers here.
return config
},
},
component: {
// Put Component Testing options here.
},
})This illustrates the configuration structure; add only options that fit the project. The live configuration reference lists current supported settings and defaults. Defaults are version-sensitive; for example, the reference currently lists baseUrl: null, an E2E specPattern of cypress/e2e/**/*.cy.{js,jsx,ts,tsx}, and testIsolation: true.
Rank #2
- HTML CSS Design and Build Web Sites
- Comes with secure packaging
- It can be a gift option
Set a base URL for E2E tests
Set e2e.baseUrl when tests should visit the same application origin using relative paths. Cypress prefixes both cy.visit() and cy.request() URLs with this value, as described in its E2E testing guide.
e2e: {
baseUrl: 'http://localhost:8080',
}With that setting, a test can use cy.visit('/login') instead of repeating the full origin. Keep the configured origin aligned with the server started for the test run.
Choose an override based on its scope
Keep stable project defaults in the config file. For a temporary run-specific change, select the narrowest override that fits:
Rank #3
| Mechanism | What it changes | Example use |
|---|---|---|
CLI --config |
One or more individual Cypress configuration values for a run | Change viewport dimensions in CI or for a one-off run |
CLI --config-file |
The configuration file Cypress loads | Use a separate config for a specialized test run |
| OS environment variables | Matching configuration values or environment-specific inputs | Set a value differently on a developer machine or CI runner |
| Runtime test overrides | Settings for a test or suite rather than the whole project | Apply a local exception where needed |
Examples of CLI overrides:
cypress run --config viewportWidth=1280,viewportHeight=720
cypress run --config-file tests/cypress.config.jsThe configuration guide also documents OS-variable overrides such as CYPRESS_VIEWPORT_WIDTH and CYPRESS_VIEWPORT_HEIGHT. Check the current configuration documentation for accepted names and precedence details.
Provide environment-specific values and secrets
Cypress supports environment values through the config’s env object, a cypress.env.json file, CYPRESS_* operating-system variables, the CLI --env option, and setupNodeEvents. Which source is appropriate depends on whether a value is safe to commit and whether it varies by environment. Cypress’s environment variables and secrets guide describes these options.
Read a secret from the process environment
const { defineConfig } = require('cypress')
module.exports = defineConfig({
e2e: {
env: {
apiKey: process.env.API_KEY,
},
},
})Set API_KEY in the machine or CI environment that runs Cypress rather than putting the real key in a checked-in config file. Use cypress.env.json only with an appropriate ignore rule if it contains local secrets, and avoid exposing secrets in logs or test output.
Rank #4
- Brand: Wiley
- Set of 2 Volumes
- A handy two-book set that uniquely combines related technologies Highly visual format and accessible language makes these books highly effective learning tools Perfect for beginning web designers and front-end developers
Use setupNodeEvents for Node-side work
setupNodeEvents(on, config) runs in Node. Use it to register Cypress event handlers or to adjust configuration dynamically, then return the config object for Cypress to apply. Node facilities such as filesystem and operating-system access are available there, but browser-side Cypress and cy commands are not. Consult the Configuration API for its current API details.
e2e: {
setupNodeEvents(on, config) {
// Register Node event handlers with on(...).
// Modify config here only when needed.
return config
},
}Keep ordinary test actions in spec files; do not try to call cy.visit() or other browser commands from this Node callback.
Update legacy plugin configuration
In older projects, a cypress/plugins/index.js file may contain Node event setup. The migration guide says Cypress no longer automatically loads that plugins file; move the relevant behavior into setupNodeEvents in the configuration file. For version-specific migration details, use the Cypress migration guide. Component Testing’s devServer belongs in its component configuration, rather than being treated as a legacy plugin setting.
What to expect while editing
Cypress automatically reboots after a configuration-file change and closes open browsers, according to the E2E testing guide. If a runner closes during an edit, allow it to restart and then check that the new configuration loaded.
Troubleshoot common configuration problems
- Cypress does not load the config: Check that the file is in the project and named with the supported extension, and that its module syntax matches the project. If the package uses ESM but the file uses CommonJS, consider
.cjs; for ESM in a CommonJS project, consider.mjsor setting the package type appropriately. - Relative visits resolve incorrectly: Confirm that
baseUrlis nested insidee2e, points to the running app, and uses the expected scheme and port. - A setting has no effect: Check whether it belongs at the shared top level or under the relevant
e2eorcomponentblock. Also check whether a CLI option or environment variable is overriding the file value. - A value is undefined in a test: Confirm that it was supplied through a supported environment-value mechanism and is read from the appropriate config or runtime location. For secrets sourced from
process.env, verify that the variable is present in the process that launched Cypress. - Node event code reports missing Cypress commands:
setupNodeEventsruns in Node, not the browser. Register Node event handlers there; movecycommands into a test. - Legacy plugin code no longer runs: Move its event logic into
setupNodeEventsand follow the migration guide for the project’s Cypress version.
Or skip the browser setup
If the task is to capture a website screenshot rather than configure Cypress for browser testing, ScreenshotNeo provides a website screenshot API and MCP server. Its one-call API example is:
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpSee the ScreenshotNeo documentation for the API details. It accepts cookie and consent banners before capture and removes more than 60 known consent platforms, newsletter popups, and chat widgets; these cleanup steps can each be turned off. Bot checks, blank pages, timeouts, failed loads, and cache hits are not billed, and response headers identify the page verdict and billing status. Its MCP server offers take_screenshot, get_page_info, and capture_pdf for AI agents and MCP clients. The Free plan includes 1,000 screenshots per month with no card; paid plans start at $5 for 3,000 shots.
Sign up for ScreenshotNeo’s free plan: 1,000 screenshots a month, no card required.
Free tools Windows power users keep installed
One-click scans. No signup required.
Frequently Asked Questions
Does Cypress require `defineConfig()`?
No. Cypress recommends it for editor completion, but it is not required to parse the configuration.
Does changing the Cypress config require manually closing the runner?
Cypress reboots after a config-file modification and closes open browsers automatically.
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
