DEV Community

Cover image for Cypress Testing: Complete Beginner's Guide
Yogesh Chavan
Yogesh Chavan

Posted on

Cypress Testing: Complete Beginner's Guide

#javascript #testing #react #cypress

Section 1: Getting Started with Cypress

1. Installing and Setting Up Cypress

Prerequisites

Before installing Cypress, ensure you have Node.js installed on your machine. Cypress requires Node.js 18.x or 20.x and above. You should also have an existing React project or create a new one.

Check your Node.js version by running this command in your terminal:

node --version
# Should output v18.x.x or higher
Enter fullscreen mode Exit fullscreen mode

Creating a React Project (Optional)

If you don't have an existing React project, create one using Vite which is the recommended approach for new React projects:

npm create vite@latest my-react-app -- --template react
cd my-react-app
npm install
Enter fullscreen mode Exit fullscreen mode

Installing Cypress

Navigate to your React project directory and install Cypress as a development dependency. Cypress is a fairly large package, so the installation might take a minute or two:

npm install cypress --save-dev

# Or using yarn
yarn add cypress --dev
Enter fullscreen mode Exit fullscreen mode

Opening Cypress for the First Time

After installation, open Cypress for the first time. This will create the initial folder structure and configuration files:

npx cypress open
Enter fullscreen mode Exit fullscreen mode

When Cypress opens for the first time, you'll see a welcome screen where you can choose between E2E Testing and Component Testing. Select E2E Testing to get started with end-to-end tests.

Cypress will then prompt you to choose a browser. You can select Chrome, Firefox, Edge, or Electron. Choose your preferred browser and click Start E2E Testing in [Browser].

Adding NPM Scripts

Add convenient scripts to your package.json for running Cypress tests:

{
  "scripts": {
    "dev": "vite",
    "build": "vite build",
    "cy:open": "cypress open",
    "cy:run": "cypress run",
    "test:e2e": "start-server-and-test dev http://localhost:5173 cy:run"
  }
}
Enter fullscreen mode Exit fullscreen mode

Tip: Use npm run cy:open for interactive development with the Cypress Test Runner. Use npm run cy:run for headless execution in CI/CD pipelines.

2. Understanding Cypress Project Structure

Project Directory Overview

After initializing Cypress, you'll notice several new folders and files in your project. Understanding each directory and file is essential for organizing your tests effectively.

my-react-app/
├── cypress/
│   ├── downloads/
│   ├── e2e/
│   │   └── spec.cy.js
│   ├── fixtures/
│   │   └── example.json
│   └── support/
│       ├── commands.js
│       └── e2e.js
├── cypress.config.js
├── package.json
└── src/
    └── (your React app)
Enter fullscreen mode Exit fullscreen mode

Key Directories and Files

cypress/e2e/

This is where your test files live. Each test file should have the .cy.js extension (or .cy.ts for TypeScript). Cypress will automatically discover and run all test files in this directory.

cypress/fixtures/

Fixtures are used to store static test data, typically in JSON format. You can use fixtures to mock API responses or provide consistent test data across multiple tests.

// cypress/fixtures/user.json
{
  "name": "John Doe",
  "email": "john@example.com",
  "role": "admin"
}
Enter fullscreen mode Exit fullscreen mode

cypress/support/commands.js

This file is where you define custom Cypress commands. Custom commands help you create reusable test logic that can be shared across multiple test files.

// cypress/support/commands.js

// Custom command to login
Cypress.Commands.add('login', (email, password) => {
  cy.visit('/login');
  cy.get('[data-testid="email"]').type(email);
  cy.get('[data-testid="password"]').type(password);
  cy.get('[data-testid="submit"]').click();
});
Enter fullscreen mode Exit fullscreen mode

cypress.config.js

This is the main configuration file for Cypress. Here you can set the base URL, viewport dimensions, timeouts, and many other options.

// cypress.config.js
import { defineConfig } from 'cypress';

export default defineConfig({
  e2e: {
    baseUrl: 'http://localhost:5173',
    viewportWidth: 1280,
    viewportHeight: 720,
    defaultCommandTimeout: 10000,
    setupNodeEvents(on, config) {
      // implement node event listeners here
    },
  },
});
Enter fullscreen mode Exit fullscreen mode

Tip: Always set a baseUrl in your cypress.config.js. This allows you to use cy.visit('/') instead of cy.visit('http://localhost:5173/'), making your tests cleaner and easier to maintain.

Configuring ESLint for Cypress

When you open Cypress test files in VS Code, you might see ESLint errors like the following:

// Error shown in VS Code:
// 'describe' is not defined. eslint(no-undef)
// 'it' is not defined. eslint(no-undef)
// 'cy' is not defined. eslint(no-undef)
// 'beforeEach' is not defined. eslint(no-undef)
Enter fullscreen mode Exit fullscreen mode

This happens because ESLint doesn't know about Cypress global variables. These are not actual errors — your tests will still run. However, to fix these warnings and get proper IntelliSense support, install the Cypress ESLint plugin:

npm install eslint-plugin-cypress --save-dev
Enter fullscreen mode Exit fullscreen mode

Then update your ESLint configuration file (eslint.config.js). First, add the import at the top of the file:

import cypressPlugin from 'eslint-plugin-cypress';
Enter fullscreen mode Exit fullscreen mode

Then add the following configuration to your ESLint config:

plugins: {
  cypress: cypressPlugin,
},
extends: [
  js.configs.recommended,
  'plugin:cypress/recommended',
  reactHooks.configs.flat.recommended,
  reactRefresh.configs.vite,
],
env: {
  'cypress/globals': true,
},
Enter fullscreen mode Exit fullscreen mode

