Интеграция API-тестов с Jenkins Pipeline: с чего начать? / forpes.ru

Главная
Интеграция API-тестов с Jenkins Pipeline: с чего начать?

Интеграция API-тестов с Jenkins Pipeline: с чего начать? +4

07.06.2025 19:10

RomanPers 1 895 Источник

Вы написали серию интеграционных API-тестов на Java (с использованием TestNG и RestAssured) и хотите, чтобы они сами запускались при каждом изменении кода? Отличная идея! Настроив Continuous Integration/Continuous Delivery (CI/CD), вы избавитесь от рутины ручного прогона тестов и получите быстрый фидбэк о качестве системы. В этой статье я в живой манере расскажу, как шаг за шагом встроить ваши API-тесты в Jenkins Pipeline на локальном сервере. Вас ждёт установка Jenkins, подключение Maven-проекта, написание Jenkinsfile (Groovy Pipeline скрипта), настройка красивых Allure-отчётов, интеграция с GitHub и даже автоматический деплой при успешном прохождении тестов. Поехали!

Установка и настройка Jenkins локально

Начнём с основы – у вас должен быть установлен Jenkins, популярный сервер CI. Как это сделать?

Скачать Jenkins: Перейдите на официальный сайт Jenkins и загрузите последнюю версию. Проще всего взять jenkins.war – универсальный исполняемый файл. Убедитесь, что Java (JDK) установлена, иначе Jenkins не запустится.

Версия может отличатся.
Запустить Jenkins: Откройте терминал/командную строку, перейдите в папку с jenkins.war и выполните команду:
```
java -jar jenkins.war
```
Jenkins запустится встроенным веб-сервером на порту 8080 . Когда в логах появится сообщение о старте, откройте браузер и перейдите по адресу http://localhost:8080 – вы увидите веб-интерфейс Jenkins.
Первая настройка: При первом запуске Jenkins попросит ввести административный пароль. Где его взять? В консоли запуска найдите строку с паролем или откройте файл initialAdminPassword (путь будет указан на странице разблокировки Jenkins).

Данные строчки можно увидеть во время установки war файла.
Введите этот пароль – Jenkins разблокируется. Далее появится предложение установить плагины. Рекомендуется нажать «Установить рекомендованные плагины» – Jenkins автоматически загрузит базовый набор расширений. Потерпите несколько минут, пока все необходимые плагины устанавливаются.

Происходит скацмвание стандартных плагинов.
Создание пользователя: После установки плагинов вам предложат создать администратора. Заполните поля (имя, пароль, email) – это будет ваш аккаунт для входа в Jenkins.

Создаем пользователя.
Готово! Вы попадёте на главную панель Jenkins. Локальный Jenkins-сервер запущен и настроен по умолчанию. Интерфейс у него веб-based, так что все дальнейшие настройки будем делать через браузер.

? Лайфхак: Jenkins можно устанавливать и другими способами – через установщики для Windows, менеджеры пакетов в Linux, Docker-контейнер и т.д. Но запуск через jenkins.war хорош для локального старта: минимум усилий – скачал и запустил.

Подключение Maven-проекта с тестами к Jenkins

Jenkins работает со сборочными проектами (jobs). Наша цель – заставить Jenkins брать исходный код с тестами и запускать Maven, чтобы прогнать TestNG-тесты. Предположим, ваш код находится в Git-репозитории (например, на GitHub). Как подружить Jenkins с вашим проектом?

Создадим Pipeline Job: На главной странице Jenkins нажмите «Создать элемент» (New Item). Введите имя проекта (например, API-Tests), выберите тип Pipeline (конвейер) и нажмите ОК.
Но перед этим, откроем в новой вкладке нашу главную страницу Jenkins, нам необходимо добавить креды с нащего уделенного реппозитория, у меня это будет GitHub. Необходимо в левом меню выбрать Dashboard -> Manage Jenkins -> Credentials и выбрать global

После чего откроется окно Credentials, где выбираем +New Credentials

