To get started with Cypress test automation, install Cypress as a development dependency, open its guided setup, choose end-to-end or component testing, and write tests at the narrowest layer that answers your question. Use end-to-end tests for critical journeys across your application, component tests for focused UI behavior, and API tests for backend behavior. Passing one layer does not prove the whole product works.
Choose the right Cypress testing layer
Cypress documents end-to-end, component, API, and accessibility testing. They cover different scopes rather than competing to be the one test type for every question. A balanced suite uses each where it gives useful feedback.
| Test type | Scope and useful cases | What a pass does not establish |
|---|---|---|
| End-to-end (E2E) | Exercises user-like workflows in a real browser. Use it for high-value journeys such as authentication, purchasing, persisted state across screens, and pre-deployment smoke checks. | It requires more setup and infrastructure than focused tests, and a passing journey does not prove every possible state or path works. |
| Component | Mounts a component in isolation. Useful for UI states, forms, date pickers, and design-system components. | It does not establish that all application layers work together. |
| API | Checks backend CRUD behavior, permissions and error responses, state setup, and response contracts without rendering the interface. | It does not verify that the interface renders or behaves correctly. |
| Accessibility | Adds checks such as labels, alt text, contrast, keyboard navigation, and focus behavior to an existing testing layer. | It is an additional layer, not a replacement for functional component, API, or E2E coverage. |
For background on the distinctions, see Cypress’s testing types guide.
Install Cypress and start a project
Use the package manager the project already uses. Cypress’s documented npm setup is:
npm install cypress --save-devThen open Cypress to start its guided configuration:
npx cypress openChoose E2E or component testing in the app. For component testing, the setup detects the UI framework and bundler and scaffolds development-server configuration. The Cypress installation guide covers the guided setup and package-manager alternatives.
Configure E2E visits
Run the application locally during development and set baseUrl in the Cypress configuration. This lets cy.visit('/') resolve to the app under test rather than requiring a full address in every test. For example, merge a setting like this into the configuration file the guided setup created:
import { defineConfig } from 'cypress'
export default defineConfig({
e2e: {
baseUrl: 'http://localhost:3000',
},
})Replace the port with the one your development server actually uses; retain any other configuration already in the file. Cypress describes local development-server testing as the ordinary development workflow in its best practices and effective E2E testing guides.
The Tool Desk
Outbyte PC Repair FREEClear out junk files and repair common Windows errorsFree Scan →Outbyte Driver Updater FREEScan for outdated or missing drivers - takes under a minuteDriver Scan →Put specs where Cypress can find them
The default E2E spec pattern is cypress/e2e/**/*.cy.{js,jsx,ts,tsx}. Component specs can live beside their components. If a spec does not appear in the Cypress app, check the configured specPattern and the file’s name and location. See Writing and Organizing Tests.
Write independent tests
A test should be runnable by itself, not depend on a test that happened to run earlier. E2E test isolation is on by default: Cypress cleans browser state between tests. Set up the state each test needs deliberately, and avoid using shared browser state as an implicit handoff.
describe('sign-in page', () => {
it('shows a validation message for empty credentials', () => {
cy.visit('/login')
cy.get('button[type="submit"]').click()
cy.contains('Email is required').should('be.visible')
})
})This small example assumes the application has a /login route and displays that message. Replace the selectors and expected text with stable elements from your app. Assertions should test observable behavior, not implementation details that change whenever the UI is refactored.
Run Cypress in continuous integration
CI needs the same basic sequence as local E2E testing: install dependencies, start the application, wait until it responds, and run Cypress. Starting the app and immediately invoking Cypress can race with server startup; a fixed sleep can also be too short or unnecessarily long.
Recommended Free Tools
- Install dependencies using the repository’s lockfile and package manager.
- Start the application using the project’s normal build or start command.
- Wait for the application to become ready using the CI environment’s readiness mechanism.
- Run the E2E suite with
npx cypress run.
The documented minimal command pair is installation followed by npx cypress run; adapt the install command to the repository. Follow the Cypress CI overview for the CI workflow you use. Keep recording credentials out of source: provide a Cypress record key through a shell or CI environment variable, or the inline CLI key. It is not read from cypress.env.json or the Cypress configuration env block.
Diagnose flakiness before adding retries
Failures can come from application behavior, timing, server readiness, test data, or network dependencies. First make the environment predictable and tests independent; then adjust timeouts or retries only when the cause warrants it.
Retries reveal intermittency; they do not repair it
Cypress retries default to zero and can be configured separately for run and open modes. For example, Cypress documents two retries in run mode and zero in open mode. A retry that passes after an initial failure is evidence of an intermittent problem to investigate, not proof that the test is reliable. Consult Test Retries for configuration.
Common failures and practical fixes
- The app is unavailable when tests start: make CI wait for a successful readiness check before running Cypress; do not assume a background start command has finished.
- A test passes only after another test: remove hidden state dependencies and give each test its own setup. E2E isolation is enabled by default.
- A spec is missing from the Cypress app: verify its directory, filename, and configured
specPattern. - A failure disappears on retry: investigate timing, state, environment, and network dependencies instead of treating retry success as a fix.
- A recorded run cannot authenticate: provide the record key via the CI or shell environment or the supported inline CLI key, not the config
envblock orcypress.env.json.
Capture a reproducible page screenshot
Cypress validates application behavior in tests; a page screenshot can separately document the rendered state for review or debugging. One option is to use ScreenshotNeo, a website screenshot API and MCP server. This is a separate capture workflow, not a replacement for Cypress assertions.
Or skip the browser setup
Make a single GET request with the target URL and your API key. This cURL example saves the response as a WebP image; see the ScreenshotNeo API documentation for request options.
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpCookie and consent banners are accepted like a visitor and removed along with supported newsletter popups and chat widgets before capture; each of those steps can be turned off. Bot checks or CAPTCHAs, blank pages, timeouts, failed loads, and cache hits are not billed, and responses identify the page verdict and billing status in headers. Its MCP server provides take_screenshot, get_page_info, and capture_pdf tools for AI agents and MCP clients. The free plan includes 1,000 screenshots a month with no card; paid plans start at $5 for 3,000 shots.
Sign up for 1,000 free screenshots a month, with no card required.
Frequently Asked Questions
Can Cypress test an API without opening a browser?
Yes. Cypress documents API testing for backend behavior and response contracts; it answers a different question from whether the UI renders correctly.
Do Cypress retries make a flaky test reliable?
No. A retry can expose intermittency, but the underlying timing, state, environment, or dependency issue still needs diagnosis.
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.
