Мастерство использования YAML в GitHub Actions для запуска тестов CI

После того как набор инструментов Playwright размещён на GitHub, следующим шагом является автоматическое запуск этого набора при каждом push-операции и pull-requestе. GitHub Actions обеспечивает необходимую среду для интеграционного тестирования, а YAML-файл с описанием рабочего процесса, который может сгенерировать Playwright, служит механизмом преобразования событий репозитория в тесты браузера на серверах типа cloud runners. Команды, которые пропускают этот шаг, часто обнаруживают регрессии лишь на ноутбуке спустя несколько часов после слияния кода, когда становится сложнее выявить причину сбоя.

В этом руководстве рассматриваются следующие аспекты:

• как GitHub Actions интегрируется с проектами Playwright
• что определяет блок on
• как организован блок jobs
• что выполняет каждый шаг в типичном рабочем процессе Playwright

В итоге структура файла Playwright CI должна быть достаточно понятной для редактирования при изменении версий Node, браузеров или веток. Рассматривайте пример как шаблон, а не как «черный ящик»: как только каждый элемент станет ясен, замена инструментов выполнения или добавление теста на работоспособность будут происходить легко.

Введение в GitHub Actions и YAML-файлы в Playwright

GitHub Actions — это сервис CI/CD, размещенный внутри GitHub. Он может выполнять сборку, тестирование и развертывание каждый раз, когда меняется репозиторий. Для фреймворков автоматизации это крайне важно: те же команды Playwright запускаются на известном образе инструмента выполнения без необходимости включать ноутбук и нажимать кнопку запуска.

При первоначальной установке с помощью команды npm init playwright@latest появляется вопрос о добавлении рабочего процесса GitHub Actions. Если согласиться, будет создан файл YAML в папке .github/workflows. В этом файле указывается версия Node, устанавливаются зависимости, и Playwright запускается при отправке изменений или создании pull-запросов на машинах, хранимых в GitHub.

Если отказаться от предложения, такую структуру можно добавить позже: создайте папку .github/workflows и вручную поместите туда файл с конфигурацией рабочего процесса в формате YAML.

В документации Playwright приведен готовый пример в руководстве по CI по адресу https://playwright.dev/docs/ci-intro. Этот файл служит стандартной отправной точкой для установки зависимостей, подготовки браузеров и выполнения тестов при каждой соответствующей отправке изменений или создании pull-запросов.

Понимание файла YAML в GitHub Actions

Приведённый ниже пример — типичная схема работы Playwright. Каждый раздел определяет, когда запускается работа и что должен сделать исполнитель перед тем, как на PR появится зелёный или красный статус.

name: Playwright Tests
on:
  push:
    branches: [ main, master ]
  pull_request:
    branches: [ main, master ]
jobs:
  test:
    timeout-minutes: 60
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@v4
    - uses: actions/setup-node@v4
      with:
        node-version: lts/*
    - name: Install dependencies
      run: npm ci
    - name: Install Playwright Browsers
      run: npx playwright install --with-deps
    - name: Run Playwright tests
      run: npx playwright test
    - uses: actions/upload-artifact@v4
      if: ${{ !cancelled() }}
      with:
        name: playwright-report
        path: playwright-report/
        retention-days: 30

Параметр on

Ключ on перечисляет события, запускающие рабочий процесс. Это входная точка: без соответствующего события ничего не выполняется.

В примере используются два типа событий:

1. События пуша: пуш в репозиторий main или master запускает обработку, поэтому прямые коммиты в стандартные ветки проверяются немедленно.
2. События pull request: открытие или обновление PR, направленного на main или master, также запускает обработку, что позволяет проверить предлагаемые слияния до их выполнения.

Вместе эти триггеры охватывают как коммиты, внесённые в кодовую базу, так и действия, связанные с ревью, что и является механизмом безопасности, на котором основаны автоматизированные фреймворки.

Обзор раздела задач

Блок jobs представляет собой план работы, который выполняется после того, как находится соответствующий триггер. Каждая задача обычно включает:

1. Имя задачи: метка, такая как test, которая идентифицирует единицу работы.
2. Среда выполнения: образ машины, часто ubuntu-latest.
3. Временные ограничения и условия: параметры вроде timeout-minutes, определяющие максимальное время выполнения задачи.
4. Шаги: последовательные действия — получение кода, установка, подготовка браузеров, запуск тестов, загрузка результатов.

Этот раздел является основой рабочего процесса: подготовка среды, выполнение Playwright и хранение результатов зависят от него. Если задача проваливается, GitHub сначала показывает название неудавшегося шага, поэтому четкие метки здесь помогают при анализе инцидентов.

Подробности шагов

Получение кода

Руннер должен содержать файлы репозитория. Сначала почти всегда выполняется операция checkout; без неё последующие шаги не имеют чего устанавливать или запускать. Большинство рабочих процессов Playwright используют официальную операцию checkout, чтобы рабочая дерево совпадала с коммитом, который запустил выполнение.

Настройка Node.js

Playwright работает на основе Node. Использование фиксированной версии node-version: lts/* обеспечивает на руннере самую последнюю версию с долгосрочной поддержкой, что позволяет скриптам установки и тестирования использовать стабильную среду выполнения. Также допустимо явно указать конкретную основную версию, если в проекте уже стандартизирована определённая линия LTS локально.

Установка зависимостей

npm ci устанавливает компоненты из package-lock.json в чистую дерево проекта. В среде CI предпочтительнее использовать его вместо npm install, поскольку установка на основе файла lockfile обеспечивает воспроизводимость результатов между запусками и чётко выдаёт ошибку, если файл lockfile устарел по сравнению с package.json.

Установка браузеров Playwright

Для тестирования требуются бинарники Chromium, Firefox и WebKit, а также соответствующие системные пакеты. На этом шаге загружаются эти браузеры, чтобы инструмент тестирования мог их запустить. Игнорирование этого шага часто становится причиной неудач локальных тестов с результатом «зелёный», но неудач в CI с результатом «красный», особенно когда у разработчиков уже есть кэшированные браузеры на их машинах.

Запуск тестов Playwright

Вот что происходит: Playwright выполняет тесты проекта в настроенных браузерах и сообщает о результатах — успешно или неудачно. Неудачи выявляются по ненулевому коду завершения, поэтому проверка в GitHub блокирует слияние ветки, если правила защиты веток этого требуют.

Загрузка отчёта о тестах

В рамках данного процесса работы генерируемый отчет Playwright сохраняется с помощью команды upload-artifact, часто с настройкой retention-days: 30, чтобы ошибки оставались доступными для анализа в течение месяца. Условие вроде if: ${{ !cancelled() }} препятствует загрузке, когда запуск был отменен вместо завершения. Хранение HTML-отчета в качестве артефакта обычно позволяет быстрее отлаживать проблемы, чем перезапускать всю сборку только для воспроизведения нестабильной проверки.