Для HTTPS лучше использовать GitHub Token вместо пароля (GitHub больше не поддерживает обычные пароли для API).
Продолжим настройки исходника (SCM): После создания вы попадёте на страницу конфигурации Job’а. Здесь нужно сказать Jenkins, откуда брать код. В разделе Pipeline найдите поле Definition (Определение) и выберите значение Pipeline script from SCM – то есть «скрипт конвейера из системы контроля версий». Появятся параметры источника: выберите Git как систему контроля версий и укажите URL вашего репозитория и нужную ветку. Например, для GitHub это может быть https://github.com/ваш-логин/ваш-проект.git, ветка main или master. Если репозиторий приватный, добавьте креденшлы (логин/пароль или ключ) – соответствующая кнопка Add позволит сохранить учетные данные и выбрать их для подключения.
Jenkinsfile: Jenkins ожидает, что в репозитории есть файл Jenkinsfile, в котором описан Pipeline (о том, как его написать – чуть позже). Если ваш Jenkinsfile лежит не в корне репо или носит другое название, укажите путь в поле Script Path. В противном случае оставьте значение по умолчанию – Jenkinsfile.
Сохраняем конфигурацию: Нажмите Сохранить. Теперь Jenkins знает, как получить код вашего Maven-проекта с тестами.

Обратите внимание, что мы выбрали подход Pipeline as code – Jenkinsfile хранится в самом репозитории. Это современный метод: конфигурация сборки версионируется вместе с исходниками. Как отмечают сами разработчики, пайплайн лучше хранить в Git, а не вводить вручную через. (Впрочем, для теста вы могли бы выбрать и вариант Pipeline script и вставить код прямо в поле конфигурации – но тогда при изменениях скрипта надо не забывать обновлять его в Jenkins вручную).

А вы знали? Jenkins Pipeline – это набор плагинов, позволяющий описывать процессы сборки и доставки в виде кода (Pipeline-as-code). Файл Jenkinsfile пишется на специальном DSL, основанном на Groovy. Звучит чуть пугающе, но на практике синтаксис довольно простой!

Перед тем как настроить сам скрипт конвейера, убедимся, что Jenkins имеет всё необходимое для сборки Maven-проекта. Java у нас уже стоит (иначе Jenkins не работал бы), а как насчёт Maven? Есть два варианта: установить Maven на сам сервер и прописать в PATH или настроить Maven через Jenkins. Второй способ удобнее: зайдите в Manage Jenkins -> Global Tool Configuration и найдите раздел Maven. Там можно либо задать путь к уже установленному Maven, либо нажать «Install automatically» и выбрать версию Maven из списка – Jenkins сам её скачает и будет использовать. Например, можно добавить Maven с именем "Maven 3.8.6". Не забудьте сохранить изменения. Теперь Jenkins знает, где взять Maven.

Настройка Jenkins Pipeline (Jenkinsfile)

Переходим к главному – напишем Jenkinsfile, который будет собирать и тестировать наш проект. Declarative Pipeline синтаксис позволяет описывать конвейер стадиями (stages). Давайте создадим три стадии: сборка, тестирование и деплой. Ниже приведён пример Jenkinsfile с комментариями:

pipeline {
    agent any            // Агент: где выполнять pipeline (any – на любом доступном узле, в нашем случае на самом Jenkins)
    tools { 
        maven "Maven 3.8.6"   // Указываем установленный Maven (имя должно совпадать с настроенным в Global Tools)
    }
    stages {
        stage('Build') {
            steps {
                echo 'Starting build...'
                // Сборка проекта (компиляция и упаковка без запуска тестов):
                sh 'mvn clean package -DskipTests'
            }
        }
        stage('Test') {
            steps {
                echo 'Running tests...'
                // Запускаем тесты Maven (TestNG + RestAssured):
                sh 'mvn clean test'
            }
            // Мы добавим блок post чуть позже для публикации отчёта Allure
        }
        // stage('Deploy') будет добавлен после настройки тестов и отчетов
    }
}

Разберём, что тут происходит:

agent any: означает, что для выполнения pipeline можно использовать любой доступный исполнитель (по умолчанию Jenkins запускает на своем основном узле). Это удобно для локального Jenkins – все шаги выполняются прямо на вашем компьютере.
tools { maven "Maven 3.8.6" }: эта директива добавляет Maven в PATH на время выполнения Pipeline. Мы указали имя Maven, настроенного ранее. Благодаря этому, команда mvn будет доступна внутри шагов (иначе пришлось бы явно указывать путь или использовать Docker-образ с Maven).
stage('Build'): первая стадия – сборка. Здесь мы выполняем mvn clean package с флагом -DskipTests, чтобы собрать проект (скомпилировать код, упаковать артефакт), не запуская тесты на этапе сборки. Это частый прием: отделить компиляцию от тестирования.
stage('Test'): вторая стадия – запуск тестов. Команда mvn clean test запускает тестовые классы (TestNG) проекта. Обратите внимание, мы снова вызываем clean – это не обязательно, но гарантирует, что мы тестируем с нуля (очищаем target перед тестами). Если ваши тесты зависят от сборки (например, нужно собрать WAR, развернуть его и потом тестировать API), то флаг -DskipTests на этапе Build как раз предотвращает преждевременный запуск тестов, а здесь мы выполняем их на собранном коде.
echo: вспомогательные команды для логгирования. Например, echo 'Running tests...' выведет сообщение в консоль Jenkins, чтобы в логе было нагляднее, на каком этапе пайплайн.
Мы пока не добавляли стадию Deploy и не обрабатывали отчёты – об этом чуть позже.

Попробуем запустить наш Pipeline (можно перейти в джобу Jenkins и нажать «Собрать»). Jenkins выкачает код из Git, выполнит стадии по очереди. Вы можете следить за ходом выполнения в режиме реального времени: откройте консоль лог (там будет видно, как Maven скачивает зависимости, компилирует, запускает тесты). Если все настроено правильно, Jenkins в конце выдаст результат сборки: Успех (зеленый) или Провал (красный). Что означает провал? Например, один из тестов упал – тогда Maven завершится с ошибкой, и Jenkins пометит билд как проваленный. CI-сервер автоматически остановит конвейер на стадии Test, не переходя к следующим этапам (нет смысла деплоить, если тесты не прошли). Такой подход защищает вас от выкатывания заведомо некорректного кода.

Однако, сейчас вывод тестов – это просто лог в консоли Jenkins. Хотелось бы красивый HTML-отчёт с графиками, списком тестов, шагами, скриншотами и пр. Настало время подключить Allure!

Настройка Allure-отчётности

Allure Report – шикарный инструмент для визуализации результатов автотестов. Он собирает информацию о запусках (статус тестов, шаги, прикрепленные данные) и формирует наглядный HTML-отчёт. Интегрировать Allure с Jenkins несложно, сделаем это в несколько шагов:

Установка плагина Allure: В панели Jenkins зайдите в Manage Jenkins -> Manage Plugins (Управление плагинами). На вкладке Available (Доступные) найдите плагин Allure Jenkins Plugin и установите его. Для безопасности можете перезапустить Jenkins после установки плагина. (Примечание: плагин Allure зависит от HTML Publisher – в новых версиях он ставится автоматически, но проверьте, что он есть. HTML Publisher нужен Jenkins для отображения статических HTML-отчётов внутри интерфейса). После установки Allure-плагина вы заметите, что Jenkins «умеет» работать с Allure-отчётами.
Конфигурация Allure Commandline: Плагин – это хорошо, но за кадром Allure генерирует отчёты с помощью утилиты командной строки. Нужно указать Jenkins, где взять Allure CLI. В Manage Jenkins -> Global Tool Configuration пролистайте вниз – появится секция Allure Commandline (её добавил установленный плагин). Нажмите «Add Allure Commandline». Введите имя, например «Allure 2.x». Можно позволить Jenkins скачать Allure автоматически: поставьте галочку Install automatically и выберите нужную версию в выпадающем списке (как правило, последняя стабильная). Сохраните настройки. Теперь в пайплайне мы сможем вызывать команду allure.
Подготовка проекта для Allure: Чтобы отчёт сформировался, одних действий Jenkins недостаточно – ваши тесты должны сгенерировать результаты Allure. Обычно это JSON и XML файлы в папке target/allure-results. Что для этого нужно? Добавить в Maven-проект зависимость Allure TestNG adapter. Откройте ваш pom.xml и добавьте:
```
<dependency>
    <groupId>io.qameta.allure</groupId>
    <artifactId>allure-testng</artifactId>
    <version>2.20.0</version> 
    <scope>test</scope>
</dependency>
```
Также добавьте зависимость AspectJ Weaver (она необходима Allure для ловли событий тестов):
```
<dependency>
    <groupId>org.aspectj</groupId>
    <artifactId>aspectjweaver</artifactId>
    <version>1.9.7</version> 
</dependency>
```
(Приведены примерные версии; актуальные смотрите на Maven Central.) Кроме того, нужно настроить Maven Surefire Plugin для запуска с агентом AspectJ – но не пугайтесь, это просто специальная строчка в конфигурации плагина. Например, в pom.xml внутри <plugin><artifactId>maven-surefire-plugin</artifactId> добавьте:
```
<configuration>
    <argLine>-javaagent:"${settings.localRepository}/org/aspectj/aspectjweaver/${aspectj.version}/aspectjweaver-${aspectj.version}.jar"</argLine>
</configuration>
```
(Эта строка позволит аспекту Allure подключиться к тестам. Подробнее об этой настройке можно почитать в документации Allure.) После этого при запуске mvn test тесты под TestNG будут собирать данные для Allure и сохранять результаты в папке target/allure-results
Изменяем Jenkinsfile для Allure: Теперь скажем Jenkins публиковать отчёт Allure после прогона тестов. Плагин предоставил нам удобный шаг allure для Pipeline. Его можно вызывать в post-блоке этапа тестирования, чтобы отчёт генерировался даже если тесты упали (блок post { always { ... } } выполнится в любом случае). Давайте допишем наш Jenkinsfile:
```
pipeline {
    agent any 
    tools { maven "Maven 3.8.6" }
    stages {
        stage('Build') {
            steps {
                sh 'mvn clean package -DskipTests'
            }
        }
        stage('Test') {
            steps {
                sh 'mvn clean test'
            }
            post {
                // Генерируем Allure-отчет независимо от статуса тестов:
                always {
                    allure includeProperties: false, jdk: '', results: [[path: 'target/allure-results']]
                }
            }
        }
        // ... (Deploy stage добавим позже)
    }
}
```
Вот здесь и происходит магия. В секции post { always { ... } } мы вызываем шаг allure и указываем путь к результатам тестов. Плагин соберёт файлы из target/allure-results и сформирует красивый отчет. Обратите внимание, мы используем формат declarative pipeline – шаг allure можно вызывать прямо, без обёртки script { }, как declarative-степ. Мы передаём ему параметры: includeProperties: false, jdk: '' (не используем отдельную JDK для генерации отчёта), и самое главное – results: [[path: 'target/allure-results']]. Именно здесь мы указываем папку с результатами (у нас она стандартная, совпадает с настройкой по умолчанию allure.results.directory). В классических Freestyle-job Jenkins вы бы просто добавили шаг «Allure Report» и прописали путь к результатам (например, target/allure-results) вручную, а в Pipeline мы делаем то же самое кодом.
Просмотр Allure-отчёта: Сохраняем Jenkinsfile в репозитории, обновляем Jenkins job (или просто снова запускаем сборку). После выполнения pipeline, на странице билда Jenkins появится раздел Allure Report (обычно внизу страницы или слева в меню, в зависимости от версии плагина). Нажмите на него – Jenkins откроет сгенерированный Allure-отчёт прямо в браузере. Там вы увидите статистику: сколько тестов прошло, упало, были ли проигнорированы; красивые графики распределения результатов, список тест-кейсов с шагами, аттачменты (например, логи или скриншоты, если вы их добавляли в тестах) и многое другое. Благодаря плагину, не нужно вручную запускать allure serve – отчёт уже доступен на Jenkins-сервере.

Теперь каждый запуск тестов будет сопровождаться не только консольным логом, но и наглядным HTML-отчётом. Команде тестировщиков (да и разработчиков) это значительно облегчит анализ результатов. Например, упавшие тесты будут видны с причинами падения, а успешные – сгруппированы по suit'ам, с информацией о длительности.

⚠️ Важно: убедитесь, что этап генерации отчёта Allure всегда выполняется, даже если тесты упали. Именно поэтому мы использовали post { always { ... } } внутри шага тестов. Это означает: запустить Allure даже при FAILURE на этапе Test. В противном случае, при падении теста вы остались бы без отчёта для диагностики. К счастью, Jenkins Pipeline позволяет задать такие условия явно.