3. Writing Your First Cypress Test

Test File Structure

Cypress uses Mocha's BDD syntax for structuring tests. If you've used Jest or Mocha before, you'll feel right at home. Tests are organized using describe blocks for grouping and it blocks for individual tests.

Let's create your first test file. First, here's the React component we'll be testing — a simple Home page component:

// src/pages/Home.jsx
import { Link } from 'react-router-dom';

const Home = () => {
  return (
    <div className="home">
      <h1>Welcome to Our App</h1>
      <p>This is the home page of our application.</p>
      <nav>
        <Link to="/about">About</Link>
        <Link to="/contact">Contact</Link>
        <Link to="/counter">Counter</Link>
      </nav>
    </div>
  );
};

export default Home;
Enter fullscreen mode Exit fullscreen mode

Setting Up the App with Routing

To use this Home component, we need to set up React Router in our application. First, install react-router-dom:

npm install react-router-dom
Enter fullscreen mode Exit fullscreen mode

Now, set up your App.jsx with routing to use the Home component:

// src/App.jsx
import { BrowserRouter, Routes, Route } from 'react-router-dom';
import Home from './pages/Home';

const App = () => {
  return (
    <BrowserRouter>
      <Routes>
        <Route path="/" element={<Home />} />
      </Routes>
    </BrowserRouter>
  );
};

export default App;
Enter fullscreen mode Exit fullscreen mode

Start your development server to run the application:

npm run dev
# App will be available at http://localhost:5173
Enter fullscreen mode Exit fullscreen mode

Writing the Test

Now, create a new file called home.cy.js in the cypress/e2e directory to test this component:

// cypress/e2e/home.cy.js

describe('Home Page', () => {
  beforeEach(() => {
    // Visit the home page before each test
    cy.visit('/');
  });

  it('should display the welcome message', () => {
    cy.contains('Welcome to Our App').should('be.visible');
  });

  it('should have a navigation menu', () => {
    cy.get('nav').should('exist');
    cy.get('nav a').should('have.length.at.least', 1);
  });
});
Enter fullscreen mode Exit fullscreen mode

Code Explanation

  • cy.visit('/') — Navigates to the home page of your application. The '/' path uses the baseUrl configured in cypress.config.js.

  • cy.contains('Welcome to Our App') — Searches the DOM for an element containing the specified text.

  • .should('be.visible') — Asserts that the element is visible on the page. This checks that the element exists, is in the viewport, and is not hidden by CSS.

  • cy.get('nav') — Selects the nav element from the DOM.

  • .should('exist') — Asserts that the element exists in the DOM. Unlike 'be.visible', this doesn't check if the element is actually visible to the user.

  • .should('have.length.at.least', 1) — Asserts that there is at least one matching element (in this case, at least one link inside the nav).

Important: Make sure inside cypress.config.js file, you have set the baseUrl to http://localhost:5173 for this test to pass. This allows cy.visit('/') to navigate to your local development server.

When you run npm run cy:open and select E2E Testing, you'll see the Cypress Test Runner interface. It will display your test files under the cypress/e2e folder. You should see your home.cy.js file listed there. Click on it to run the tests.

Understanding the Test Structure

  • describe() — Groups related tests together. You can nest describe blocks for better organization. The first argument is a string describing what you're testing.

  • beforeEach() — Runs before each test in the describe block. Perfect for setup tasks like visiting a page or logging in. There's also afterEach(), before(), and after().

  • it() — Defines an individual test case. Each it block should test one specific behavior. The first argument describes what the test should do.

Want the Complete Guide?

This article is an excerpt from my Cypress Testing - Complete Beginner's Guide. For the full, in-depth walkthrough — with every concept explained step-by-step and ready-to-use code examples — check out the complete guide.

Here's everything you'll learn inside:

→ What is Cypress & why it's replacing Selenium for modern web testing
→ Installing and setting up Cypress from scratch
→ Writing your first Cypress test (step-by-step with a real React app)
→ Selecting elements the right way — so your tests never break randomly
→ Interacting with elements — clicks, typing, dropdowns, file uploads & more
→ Assertions and expectations that actually work (and auto-retry)
→ Working with aliases and handling Cypress's async behavior
→ Testing React components in complete isolation
→ Mocking API calls with cy.intercept() for fast, reliable tests
→ Testing forms, validation, and real-time user input
→ Testing authentication flows — login, logout & protected routes
→ Best practices used by top engineering teams to keep test suites maintainable

If you found this article helpful, the full guide takes it much further.

Want More Such Guides? Check out the Ultimate React Ebooks Collection with 20+ useful and practical guides.

Don't Miss This!

Don't miss the Lifetime/Pro Subscription — get lifetime access to all my 30+ current and all future courses, ebooks, webinars along with Applications Source Code Bundle (Bonus Offer), for just $10 / ₹850 (95% OFF).

⚡ Limited-Time Offer
⚡ One-Time Payment
⚡ Lifetime Access
⚡ All Future Courses/ebooks/webinars Included

The discount won't stay forever. Grab it while it's available.

About Me

I'm a freelancer, mentor, and full-stack developer with 12+ years of experience, working primarily with React, Next.js, and Node.js.

Alongside building real-world web applications, I'm also an Industry/Corporate Trainer, training developers and teams in modern JavaScript, Next.js, and MERN stack technologies with a focus on practical, production-ready skills.

I've also created various courses with 3000+ students enrolled.

My Portfolio: https://yogeshchavan.dev/

Follow me on LinkedIn for regular content that I share every day.

Top comments (0)