Cypress Testing: A Beginner’s Guide

Cypress lets you write browser tests that exercise an application in a real browser. Use an end-to-end (E2E) test to check a user-facing flow across your app; use a component test to mount one UI component and check its behavior or appearance in isolation. To start, install Cypress as a project development dependency, open the Cypress App, choose a test type, and write a test that visits a page, interacts with it, and asserts the visible result.

1. Choose the test that matches the question

Question	Test type	What it exercises	Useful for finding
Can a user complete an important journey through the app?	E2E	The application in its normal browser context, including navigation and connected UI behavior.	Broken routes, forms, integration points, and regressions that interrupt a user flow.
Does this component behave and render correctly on its own?	Component	A mounted component in a real browser.	Component interaction, styling, and rendering problems.

These test types answer different questions. An E2E test follows an application flow; a component test focuses on an individual component. A project can use both. Cypress’s local App is free and open source. Cypress Cloud is a separate paid service for recording runs and surfacing results and analytics; it is not required to write or run a first local test. Cypress overview.

2. Install Cypress and open the app

Use a Node.js project with a supported package manager. Cypress recommends checking its live system requirements before installing because supported operating systems, browsers, and other requirements can change.

# npm
npm install cypress --save-dev
npx cypress open

Equivalent package-manager commands include:

# Yarn
yarn add cypress --dev
yarn cypress open

# pnpm
pnpm add cypress --save-dev
pnpm cypress open

# Bun
bun add cypress --dev
bunx cypress open

In the Cypress App, choose E2E Testing or Component Testing. The app guides you through creating the initial configuration and example files. For a first test, choose E2E and launch one of the browsers offered by your installation. The current installation and requirements guide has the latest prerequisites and package-manager instructions.

3. Write a first E2E test

Start your application using its normal development command in a separate terminal. The example below assumes the app is available at http://localhost:3000 and has a search input, a button named “Search,” and a results heading. Replace those selectors and expected text with elements from your own app.

describe('search', () => {
  it('shows results for a query', () => {
    cy.visit('http://localhost:3000')
    cy.get('[data-cy=search-input]').type('Cypress')
    cy.contains('button', 'Search').click()
    cy.get('h1').should('contain', 'Results for Cypress')
  })
})

Save the spec in cypress/e2e/search.cy.js (or another supported spec extension configured for your project). Select it in the Cypress App to run it. The example follows a user-like sequence:

1. describe() groups related tests. Cypress uses a Mocha-style interface; context() is another grouping name.
2. it() defines one test. specify() is an alternative name.
3. cy.visit() opens the app URL in the controlled browser.
4. cy.get() finds an element matching a selector. A data-cy attribute is a useful stable selector that is separate from styling classes.
5. .type() enters text, and .click() activates the matching button.
6. .should() checks the resulting page state. Cypress retries queries and assertions while the page updates, up to the configured timeout.

A test should assert an outcome a user can observe, not merely that a command ran. For a form, that might be a confirmation message, an error shown for invalid input, or a changed destination URL.

4. Find specs and shared setup

By default, Cypress puts E2E specs in cypress/e2e. Component specs can live beside the components they exercise. A support file runs before each spec and is a natural place for shared setup and custom commands. These are defaults, and the Cypress configuration can change them. See Writing and organizing tests for the current configuration details.

my-app/
  cypress.config.js
  cypress/
    e2e/
      search.cy.js
    support/
      e2e.js
  src/
    components/
      SearchForm.jsx
      SearchForm.cy.jsx

Keep test setup easy to understand. Put behavior used by many specs in support code or a custom command, but leave the important steps visible in the test so a failure is straightforward to diagnose.

5. Make tests useful and stable

Prefer selectors that describe test intent

CSS classes often change during redesigns. Where possible, add purpose-built attributes such as data-cy="search-input" and query them directly. Use accessible labels or visible text when the test should also verify how a user finds the control.

Wait for a condition instead of guessing a delay

Assertions on the expected UI state let Cypress retry while the app responds. Avoid fixed sleeps such as cy.wait(2000) as a general synchronization strategy: the right delay varies across machines and runs. For network-dependent behavior, wait for a meaningful request or visible result, and configure the test around the app’s actual behavior.

Keep each test focused

Test one outcome at a time and make its setup predictable. A long scenario with many unrelated assertions can obscure the cause of failure. Use E2E tests for a small number of important application journeys and component tests for focused UI behavior.

6. Run tests from the command line

Opening the app is useful while authoring and debugging. For automated runs, use the Cypress CLI:

# Run E2E specs headlessly
npx cypress run

# Run with an explicitly selected browser
npx cypress run --browser chrome

# Open the interactive app
npx cypress open

Available browser names and stability differ by current Cypress version and environment. Cypress documents Chrome-family browsers and Firefox, describes WebKit as experimental, and marks Electron as deprecated as a test browser in its current browser reference. Check the live browser launching documentation before choosing a browser for local or CI runs. Cypress supports headed and headless runs; use the mode that fits the debugging or automation task.

7. Add component testing when it fits

