E2E тестирование с Cypress

Введение

E2E (end-to-end) тестирование — один из ключевых уровней тестирования современных веб-приложений. Оно позволяет проверить, как приложение работает целиком: от пользовательского интерфейса до API и базы данных. Cypress — один из наиболее популярных инструментов для E2E тестирования, который завоевал признание в React-сообществе благодаря удобному API, встроенному отладчику и быстрой настройке.

В этой статье вы узнаете, что такое E2E тестирование и зачем нужен Cypress, как установить и настроить его в React-проекте, освоите основные команды, научитесь тестировать формы, навигацию и API-вызовы, а также настроите запуск тестов в CI/CD.

Что такое E2E тестирование и зачем нужен Cypress

Уровни тестирования

В разработке принято выделять три уровня тестирования:

• Unit-тесты — проверяют отдельные функции и компоненты в изоляции.
• Интеграционные тесты — проверяют взаимодействие нескольких модулей.
• E2E-тесты — проверяют приложение целиком, имитируя реальные действия пользователя в браузере.

E2E-тесты наиболее близки к реальному сценарию использования: они открывают браузер, переходят по страницам, заполняют формы, нажимают кнопки и проверяют результаты. Именно поэтому они дают наибольшую уверенность в том, что приложение работает корректно для конечного пользователя.

Почему Cypress

Cypress — это инструмент E2E тестирования, разработанный специально для современных веб-приложений. Его отличают:

• Работа внутри браузера. В отличие от Selenium, Cypress выполняется непосредственно в контексте браузера, что даёт доступ ко всем DOM-событиям и сетевым запросам без сторонних драйверов.
• Автоматическое ожидание. Cypress автоматически ждёт появления элементов, завершения запросов и анимаций — без явных sleep() или waitFor().
• Встроенный отладчик. Интерактивный режим Cypress Test Runner позволяет просматривать каждый шаг теста в реальном времени с историей снимков DOM.
• Мокирование сети. Встроенная команда cy.intercept() позволяет перехватывать и подменять HTTP-запросы прямо в тестах.
• Компонентное тестирование. Помимо E2E, Cypress поддерживает изолированное тестирование React-компонентов.

Установка и настройка Cypress в React проекте

Установка

Для установки Cypress выполните следующую команду в корне вашего React-проекта:

npm install --save-dev cypress

или с использованием yarn:

yarn add --dev cypress

Первый запуск

После установки запустите Cypress через npx:

npx cypress open

При первом запуске Cypress предложит выбрать тип тестирования: E2E Testing или Component Testing. Выберите нужный вариант, и Cypress автоматически создаст конфигурационный файл cypress.config.ts (или cypress.config.js) и базовую структуру директорий.

Структура проекта

После инициализации в корне проекта появится папка cypress:

cypress/
├── e2e/           # E2E тесты
├── fixtures/      # Фиктивные данные (JSON-файлы)
├── support/
│   ├── commands.ts  # Кастомные команды
│   └── e2e.ts       # Конфигурация поддержки
cypress.config.ts    # Основной конфиг Cypress

Конфигурационный файл

Пример базовой конфигурации cypress.config.ts:

import { defineConfig } from 'cypress';

export default defineConfig({
  e2e: {
    baseUrl: 'http://localhost:3000', // базовый URL вашего приложения
    setupNodeEvents(on, config) {
      // плагины и обработчики событий
    },
  },
});

Параметр baseUrl позволяет использовать относительные пути в командах cy.visit(), например cy.visit('/login') вместо полного URL.

Добавление скриптов в package.json

Для удобства добавьте скрипты в package.json:

{
  "scripts": {
    "cy:open": "cypress open",
    "cy:run": "cypress run"
  }
}

Основные команды Cypress

cy.visit()

Команда cy.visit() открывает страницу по указанному URL:

cy.visit('/');           // корневой маршрут (относительно baseUrl)
cy.visit('/about');      // страница "О нас"
cy.visit('https://example.com'); // абсолютный URL

cy.get()

cy.get() — основной способ поиска элементов в DOM. Принимает CSS-селектор:

cy.get('button');                   // все кнопки
cy.get('.submit-button');           // элемент по классу
cy.get('#username');                // элемент по ID
cy.get('[data-cy="login-btn"]');    // элемент по data-атрибуту
cy.get('form input[type="email"]'); // вложенный селектор

Рекомендуется использовать специальный атрибут data-cy (или data-testid) для тестирования — это делает тесты независимыми от изменений CSS-классов и структуры DOM.

cy.contains()

Команда cy.contains() ищет элемент по текстовому содержимому:

