Cypress Basics (Part 1): Introduction and Setup

Cypress is a popular end-to-end (E2E) testing framework for the web. It runs in the browser, gives you a clear UI to watch tests run, and uses a simple API that makes writing and debugging tests straightforward. This post covers what Cypress is, why teams choose it, and how to get it running so you can write your first test.

What is Cypress?

Cypress is an open-source E2E testing tool. Unlike tools that drive the browser from the outside (e.g. Selenium), Cypress runs inside the same run loop as your app. That means:

• Direct access to the DOM, network, and timers so you can stub and control them.
• Automatic waiting for elements and network requests, so you write fewer explicit waits.
• Time-travel debugging in the Test Runner: you can step back to any command and see the app state.
• Screenshots and videos of failing runs to understand what went wrong.

Cypress is built for modern web apps (SPAs, React, Vue, etc.) and works well in CI with headless browsers.

Why use Cypress?

• Developer and QA friendly: Same JavaScript/TypeScript you use in the app; no separate language or complex setup.
• Fast feedback: The interactive Test Runner shows each step; failures are easy to inspect.
• Stable by design: Built-in retry and waiting reduce flaky "element not found" failures when used correctly.
• Good docs and community: Official docs, examples, and plugins (e.g. for code coverage, visual testing).

If you already write API or unit tests and want to add E2E coverage, Cypress is a solid choice.

Installing Cypress

Use npm or yarn in your project (or create a new folder for tests).

npm init -y
npm install cypress --save-dev

Or with yarn:

yarn add -D cypress

Open Cypress once to scaffold config and example specs:

npx cypress open

This creates a cypress folder (or cypress/e2e depending on version) and a cypress.config.js (or cypress.config.ts). You can remove the example specs and keep only your own.

Project structure (typical)

After opening Cypress once, a minimal layout looks like:

your-project/
  cypress/
    e2e/
      login.cy.js          # your specs
      home.cy.js
    support/
      commands.js          # custom commands (optional)
      e2e.js               # runs before each spec (optional)
  cypress.config.js

Put your test files under cypress/e2e/ (or the path you set in config). Use .cy.js or .cy.ts so Cypress discovers them.

Your first test

Create cypress/e2e/hello.cy.js:

describe('Hello Cypress', () => {
  it('visits the Cypress example page', () => {
    cy.visit('https://example.cypress.io')
    cy.contains('h1', 'Kitchen Sink').should('be.visible')
  })
})

Then run:

npx cypress open

Click the spec hello.cy.js. Cypress opens a browser, visits the URL, finds the heading, and asserts it's visible. You've just run your first E2E test.

To run headless (e.g. for CI):

npx cypress run

Summary

• Cypress is an E2E testing framework that runs in the browser and gives you a Test Runner, automatic waiting, and time-travel debugging.
• Install with npm install cypress --save-dev, then run npx cypress open to scaffold and run tests.
• Tests live in cypress/e2e/; a minimal test uses cy.visit() and cy.contains() with .should() assertions.

In the next part we'll go deeper into writing tests: selectors, common commands (get, click, type), and assertions.