Writing Your First Cypress Test: Step-by-Step Guide for Beginners

Asfa AkbarLast Updated on November 5, 2026

12-13 Min Read TimeAdd as preferred on Google

Key Takeaways

New Cypress projects should start on Node.js 24 or 26, because Node.js 22 support ends on 30 April 2027.

• Cypress 16 dropped Node.js 20 and 25, so older setup tutorials can fail on the first command.
• Node.js 22 reaches end of support on 30 April 2027, while Node.js 24 runs until 30 April 2028 and Node.js 26 until 30 April 2029.
• Run npx cypress verify after installing to confirm the binary works.
• The template spec contains no assertion. A real test acts on the page, then checks the result, for example with .should('have.value', ...).
• Use cypress open to build tests and cypress run for full suites.
• Electron has been deprecated since Cypress 16.0.0. Name a browser such as Chrome in every run with --browser chrome.

Write one spec for a real flow in your own app and run it with npx cypress run --browser chrome.

The Cypress automation tool dropped support for Node.js 20 in version 16.0.0, released on 1 September 2026. Setup tutorials written before that date can fail on the first command.

This guide takes a manual tester or junior JavaScript developer from an empty folder to a passing test that checks a real value. It starts with the requirements as of November 2026, including the Node.js change that arrives in April 2027. Then it covers installing and verifying Cypress, writing a spec with assertions, choosing between cypress open and cypress run, and reading the folders Cypress creates. QA leads can use the same steps to judge the effort of a first setup.

What is the Cypress automation tool?

Cypress is a JavaScript test tool for anything that runs in a web browser. It runs tests inside the browser and does not use Selenium or WebDriver. The Cypress documentation (Why Cypress, 2026) describes the Cypress App as a free, open-source app you install locally to write and run tests.

Cypress is used for end-to-end (E2E) tests, which check a whole user flow from the user's point of view, such as filling in a form and seeing the result. It also offers component testing, which mounts a single UI component in a real browser. This guide covers E2E only.

Cypress features a beginner uses on day one

Four features change how a first Cypress test is written and debugged:

• Time travel snapshots record each step, and hovering over a command in the Command Log shows the page at that moment.
• Automatic waiting means Cypress waits for commands and assertions before moving on, so tests rarely need manual waits.
• Cypress takes a screenshot automatically when a test fails during cypress run. It does not do this during cypress open, and video recording is off by default.
• The same specs run in several browsers, locally or in a pipeline.

Cypress requirements as of November 2026

Cypress 16 needs Node.js 22, 24 or 26 or later, a recent package manager, and a 64-bit operating system from the supported list. The latest release on the npm registry is Cypress 16.2.1, published on 28 October 2026. Check each requirement below before installing.

Cypress Node.js requirements

The Cypress documentation (Install Cypress, 2026) lists Node.js 22.x, 24.x and 26.x or later. Cypress 16.0.0 removed Node.js 20 and Node.js 25.

Supported package managers are npm 10.1.0 or later, Yarn Classic 1.22.22 or later, Yarn Berry 4.x, pnpm 8.x and Bun 1.2.22 or later. This guide uses npm.

To check your versions, open a terminal and run:

• node -v to print the Node.js version
• npm -v to print the npm version

If node -v prints a version below 22, or 25, install Node.js 24 or 26 first. On Linux, avoid the Snap package of Node.js. Cypress warns that it can cause permission errors for non-root users.

What changes for Cypress in 2027

Plan for one date. The Node.js Release Working Group schedule ends support for Node.js 22 on 30 April 2027, while Node.js 24 runs until 30 April 2028 and Node.js 26, which became LTS on 28 October 2026, runs until 30 April 2029. Our view is that a new project starting in late 2026 or 2027 should use Node.js 24 or 26. Node.js 22 still works today, but a team that picks it now will have to upgrade within months.

Supported operating systems for Cypress 16

Cypress runs on current 64-bit versions of Windows, macOS and the main Linux distributions:

• Windows 10 and 11 (x64), and Windows Server 2019, 2022 and 2025 (x64). Windows 11 25H2 on arm64 is in preview, running under x64 emulation.
• macOS 13.5 or later on Intel or Apple Silicon.
• Linux on x64 or arm64, with Ubuntu 22.04 or later (24.04 or later on arm64), Debian 12 or later (13 or later on arm64) or Fedora 43 or later.

Cypress supported browsers

Cypress supports Chrome for Testing, Chrome, Chromium, Edge, Firefox and Electron, plus experimental WebKit. Several of these come with their beta, dev or nightly channels:

• Chrome, Chrome Beta and Chrome Canary
• Edge, Edge Beta, Edge Canary and Edge Dev
• Firefox, Firefox Developer Edition and Firefox Nightly
• Chrome for Testing and Chromium
• Electron, deprecated since Cypress 16.0.0 and due for removal in a future major version
• WebKit, which is experimental and opt-in

The Electron change matters for any test suite set up today. A run that relies on Electron will break once it is removed. Name a browser such as Chrome in every run from the start. Brave is not on the official list.

How to install Cypress and set up a project

Installing Cypress means creating a project with a package.json file, installing Cypress as a dev dependency, verifying it, then opening it and picking E2E testing. The screenshots below come from an earlier Cypress release, so some labels may look slightly different in Cypress 16.

Create the project folder and package.json

1. Create a folder on your Desktop or in Documents, for example CypressProject.

2. Open Visual Studio Code and open the folder.

3. Open the Terminal menu and select New Terminal.