Интеграция с GitHub: автоматический запуск через вебхуки

Мы настроили Jenkins job и Pipeline, но запускать его пока нужно вручную. В идеале, сборка должна стартовать автоматически при каждом пуше в репозиторий (continuous integration же!). Как это сделать? Использовать webhook из GitHub к Jenkins.

Webhook – это HTTP-колбек, который GitHub (или другой Git-сервис) отправляет при определённых событиях, например, после успешного пуша в репозиторий. Мы можем настроить GitHub так, чтобы он сообщал нашему Jenkins: «Новый коммит! Срочно запусти сборку!».

Что нужно настроить:

В Jenkins (триггер): Откройте конфигурацию вашего Pipeline job (через Изменить конфигурацию). Найдите раздел Build Triggers (Триггеры сборки). Поставьте галочку GitHub hook trigger for GITScm polling – эта опция говорит Jenkins ждать сигналов (хуков) от GitHub. Фактически, Jenkins создает специальный URL для вебхуков.
В GitHub (вебхук): Зайдите на страницу вашего репозитория GitHub -> Settings -> Webhooks -> Add Webhook. В поле Payload URL укажите адрес вашего Jenkins сервера, добавив путь /github-webhook/. Формат такой: http://<адрес-jenkins>/github-webhook/. Если Jenkins работает локально и недоступен напрямую из интернета, этот шаг может потребовать дополнительного решения (например, использовать ngrok для проксирования вебхука к локальному Jenkins). Для Content type выберите application/json. В списке событий вы можете оставить «Just the push event» – этого достаточно, чтобы реагировать на новые коммиты. Сохраните вебхук.
Проверка: Сделайте тестовый коммит в ваш репозиторий. GitHub отправит POST-запрос на указанный URL. Jenkins (при корректной настройке) должен получить этот запрос и поставить ваш Pipeline в очередь сборок. Если всё хорошо, вы увидите, что сразу после пуша начался новый билд.

Теперь у нас реально CI: разработчик пушит изменения – автоматически бегут тесты. Если что-то падает, Jenkins может оповестить (например, через email или в мессенджер, но это уже тема для отдельной статьи).

Совет: Плагин GitHub Integration позволяет Jenkins не только принимать вебхуки, но и, например, отправлять статус обратно на GitHub. Вы, наверное, видели зеленые галочки или красные крестики возле коммитов/PR на GitHub – Jenkins умеет их ставить, сообщая, прошла сборка или нет. Для этого убедитесь, что в конфигурации Jenkins (Manage Jenkins -> Configure System -> GitHub) добавлен сервер GitHub и привязаны креденшлы токена, а в Job’е включена опция GitHub project (с URL репозитория). Тогда Jenkins при каждом выполнении будет обновлять статус сборки в GitHub. Очень удобно: прямо в pull request видно, прошли ли тесты.

Если вебхуки по каким-то причинам недоступны (например, Jenkins развернут внутри закрытой сети), можно использовать альтернативу – Poll SCM. Это менее оптимально, но работает: Jenkins будет опрашивать репозиторий по расписанию (например, каждую минуту) на наличие новых коммитов. Для этого в настройках Job’а включите Poll SCM и задайте крон-образное выражение расписания, например: H/5 * * * * (раз в ~5 минут). Но лучше, конечно, настроить вебхук – мгновенная реакция и минимум лишней нагрузки.

Пример полного Jenkinsfile (Pipeline)

Мы рассмотрели все основные компоненты. Давайте сведём их вместе. Ниже — полный пример Jenkinsfile, который можно сразу применять (не забудьте внести в него свой URL репозитория, если потребуется, и настроить Allure/плагины как описано выше):

