Installing Cypress
Cypress is installed as a development dependency through npm or yarn, just like any other JavaScript tooling package. Running npm install cypress --save-dev downloads both the Cypress npm module, which exposes the cypress CLI, and a separate binary that contains the actual Electron-based Test Runner application; the binary is cached globally so repeated installs across projects on the same machine are fast. Once installed, npx cypress open launches the interactive Test Runner for the first time, which triggers a setup wizard that scaffolds configuration and example files into your project.
Cricket analogy: Installing Cypress via npm is like a franchise signing a player through the IPL auction system: one clear registration process that then equips the whole squad with a ready-to-use resource.
The Scaffolded Folder Structure
The first time you open Cypress, it creates a cypress/ directory containing e2e/ for end-to-end spec files, fixtures/ for static JSON test data, support/ for reusable commands and global configuration like commands.js and e2e.js, and downloads/ for files your tests download during a run. It also creates a cypress.config.js (or .ts) file at the project root, where you configure the baseUrl, viewport size, timeouts, and register plugins or event listeners through the setupNodeEvents function. Keeping this structure consistent across projects makes it easy for any developer to find specs, shared commands, and mock data without hunting through custom folder layouts.
Cricket analogy: The scaffolded folders are like a cricket academy's standard layout: nets for practice (e2e specs), a video analysis room (fixtures of past deliveries), and a fitness wing (support commands) that every player finds in the same place at every venue.
// cypress.config.js
const { defineConfig } = require('cypress');
module.exports = defineConfig({
e2e: {
baseUrl: 'http://localhost:3000',
viewportWidth: 1280,
viewportHeight: 800,
defaultCommandTimeout: 6000,
setupNodeEvents(on, config) {
// register event listeners and plugins here
on('task', {
log(message) {
console.log(message);
return null;
},
});
return config;
},
},
});Setting a baseUrl in cypress.config.js means you can write cy.visit('/login') instead of the full URL in every spec, and Cypress will also wait for your dev server to be reachable before running tests, which reduces flaky startup failures in CI.
Configuring Environment Variables and CI Setup
Cypress supports environment-specific configuration through a cypress.env.json file, the env key in cypress.config.js, or CYPRESS_ prefixed OS environment variables, all of which are merged into Cypress.env() at runtime; this is how teams inject API keys, feature flags, or environment-specific base URLs without committing secrets to source control. For continuous integration, Cypress ships a headless CLI mode invoked with npx cypress run, which requires no display server and produces JSON, JUnit, or video artifacts that CI systems like GitHub Actions or CircleCI can archive; teams commonly install the official cypress-io/github-action to handle caching the binary between CI runs automatically.
Cricket analogy: Environment variables in Cypress are like a team's confidential team-sheet passed only to selectors before a match, kept out of the public scorecard (source control) but available when needed on matchday.
Never commit cypress.env.json or hardcode secrets directly into cypress.config.js if the repository is public or shared broadly. Use CI-provided secret stores (like GitHub Actions secrets) to inject CYPRESS_ prefixed environment variables at runtime instead.
- Cypress installs as an npm dev dependency and also downloads a separate cached Electron-based binary.
- npx cypress open launches the interactive Test Runner and scaffolds the cypress/ folder structure on first run.
- The scaffolded structure includes e2e/, fixtures/, support/, and downloads/ directories plus a cypress.config.js file.
- baseUrl in the config lets specs use relative paths with cy.visit() and improves CI startup reliability.
- Environment-specific values are supplied via cypress.env.json, the config's env key, or CYPRESS_ prefixed OS variables.
- npx cypress run provides a headless CLI mode suited for CI pipelines, producing videos and JUnit/JSON reports.
- Secrets should never be committed to source control; use CI secret stores to inject them at runtime.
Practice what you learned
1. How is Cypress typically added to a JavaScript project?
2. What does npx cypress open do the first time it's run in a new project?
3. What is the purpose of setting baseUrl in cypress.config.js?
4. How should secrets like API keys be provided to Cypress in CI?
5. Which command runs Cypress in headless mode suitable for CI pipelines?
Was this page helpful?
You May Also Like
What Is Cypress?
An introduction to Cypress, the JavaScript end-to-end testing framework that runs inside the browser alongside your application code.
The Cypress Test Runner
A tour of the interactive Cypress Test Runner: the command log, DOM snapshots, selector playground, and debugging tools that make writing tests fast.
Your First Cypress Test
Write, run, and understand a complete Cypress spec file from scratch, covering describe/it blocks, commands, and assertions.