4. Run npm init -y.

The npm init command normally asks a series of questions before writing package.json. The -y flag accepts the defaults and writes the file straight away.

Install and verify Cypress

1. Run npm install cypress --save-dev. This installs the release tagged latest on npm (16.2.1 as of 3 November 2026) and records Cypress as a dev dependency in package.json.

2. Run npx cypress -v to print the installed Cypress version.

3. Run npx cypress verify. It confirms that the Cypress binary is installed correctly and can run on your machine.

If the install stops with an engine or version error, check node -v again. Cypress 16 declares Node.js 22, 24 or 26 and later as its supported engines.

Open Cypress and choose E2E testing

Run npx cypress open. A window titled "Welcome to Cypress" appears, which means the app started correctly. It offers two testing types, E2E Testing and Component Testing.

1. Select E2E Testing.

2. Cypress lists the configuration files it adds to the project. Select Continue.

3. On the browser page, choose Chrome and select the button to start E2E testing in Chrome.

Create and run your first spec

A spec is a JavaScript or TypeScript file that holds your tests. Chrome opens on the Specs page, where you can create a new spec or scaffold example specs.

1. Select Create New Spec.

2. Give the spec a name ending in .cy.js and select Create Spec.

Cypress saves the file in cypress/e2e. Expand both folders in VS Code to see it.

The template has three parts. describe('template spec', ...) groups related tests into a suite, it('passes', ...) defines one test case, and cy.visit('https://example.cypress.io') tells the browser to open that URL. Click the spec in the list to run it, and the Test Runner marks the test green.

New specs can also be created in VS Code. Add a file such as test1.cy.js inside cypress/e2e, and it appears in the Specs list automatically.

How to write your first Cypress test with real assertions

A green template spec proves almost nothing. It contains no assertion, so it passes whenever the page loads. A real test acts on the page and then checks the result. This example uses the actions page of the Cypress example app and can replace the template code:

describe('email field', () => {
  it('accepts typed text', () => {
    cy.visit('https://example.cypress.io/commands/actions')
    cy.get('.action-email').type('test@example.com')
    cy.get('.action-email').should('have.value', 'test@example.com')
  })
})

Here is how the pieces fit together. cy.visit opens the actions page, and cy.get('.action-email') finds the email field by its CSS class. .type() enters the text. The assertion .should('have.value', 'test@example.com') passes only if the field holds exactly that value, and Cypress retries it until the field is ready or the command times out.

Run the spec again. Green means every assertion passed. Red means a command or assertion failed, and the runner shows the error at the failing step, where hovering over earlier commands shows how the page looked before it broke.

To see a failure on purpose, change the expected value to a different address and rerun. Watching one test fail for the right reason is the quickest way to trust the ones that pass.

What is the difference between cypress open and cypress run?

The cypress open command starts the interactive app for writing and debugging, while cypress run runs every spec to completion from the terminal, headlessly by default. Use open while building a test and run once it works.

Add --browser chrome (or edge, firefox or chromium) to npx cypress run to choose the browser. With Electron deprecated, naming the browser now saves a broken run later.

Cypress folder structure explained

After the first E2E setup, a Cypress project has a cypress folder for tests and helpers, plus a few files in the project root.

Inside the cypress folder

• e2e holds the spec files, which end in .cy.js.
• fixtures stores static test data, such as a JSON file of sample users, that tests can load.
• support/commands.js is where custom commands go once you need them.
• support/e2e.js runs before every spec file and holds global setup.

Project root files

• cypress.config.js holds the settings that control how Cypress runs.
• node_modules contains the installed libraries, Cypress among them.
• package.json came from npm init -y and now lists Cypress under devDependencies.
• package-lock.json is written by npm and records the exact dependency versions installed, so teammates get the same setup.

What to build after your first Cypress test

Once the Cypress automation tool is running, pick one real flow in your own application, such as signing in or submitting a form, and write a spec that asserts the outcome of each step. One flow with five meaningful assertions teaches more than ten specs that only visit pages. Run it with npx cypress run --browser chrome before every commit. If you are setting up a project now, start it on Node.js 24 or 26 to avoid an upgrade in April 2027.

Readers weighing another framework can follow the same path in our Playwright installation guide for QA beginners. Manual testers planning a longer move can use the QA engineer's roadmap to AI-powered test automation.

Frequently asked questions

How can Cypress tests run without opening a browser window?

Run npx cypress run from the project folder. It runs every spec headlessly by default and exits when all tests finish. Add --browser chrome, edge or firefox to pick the browser instead of relying on Electron, which Cypress 16 has deprecated.

Can Cypress tests run in Safari or Brave?

Cypress supports Safari's engine, WebKit, only as an experimental option, and the Cypress documentation warns that you may encounter issues with it. Brave is not on the official browser list as of November 2026.

Should Cypress be installed with --save-dev?

The official install command is npm install cypress --save-dev, which lists Cypress as a dev dependency because it is only needed for development and testing. Yarn, pnpm and Bun are also supported package managers.

Does Cypress record videos of test runs?

Video recording is disabled by default. Screenshots behave differently. Cypress captures one automatically whenever a test fails during cypress run, but takes none on failure during cypress open.

Get help setting up Cypress test automation

One passing spec is a start. Turning a manual regression checklist into a reliable automated suite takes framework decisions, stable selectors and a plan for maintenance as the app changes. Arbisoft's QA and software testing services include automated testing, and the team can talk through how to plan the move from manual testing to automation.