cy.contains('Войти');              // найти элемент с текстом "Войти"
cy.contains('button', 'Войти');   // кнопка с текстом "Войти"
cy.contains(/^Добро пожаловать/); // регулярное выражение

cy.click()

Команда cy.click() имитирует клик по элементу:

cy.get('[data-cy="submit-btn"]').click();
cy.contains('Войти').click();
cy.get('.menu-item').first().click();

cy.type()

cy.type() вводит текст в поле ввода:

cy.get('#email').type('user@example.com');
cy.get('#password').type('secret123');

// Специальные символы
cy.get('#search').type('React{enter}'); // нажать Enter
cy.get('#field').type('{selectall}{backspace}'); // выделить всё и удалить

Cypress поддерживает специальные клавиши в фигурных скобках: {enter}, {tab}, {backspace}, {esc}, {selectall} и другие.

cy.clear()

Очищает содержимое поля ввода:

cy.get('#search').clear();
cy.get('#search').clear().type('новый текст');

cy.should()

Команда cy.should() используется для утверждений (assertions). Cypress использует синтаксис Chai:

cy.get('[data-cy="title"]').should('be.visible');
cy.get('[data-cy="error"]').should('contain', 'Неверный пароль');
cy.get('button').should('be.disabled');
cy.get('[data-cy="count"]').should('have.text', '5');
cy.url().should('include', '/dashboard');

cy.wait()

Хотя Cypress автоматически ждёт большинства событий, иногда нужно явно дождаться запроса или заданного времени:

cy.wait('@apiRequest'); // ждать перехваченный запрос (см. cy.intercept)
cy.wait(1000);          // ждать 1 секунду (использовать с осторожностью)

Cypress Component Testing vs E2E Testing

Cypress поддерживает два режима тестирования, которые решают разные задачи.

E2E Testing

E2E тестирование запускает реальный браузер и тестирует приложение в целом — с реальным сервером, роутингом и API. Тест открывает страницу и взаимодействует с ней так, как это делал бы пользователь:

// cypress/e2e/login.cy.ts
describe('Страница входа', () => {
  it('должна позволять авторизоваться', () => {
    cy.visit('/login');
    cy.get('#email').type('admin@example.com');
    cy.get('#password').type('password');
    cy.get('[data-cy="login-btn"]').click();
    cy.url().should('include', '/dashboard');
  });
});

Когда использовать: для критических пользовательских сценариев (авторизация, оформление заказа, навигация по приложению).

Component Testing

Component Testing позволяет монтировать React-компоненты в изоляции, без запуска всего приложения. Это быстрее и удобнее для тестирования отдельных компонентов:

// cypress/component/Button.cy.tsx
import Button from './Button';

describe('Компонент Button', () => {
  it('вызывает onClick при клике', () => {
    const onClick = cy.stub().as('clickHandler');
    cy.mount(<Button onClick={onClick}>Нажми меня</Button>);
    cy.get('button').click();
    cy.get('@clickHandler').should('have.been.calledOnce');
  });
});

Когда использовать: для тестирования логики и состояний отдельных компонентов, особенно с разными наборами пропсов.

Сравнение

Тестирование форм

Формы — один из наиболее распространённых объектов E2E тестирования. Рассмотрим пример тестирования формы регистрации:

// cypress/e2e/registration.cy.ts
describe('Форма регистрации', () => {
  beforeEach(() => {
    cy.visit('/register');
  });

  it('должна отображать ошибки при отправке пустой формы', () => {
    cy.get('[data-cy="register-form"]').submit();
    cy.get('[data-cy="email-error"]').should('contain', 'Введите email');
    cy.get('[data-cy="password-error"]').should('contain', 'Введите пароль');
  });

  it('должна успешно зарегистрировать пользователя', () => {
    cy.get('#name').type('Иван Петров');
    cy.get('#email').type('ivan@example.com');
    cy.get('#password').type('SecurePass123');
    cy.get('#confirm-password').type('SecurePass123');
    cy.get('[data-cy="submit-btn"]').click();

    // Проверяем редирект после успешной регистрации
    cy.url().should('include', '/welcome');
    cy.contains('Добро пожаловать, Иван!').should('be.visible');
  });

  it('должна блокировать кнопку отправки при несовпадении паролей', () => {
    cy.get('#password').type('password1');
    cy.get('#confirm-password').type('password2');
    cy.get('[data-cy="submit-btn"]').should('be.disabled');
  });
});

Работа с выпадающими списками и чекбоксами

// Выбор из <select>
cy.get('select[name="country"]').select('Russia');

