To set up Cypress end-to-end testing, install Cypress as a project development dependency, open its Launchpad, choose E2E Testing, configure the URL of your running app as e2e.baseUrl, then write and run a spec. For CI, start the app and wait until it is ready before running Cypress; starting the server and immediately launching tests can cause intermittent failures.
Install Cypress in your project
Run the install command from your application’s project root. Cypress should be a development dependency because it is used for testing, not as part of the deployed application. Check Cypress’s installation guide for current system requirements, including its supported Node.js and package-manager versions.
| Package manager | Command |
|---|---|
| npm | npm install cypress --save-dev |
| Yarn | yarn add cypress --dev |
| pnpm | pnpm add --save-dev cypress |
| Bun | bun add --dev cypress |
Use the package manager already used by the project, and commit its updated manifest and lockfile. Installing Cypress does not tell it where your application runs; that is configured separately.
Initialize E2E testing with the Launchpad
- From the project root, run
npx cypress open. Use your package manager’s equivalent runner if appropriate. - On first launch, select E2E Testing rather than Component Testing.
- Follow the Launchpad prompts to create the initial Cypress configuration and E2E folder structure, then select an available browser.
The Launchpad creates a starting point; you still need to start the application, set its base URL and add tests for your own user flows. The official open-the-app guide explains the first-launch process.
Start the app and configure its base URL
Run your development server separately from Cypress and note its actual address. For example, if the app is available at http://localhost:8080, set that address as the E2E base URL in cypress.config.js or cypress.config.ts.
const { defineConfig } = require('cypress');
module.exports = defineConfig({
e2e: {
baseUrl: 'http://localhost:8080',
},
});For a TypeScript configuration, use the equivalent typed config shape:
import { defineConfig } from 'cypress';
export default defineConfig({
e2e: {
baseUrl: 'http://localhost:8080',
},
});Replace the example URL with the address and port your server actually uses. With baseUrl set, cy.visit('/') and cy.request('/api/...') resolve against it; without it, use a full URL. See Cypress’s configuration reference for other configuration options.
Do not start a long-running app server from inside a Cypress test. Keep server lifecycle management outside the spec so the app is available before the browser begins navigating.
Windows Errors? Fix Them Before They Spread
Repair common Windows errors and clear accumulated junk for a smoother, more stable PC - no reinstall needed.Free scan · no reinstallOutdated Drivers Are Slowing You Down
One free scan finds every outdated or missing driver and matches the right update for your exact hardware.Free scan · exact hardware matchWrite and run your first E2E spec
Put a spec in the configured E2E directory, typically cypress/e2e. A useful first test visits a real route and checks something a user can see, rather than merely checking that navigation did not throw an error.
describe('home page', () => {
it('shows the main heading', () => {
cy.visit('/');
cy.get('h1').should('be.visible');
});
});Replace the heading selector or assertion with an element and outcome that are meaningful for your application. Prefer stable selectors intended for tests when your project provides them, and assert observable behavior such as a confirmation message after a user action.
- Run
npx cypress opento select a spec and debug interactively. - Run
npx cypress runfor a headless command-line run suitable for automation.
The first E2E test guide covers the test-writing flow.
Choose a browser deliberately
Cypress’s browser support and version-specific notes can change. Its current documentation describes support for the latest three major versions of Chrome, Edge and Firefox, subject to individual notes; WebKit support is experimental. Electron is deprecated as a test browser and is slated for removal, so avoid building a durable workflow around an implicit Electron default. Check the current browser guide before fixing a browser matrix.
Cypress can detect installed browsers, and the CLI accepts --browser, for example npx cypress run --browser chrome when Chrome is installed and detected. For repeatable CI runs, Cypress recommends Chrome for Testing where practical because its version is controlled rather than silently auto-updated. The selected browser must exist in the CI environment or be supplied by a suitable Cypress Docker image.
You do not necessarily need to run every supported browser on every commit. Choose browsers based on the ones your users rely on, then balance coverage against run time and infrastructure cost. A smaller fast check on each change and broader coverage on a scheduled or release run may be a reasonable project-specific approach.
Run Cypress reliably in CI
The basic CI sequence is install dependencies, start the application, wait for it to respond, and then run Cypress in the chosen browser. Cypress documents integrations for GitHub Actions, CircleCI, GitLab, Jenkins, AWS CodeBuild and other providers; the provider changes, but the readiness requirement does not.
- Check out the code and install dependencies from the committed lockfile.
- Start the application server using the project’s normal build or start command.
- Wait for the actual app URL to become available with a readiness tool, or use the CI integration’s documented wait option.
- Run
npx cypress run, specifying a browser if your workflow requires one. - Retain the failure output and any configured run artifacts that your team needs to diagnose failures.
A background server command followed immediately by Cypress creates a race: the test runner may visit the URL before the server has finished starting. A fixed sleep can reduce the chance of that race but does not confirm readiness; use a check that waits for a response from the app instead. Cypress’s CI overview describes server startup and readiness approaches, including the official GitHub Action’s start and wait-on options.
The Tool Desk
Outbyte PC Repair FREERepair Windows errors before they cause bigger problemsFix Now →Outbyte Driver Updater FREEFix the driver behind crashes, sound loss and screen glitchesFind Drivers →Resources and dependencies
Cypress’s install documentation gives a CI baseline recommendation of at least 2 CPUs and 4 GB RAM, with 8 GB or more recommended for longer runs or video recording. Actual needs depend on the application, browser and server. Linux runners may need additional system dependencies; Cypress Docker images can package browser and system prerequisites. Check the current install and CI documentation for requirements applicable to your Cypress version and runner.
Parallelization and browser coverage
Parallel execution can reduce wall-clock time, but requires more CI capacity and can increase infrastructure expense. Consider test duration, the value of faster feedback, and whether the chosen browser set represents your users. Parallelism is a trade-off, not a prerequisite for a working Cypress setup.
Optional: record runs with Cypress Cloud
Cypress App is the local testing application; Cypress Cloud is an optional hosted service for recording CI runs and related collaboration, debugging, analytics and orchestration features. To connect a project, associate its project ID with the configuration and provide a record key to the run, commonly through a protected environment variable. Do not commit the key to source control or expose it in logs.
Cloud plans, prices and allowances can change. Consult the official Cypress Cloud pricing page and Cloud setup guide for current terms before choosing a plan.
Troubleshoot common setup failures
| Symptom | Likely cause | What to check |
|---|---|---|
cy.visit('/') cannot reach the application |
The server is stopped, the configured address or port is wrong, or CI started Cypress before the app was ready. | Open the exact baseUrl in a browser; verify the server port and use a readiness check before the test command. |
| The browser does not appear in Cypress | The browser is not installed, is outside the documented supported versions, or is not available to the runner. | Check installed browsers, Cypress’s current compatibility notes and the CI image; explicitly select an installed browser with --browser. |
| Tests pass locally but fail in CI at startup | The CI workflow has a server readiness race, a different URL/configuration, or missing browser/system dependencies. | Wait on the app URL, compare the CI base URL and environment to local settings, and verify the runner has the required browser and OS dependencies. |
| The run fails after a Cypress or browser update | Browser support and requirements are version-sensitive, and an automatically updated browser can change behavior. | Review the current Cypress browser guidance and pin or otherwise control the CI browser version where practical. |
| Cloud recording fails or a secret is rejected | The project ID or record key is missing or mismatched, or the key is not being passed to the CI run as expected. | Follow the Cloud setup instructions and configure the record key as a protected CI secret rather than hard-coding it. |
Or skip the browser setup
If the job is to capture a page screenshot rather than verify an interactive application flow, ScreenshotNeo provides a screenshot API and MCP server; it is not a replacement for Cypress E2E assertions. One GET request returns a PNG, JPEG, WebP or PDF. Example cURL request (see the ScreenshotNeo API docs):
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpScreenshotNeo accepts cookie or consent banners and removes more than 60 known consent platforms, newsletter popups and chat widgets before capture; those steps can be turned off. Bot checks or CAPTCHAs, blank pages, timeouts, failed loads and cache hits cost nothing, and each response identifies the page verdict and billing status with X-Page-Verdict and X-Billed headers. Its MCP server exposes take_screenshot, get_page_info and capture_pdf to 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. Sign up for ScreenshotNeo’s free plan.
Frequently Asked Questions
Can I use Cypress without Cypress Cloud?
Yes. Cypress App runs local tests, and Cloud is an optional hosted service for recording CI runs and related features.
Should I use Electron for new Cypress tests?
Avoid relying on it for a durable setup: Cypress documents Electron as deprecated and slated for removal.
Recommended Free Tools
Does installing Cypress configure my app URL automatically?
No. Set the E2E baseUrl to the address of the running application.
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.