pipeline {
    agent any
    tools { 
        maven 'Maven 3.8.6'        // Имя Maven из глобальной конфигурации Jenkins
    }
    stages {
        stage('Build') {
            steps {
                echo 'Building the project...'
                sh 'mvn clean package -DskipTests'
            }
        }
        stage('Test') {
            steps {
                echo 'Running tests...'
                sh 'mvn clean test'
            }
            post {
                always {
                    // Генерация Allure-отчета (после тестов, даже если некоторые упали):
                    allure includeProperties: false, jdk: '', results: [[path: 'target/allure-results']]
                }
            }
        }
        stage('Deploy') {
            when { 
                // Выполнять деплой только если предыдущие стадии успешны:
                expression { currentBuild.currentResult == 'SUCCESS' }
            }
            steps {
                echo 'Deploying application...'
                // Пример: деплой артефакта на удалённый сервер или репозиторий
                sh 'mvn clean deploy'
                // В реальности тут могут быть команды SCP, SSH или вызов API деплоя
            }
        }
    }
}

Что делает этот конвейер:

Стадия Build собирает проект, пропуская тесты (чтобы не дублировать запуск).
Стадия Test запускает тесты. В блоке post { always { ... } } сразу публикуется Allure-отчёт по итогам тестирования. Даже если тесты упадут, отчёт все равно будет сформирован, и вы сможете его посмотреть.
Стадия Deploy выполнится только если предыдущие прошли успешно (мы явно добавили условие when на SUCCESS, хотя по умолчанию declarative pipeline и так не пойдёт дальше при ошибке). Здесь происходит условный деплой: в примере мы вызываем mvn deploy (предполагая, что pom.xml настроен на деплой артефакта, скажем, в Nexus или артфактори). В вашем случае деплой может означать что угодно: копирование сборки на сервер, раскатка Docker-контейнера, развертывание на Tomcat, вызов облачного API и т.п. Все эти шаги можно автоматизировать в Jenkins (существуют плагины для SCP, SSH, Kubernetes deployment и др., либо можно просто выполнять shell-скрипты). Вы можете усложнить логику: например, деплоить только для мастер-ветки, или делать стадию Staging и Production с ручным подтверждением (input step). Pipeline DSL очень гибкий – позволяет реализовать практически любой сценарий.

После добавления Jenkinsfile в репозиторий и настройки webhook, ваш Pipeline станет полностью автоматическим. Представьте: разработчик пушит изменение на GitHub, Jenkins тут же запускает сборку, прогоняет API-тесты, формирует Allure-отчёт. Если всё зелёное – сразу выполняется деплой (например, на тестовый стенд или даже в прод, если вы достаточно смелы). Всё это без участия человека – чудеса автоматизации!

Заключение

Мы прошли весь путь от установки локального Jenkins до развёртывания приложения после успешных тестов. Подытожим ключевые моменты:

Jenkins локально: Запускаем jenkins.war, проходим первоначальную настройку (разблокировка, плагины).
Проект в Jenkins: Создаём Pipeline job, привязываем его к Git-репозиторию с тестами. Храним скрипт конвейера (Jenkinsfile) в репо для версионирования.
Pipeline (Jenkinsfile): Описываем стадии. Компилируем и запускаем Maven-тесты (TestNG + RestAssured) на этапе Test. Падение тестов останавливает pipeline, предотвращая деплой неисправного билда.
Allure-отчёты: Устанавливаем плагин, настраиваем Allure , подключаем Allure TestNG в проекте. После тестов генерируем отчёт командой allure в Pipeline. В итоге каждый запуск сопровождается наглядным HTML-отчётом с деталями тестов.
Git интеграция: Настраиваем webhook из GitHub на Jenkins, включаем триггер в job’е. Теперь pipeline запускается при каждом пуше. Jenkins может отправлять статус сборки обратно в GitHub (прошло/не прошло) для вашего удобства.
Деплой: Добавляем стадию деплоя, которая срабатывает только при успешных тестах. Что делать в этой стадии – зависит от ваших требований: можно загрузить артефакты на сервер, раскатить обновление, отправить уведомление о релизе и т.д. Мы показали простой пример с mvn deploy, но возможности не ограничены.

Надеемся, эта инструкция поможет вам настроить собственный CI/CD-процесс. Получив такую сборочную линию, вы будете уверены: каждый коммит проверен тестами, отчет лежит в Jenkins, а при успехе новая версия автоматически развернута. Разве не об этом мечтает каждый разработчик и тестировщик?

Успехов в автоматизации и зеленых вам билдов!

Комментарии (1)

Zulu0
07.06.2025 19:53
#28409948
Отличный текст. Я знаю чем займусь в ближайшее время. Давно хотел под forjego развернуть локально ci/cd