// Чекбокс
cy.get('[data-cy="agree-checkbox"]').check();
cy.get('[data-cy="agree-checkbox"]').should('be.checked');

// Radio button
cy.get('[data-cy="role-admin"]').check();

Тестирование навигации

Cypress позволяет проверять маршрутизацию React Router или других роутеров:

// cypress/e2e/navigation.cy.ts
describe('Навигация приложения', () => {
  beforeEach(() => {
    cy.visit('/');
  });

  it('должна переходить на страницу "О нас" по клику на ссылку', () => {
    cy.get('[data-cy="nav-about"]').click();
    cy.url().should('include', '/about');
    cy.get('h1').should('contain', 'О нас');
  });

  it('должна перенаправлять неавторизованного пользователя на страницу входа', () => {
    cy.visit('/profile');
    cy.url().should('include', '/login');
  });

  it('должна сохранять историю браузера', () => {
    cy.visit('/about');
    cy.visit('/contact');
    cy.go('back');
    cy.url().should('include', '/about');
  });
});

Тестирование API вызовов с cy.intercept()

Команда cy.intercept() позволяет перехватывать HTTP-запросы, что необходимо для:

• мокирования ответов API (без реального бекенда);
• проверки отправляемых данных;
• тестирования состояний загрузки и ошибок.

Базовое мокирование

describe('Список пользователей', () => {
  it('должен отобразить список пользователей из API', () => {
    // Перехватываем GET запрос и возвращаем фиктивные данные
    cy.intercept('GET', '/api/users', {
      statusCode: 200,
      body: [
        { id: 1, name: 'Анна Смирнова', email: 'anna@example.com' },
        { id: 2, name: 'Борис Иванов', email: 'boris@example.com' },
      ],
    }).as('getUsers'); // псевдоним для ожидания

    cy.visit('/users');
    cy.wait('@getUsers'); // ждём завершения запроса

    cy.get('[data-cy="user-item"]').should('have.length', 2);
    cy.contains('Анна Смирнова').should('be.visible');
  });
});

Использование фикстур

Фикстуры — это JSON-файлы с тестовыми данными, которые хранятся в cypress/fixtures/:

// cypress/fixtures/users.json
[
  { "id": 1, "name": "Анна Смирнова", "email": "anna@example.com" },
  { "id": 2, "name": "Борис Иванов", "email": "boris@example.com" }
]

cy.intercept('GET', '/api/users', { fixture: 'users.json' }).as('getUsers');

Тестирование состояния ошибки

it('должен отображать сообщение об ошибке при сбое API', () => {
  cy.intercept('GET', '/api/users', {
    statusCode: 500,
    body: { message: 'Внутренняя ошибка сервера' },
  }).as('getUsersError');

  cy.visit('/users');
  cy.wait('@getUsersError');

  cy.get('[data-cy="error-message"]').should('be.visible');
  cy.contains('Не удалось загрузить пользователей').should('be.visible');
});

Проверка тела запроса

it('должен отправить корректные данные при создании пользователя', () => {
  cy.intercept('POST', '/api/users', (req) => {
    // Проверяем тело запроса
    expect(req.body).to.have.property('name', 'Новый Пользователь');
    expect(req.body).to.have.property('email', 'new@example.com');
    req.reply({ statusCode: 201, body: { id: 3, ...req.body } });
  }).as('createUser');

  cy.visit('/users/new');
  cy.get('#name').type('Новый Пользователь');
  cy.get('#email').type('new@example.com');
  cy.get('[data-cy="submit-btn"]').click();
  cy.wait('@createUser');
});

Тестирование состояния загрузки

it('должен отображать спиннер во время загрузки', () => {
  cy.intercept('GET', '/api/data', (req) => {
    // Задержка ответа для проверки состояния загрузки
    req.reply((res) => {
      res.delay = 1000;
      res.body = { items: [] };
    });
  }).as('slowRequest');

  cy.visit('/dashboard');
  cy.get('[data-cy="loading-spinner"]').should('be.visible');
  cy.wait('@slowRequest');
  cy.get('[data-cy="loading-spinner"]').should('not.exist');
});

Кастомные команды

Cypress позволяет создавать собственные команды для переиспользования часто повторяющейся логики. Команды определяются в cypress/support/commands.ts:

// cypress/support/commands.ts

// Команда для авторизации
Cypress.Commands.add('login', (email: string, password: string) => {
  cy.visit('/login');
  cy.get('#email').type(email);
  cy.get('#password').type(password);
  cy.get('[data-cy="login-btn"]').click();
  cy.url().should('include', '/dashboard');
});

