Cypress lets you write browser tests that exercise an application through a real browser. For a first test, install Cypress in your project, open its app, choose end-to-end (E2E) testing, and create a spec that visits a page, interacts with it, and checks the result. Use E2E tests for important flows across your app; use component tests when you want to examine one component in isolation.
What Cypress tests—and which kind should you start with?
Cypress provides browser-based tools for testing web applications. Its local App is free and open source. Cypress Cloud is a separate paid service for recording test runs and viewing results and analytics; you do not need Cloud to write or run a local test. Cypress’s overview explains the product and test types.
| Test type | Scope and setup | Best question to answer | Typical failures it can reveal |
|---|---|---|---|
| E2E | Visits the application and performs UI actions along a user-facing flow. | Can a user complete this important task through the app? | Broken navigation, form submission, or integration between pages and application behavior. |
| Component | Mounts an individual component in a real browser. | Does this component behave and render as expected in isolation? | Component behavior, styling, or appearance problems. |
These test types complement rather than replace one another. An E2E test covers a broader path through the application; a component test focuses on a smaller unit in its browser context. Cypress lists official component mounting libraries for React, Angular, Vue, and Svelte, but supported framework, version, and bundler combinations change. Check the current component-testing setup guide before choosing a configuration.
Install Cypress in your project
You need Node.js and a supported package manager. Cypress recommends checking its live installation and system requirements first because operating-system, browser, and other support details can change.
The Tool Desk
Outbyte Driver Updater FREEFix the driver behind crashes, sound loss and screen glitchesFind Drivers →Outbyte PC Repair FREERepair Windows errors before they cause bigger problemsFix Now →- Open your project directory in a terminal. Cypress is installed locally as a development dependency, rather than as a global command.
- Install it with your package manager. For npm, run
npm install cypress --save-dev. The official installation guide also shows alternatives for Yarn, pnpm, and Bun. - Launch the Cypress App. Run
npx cypress open. The interactive app guides you through setting up testing and choosing E2E or component testing. - Choose E2E testing for the example below. Follow the app’s prompts to select a browser and create the initial configuration and spec files.
The App’s setup flow is often the simplest way to generate the project’s initial files. If you need to adjust configuration later, use the current documentation rather than assuming that file names or defaults cannot change.
Write a first E2E test
Here is a small test for a fictional search page. Replace the example URL, input selector, button selector, and expected heading with elements and content from your own application. Save the spec in the default E2E spec directory, cypress/e2e.
describe('Search', () => {
it('shows results for a query', () => {
cy.visit('http://localhost:3000/search')
cy.get('input[name="q"]').type('Cypress')
cy.get('button[type="submit"]').click()
cy.get('h1').should('contain', 'Search results for Cypress')
})
})Start your application locally before running this example, and make sure the URL matches where it is running. In the Cypress App, select the spec to run it. The test performs the same broad sequence a person would: open the page, enter a query, submit it, and verify visible application state.
What each command does
describe()names and groups related tests. Cypress uses a Mocha-style interface;context()is another grouping option.it()defines one test.specify()is an alternative.cy.visit()opens the application URL in the test browser.cy.get()finds an element using a CSS selector..type()enters text into the selected input, and.click()activates the selected button..should('contain', ...)asserts that the selected heading contains the expected text. The assertion checks the result, not just whether the commands ran.
Cypress’s introduction walks through a similar visit, interaction, and assertion pattern, including a todo example.
Where tests and shared setup go
By default, E2E specs live in cypress/e2e. Component specs can live beside the components they test. A support file runs before each spec and is a natural place for shared setup and custom commands. These locations and other defaults can be configured; see Cypress’s guide to writing and organizing tests for the current conventions.
Keep a test focused on a behavior a reader or user could recognize, such as submitting a form or completing a checkout step. Use selectors that identify the intended element, and assert something meaningful about the resulting interface. For a form journey, the pattern is to visit the page, enter valid or deliberately invalid values, submit, and assert the success or validation state that the application should show.
Choose a browser and run mode
Cypress documentation lists Chrome-family browsers and Firefox, describes WebKit as experimental, and marks Electron as deprecated as a test browser. These options do not all have the same stability status. Consult the live browser launch reference before relying on a particular browser or version. Cypress can run headed, with a visible browser window, or headless, without one; its CLI also supports selecting a browser.
For local work, a modern development machine is generally suitable. Cypress’s requirements page recommends at least 2 CPUs and 4 GB of RAM for CI, and 8 GB or more for long runs or video recording. These are vendor recommendations, not guarantees of a particular runtime, and the requirements may change.
Troubleshoot common first-run problems
- The command cannot find Cypress: confirm you are in the project directory and that the installation completed. With the documented npm setup, launch it using
npx cypress open. - The browser opens, but the page does not: start your local application and check that the URL in
cy.visit()matches its actual address and route. - An element is not found: inspect the page and verify the selector matches a real element on that route. Check whether the page has finished rendering or whether navigation changed the visible page.
- The test runs but the assertion fails: compare the expected text with the application’s actual result. Confirm the interaction succeeded and that the test is checking the relevant heading or status message.
- A browser option behaves unexpectedly: check its current status and launch instructions in Cypress’s browser reference; experimental and deprecated choices should not be treated as equivalent to supported stable options.
- CI runs fail under load: compare the runner’s resources with Cypress’s published recommendations, particularly for long tests or video recording, and consult the current requirements page.
Keep learning with official resources
Cypress’s Real World Testing learning site offers free courses and practical material on installation, first tests, test types, user journeys, debugging, and application examples. It is a useful next step after the first spec; match any framework-specific guidance to the versions your project actually uses.
Or skip the browser setup
If the job is to capture a page rather than test application behavior, ScreenshotNeo is a website screenshot API and MCP server for developers. One GET request can return a PNG, JPEG, WebP, or PDF; its cleanup steps can accept cookie or consent banners and remove more than 60 known consent platforms, newsletter popups, and chat widgets before capture. These steps can each be turned off. Bot checks and CAPTCHAs, blank pages, timeouts, failed loads, and cache hits cost nothing, and responses identify the page verdict and billing status in headers.
For a one-call WebP capture, first get an API key, then run this cURL command. 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.webpScreenshotNeo also offers an MCP server with take_screenshot, get_page_info, and capture_pdf tools for Claude, Cursor, and other MCP clients. The Free plan includes 1,000 screenshots per month without a card; paid plans start at $5 for 3,000 screenshots. Learn more at ScreenshotNeo, or sign up free for 1,000 screenshots a month with no card.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
Frequently Asked Questions
Do I need Cypress Cloud to run my first test?
No. You can write and run tests with the local Cypress App; Cloud is a separate service for recording and analyzing runs.
Can Cypress component tests replace E2E tests?
No. Component tests focus on one mounted component, while E2E tests exercise user-facing flows through the 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.