Component Testing mounts the actual component in a real browser, rather than relying on a simulated DOM. It helps answer questions about a component’s behavior, style, and appearance without driving the entire app. Cypress documents mounting libraries for React, Angular, Vue, and Svelte. Framework versions and bundler combinations change, so verify the current component testing setup guide before configuring a specific stack.

A component test needs a mount setup appropriate to the chosen framework, then can interact with the rendered component much like an E2E test interacts with a page. Keep the boundary clear: test an isolated control or component here; test its integration into a full journey with E2E.

8. Browser, CI, and resource considerations

For local development, Cypress says a modern development machine is suitable. Its current CI guidance recommends at least 2 CPUs and 4 GB RAM, with 8 GB or more recommended for long runs or video recording. These are vendor recommendations and may change; check the live requirements page when sizing CI workers.

• Run locally in the browser configuration developers use to catch relevant behavior early.
• In CI, choose the browser and headed or headless mode deliberately, and keep the Cypress version consistent with the project lockfile.
• Long runs, parallel jobs, and video recording consume additional resources. Measure your own workflow before increasing worker count.
• Use Cypress Cloud only if its recording and analytics capabilities fit the team’s needs; local Cypress runs do not require Cloud.

9. Troubleshooting common problems

Symptom	Likely cause	Fix
cypress command not found	Cypress is not installed in this project or the package manager command was run from the wrong directory.	Run the install command in the project root, then use npx cypress open or the matching package-manager command.
The app cannot be reached at the URL	The development server is stopped, uses a different port, or the test URL is wrong.	Start the app separately, confirm its local URL in a browser, and update cy.visit().
Element not found or timed out	The selector does not match, the element is not rendered yet, or the test assumes the wrong page state.	Inspect the page in the Cypress runner, verify the selector and app state, and assert a condition that reflects when the element should appear.
Test is flaky around loading	A fixed wait or timing assumption does not match the actual response time.	Wait on a relevant request or assert the final visible state instead of relying on an arbitrary sleep.
Browser fails to launch	The selected browser is missing, unsupported in the environment, or changed behavior across Cypress versions.	Check the installed browser, use a browser currently supported by Cypress, and consult the live browser launch reference.
Component setup fails	The framework, version, or bundler setup does not match the current Cypress component testing integration.	Compare the project configuration with the current Cypress component testing compatibility and setup documentation.
CI run is slow or runs out of memory	Worker resources are insufficient for the suite, browser, parallel work, or recording configuration.	Review CI resource allocation against Cypress’s current guidance; reduce unnecessary recording or parallel load and split an overly broad suite.

10. Or skip the browser setup

If your goal is to capture a page for a visual check, a baseline, or documentation, you can request a screenshot directly from ScreenshotNeo, a website screenshot API and MCP server from Yorker Media. This is separate from Cypress: it captures a page image or PDF, while Cypress runs browser tests that interact with and assert on your application. See the ScreenshotNeo API documentation.

curl -G "https://api.screenshotneo.com/v1/shot" \
  -d access_key=YOUR_API_KEY \
  --data-urlencode url=https://stripe.com \
  -o shot.webp

import requests

r = requests.get(
    "https://api.screenshotneo.com/v1/shot",
    params={"access_key": "YOUR_API_KEY", "url": "https://stripe.com"},
    timeout=90,
)
open("shot.webp", "wb").write(r.content)

const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://stripe.com' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);
if (!res.ok) throw new Error(`Screenshot request failed: ${res.status}`);
await Bun.write('shot.webp', res);

The Node.js snippet uses Bun’s file writer for saving the response. In Node.js, save the response body with the filesystem API:

import { writeFile } from 'node:fs/promises';

const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://stripe.com' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);
if (!res.ok) throw new Error(`Screenshot request failed: ${res.status}`);
await writeFile('shot.webp', Buffer.from(await res.arrayBuffer()));

ScreenshotNeo removes cookie banners, popups, and chat widgets before the shot. Bot checks, blank pages, and failed loads are never billed. Its MCP server lets AI agents take screenshots. The free plan includes 1,000 screenshots a month with no card; paid plans start at $5 for 3,000. Sign up for 1,000 free screenshots a month, no card required.

11. Keep learning

Start with the official Cypress introduction and its free Real World Testing courses, which cover installation, first tests, test types, user journeys, debugging, and application examples. Use the official docs as the source of truth for changing browser support and framework setup. If considering Cypress Cloud, check the current pricing page; pricing and plan details can change.

FAQ

Do I need Cypress Cloud to run tests?

No. The local Cypress App can be used to write and run tests. Cloud is an optional paid service for recording and analyzing runs.

Should a beginner start with E2E or component testing?

Start with the question you need answered. Choose E2E for a user journey through the app, and component testing for an isolated component’s behavior or rendering.

Can Cypress capture a screenshot without running a test?

Cypress can capture screenshots as part of browser testing workflows. For a direct screenshot or PDF request without setting up a test, ScreenshotNeo provides a screenshot API; see its documentation.

Where should I check current browser support?

Use Cypress’s live browser reference, since supported and experimental options can change.