// Команда для авторизации через API (быстрее, чем через UI)
Cypress.Commands.add('loginByApi', (email: string, password: string) => {
  cy.request('POST', '/api/auth/login', { email, password }).then((response) => {
    window.localStorage.setItem('token', response.body.token);
  });
});

Использование кастомных команд в тестах:

describe('Личный кабинет', () => {
  beforeEach(() => {
    cy.login('admin@example.com', 'password');
  });

  it('должен отображать данные профиля', () => {
    cy.visit('/profile');
    cy.get('[data-cy="user-name"]').should('be.visible');
  });
});

Запуск тестов в headless режиме и CI/CD

Headless режим

Для запуска тестов без открытия браузера (например, в CI) используйте команду:

npx cypress run

По умолчанию Cypress запускает тесты в браузере Electron. Для указания конкретного браузера:

npx cypress run --browser chrome
npx cypress run --browser firefox

Запуск отдельного файла или группы тестов:

npx cypress run --spec "cypress/e2e/login.cy.ts"
npx cypress run --spec "cypress/e2e/**/*.cy.ts"

Интеграция с GitHub Actions

# .github/workflows/e2e.yml
name: E2E Tests

on:
  push:
    branches: [main, develop]
  pull_request:
    branches: [main]

jobs:
  cypress-run:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout code
        uses: actions/checkout@v4

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: 20

      - name: Install dependencies
        run: npm ci

      - name: Build application
        run: npm run build

      - name: Start server
        run: npm start &

      - name: Wait for server
        run: npx wait-on http://localhost:3000

      - name: Run Cypress tests
        uses: cypress-io/github-action@v6
        with:
          browser: chrome
          headed: false

Официальный GitHub Action от Cypress

Cypress предоставляет официальный GitHub Action, который упрощает интеграцию:

- name: Cypress run
  uses: cypress-io/github-action@v6
  with:
    start: npm start          # команда запуска сервера
    wait-on: 'http://localhost:3000' # ждать запуска сервера
    browser: chrome

Action автоматически устанавливает зависимости, кеширует бинарники Cypress и запускает тесты.

Сохранение артефактов

При падении тестов Cypress автоматически сохраняет скриншоты и видео. В CI их можно сохранить как артефакты:

- name: Upload screenshots
  uses: actions/upload-artifact@v4
  if: failure()
  with:
    name: cypress-screenshots
    path: cypress/screenshots

- name: Upload videos
  uses: actions/upload-artifact@v4
  if: always()
  with:
    name: cypress-videos
    path: cypress/videos

Параллельный запуск

Для ускорения можно запускать тесты параллельно через Cypress Cloud (ранее Cypress Dashboard):

- name: Cypress run parallel
  uses: cypress-io/github-action@v6
  with:
    record: true
    parallel: true
    group: 'E2E Tests'
  env:
    CYPRESS_RECORD_KEY: ${{ secrets.CYPRESS_RECORD_KEY }}

Лучшие практики

Используйте data-атрибуты для селекторов

Вместо CSS-классов или ID рекомендуется использовать специальные data-cy атрибуты:

// ✅ Правильно
<button data-cy="submit-btn">Отправить</button>

// ❌ Избегайте
<button className="btn-primary">Отправить</button>

Это делает тесты независимыми от изменений стилей.

Избегайте явных задержек

// ❌ Плохо
cy.wait(2000);

// ✅ Хорошо — ждать конкретного события
cy.wait('@apiRequest');
cy.get('[data-cy="result"]').should('be.visible');

Изолируйте тесты

Каждый тест должен быть независимым. Используйте beforeEach для сброса состояния:

beforeEach(() => {
  cy.clearLocalStorage();
  cy.clearCookies();
  cy.visit('/');
});

Переиспользуйте логику через кастомные команды

Выносите повторяющуюся логику (авторизация, заполнение форм) в кастомные команды Cypress.

Заключение

Cypress — это мощный и удобный инструмент для E2E тестирования React-приложений. Его основные преимущества — автоматическое ожидание, встроенный отладчик, простое мокирование API через cy.intercept() и поддержка компонентного тестирования.

Начните с написания тестов для критических пользовательских сценариев: авторизации, оформления заказа, основной навигации. Используйте data-cy атрибуты для стабильных селекторов, кастомные команды для переиспользования логики, и CI/CD интеграцию для автоматического запуска тестов при каждом изменении кода.

Cypress значительно снижает риск регрессий и повышает уверенность команды в работоспособности приложения на каждом этапе разработки.