Интеграция с Jenkins

Эта страница описывает, как настроить ТестОпс и Jenkins в проекте, который использует Jenkins для запуска тестов.

Как и все другие CI-интеграции в ТестОпс, это двусторонняя связь:

• Сборка Jenkins отправляет свой статус и результаты тестов в ТестОпс.
• ТестОпс использует API Jenkins для запуска новых пайплайнов, при необходимости передавая тест-план.

После остановки пайплайна соответствующий запуск в ТестОпс может быть закрыт вручную или автоматически в соответствии с политикой автоматического закрытия.

Чтобы добавить поддержку ТестОпс в ваш проект в Jenkins:

1. Установите плагин для Jenkins.
2. Включите отправку данных из Jenkins.
3. Включите запуск сборок Jenkins.
4. Параметризуйте джобы (если необходимо).

1. Установите плагин для Jenkins

Для установки плагина ТестОпс мы рекомендуем указать его URL-адрес в настройках Jenkins. Если ваш инстанс Jenkins не имеет доступа к интернету, вы можете загрузить HPI-файл плагина в Jenkins вручную. Выбранный метод установки не влияет на функциональность плагина.

Указание URL-адреса

1. Выберите последнюю версию плагина на странице jenkins-plugin и скопируйте URL-адрес HPI-файла.

   Внимание

   Обратите внимание, что начиная с 15 февраля 2024 года существует 2 версии плагина:

   • версия 4 для Jenkins 2.361.1 и выше, использующая Java 17;
   • версия 3 для Jenkins ниже 2.361.1, использующая Java 11.

   Если вы используете версию 4, то на стороне агента (раннера) Jenkins у вас должна быть установлена Java версии 17, иначе плагин не сможет запуститься и загрузка результатов не будет работать.

2. В Jenkins перейдите в Manage Jenkins → Manage Plugins → Advanced settings.

3. В разделе Deploy Plugin вставьте URL-адрес HPI-файла.

4. Нажмите Deploy, чтобы подтвердить установку плагина.

   На странице Download progress дождитесь статуса Success для каждого этапа.

Загрузка файла

1. Выберите последнюю версию плагина на странице jenkins-plugin и скачайте HPI-файл в локальную директорию на вашем устройстве.

2. В Jenkins перейдите в Manage Jenkins → Manage Plugins → Advanced settings.

3. В разделе Deploy Plugin нажмите Browse и выберите скачанный HPI-файл.

4. Нажмите Deploy, чтобы подтвердить установку плагина.

   На странице Download progress дождитесь статуса Success для каждого этапа.

2. Включите отправку данных из Jenkins

Этот раздел описывает вторую часть двусторонней связи: отправку статусов джоб и результатов тестов из Jenkins в ТестОпс. Для этого любому пользователю ТестОпс нужно создать токен аутентификации и добавить его в Jenkins, чтобы Jenkins мог выполнять действия с правами этого пользователя.

Саму джобу Jenkins также нужно изменить, чтобы включить взаимодействие с сервером. Плагин поддерживает это как для freestyle-проектов, так и для пайплайнов.

После настройки запустите и проверьте джобу, чтобы убедиться, что все работает.

2.1. Создайте токен в ТестОпс

1. В ТестОпс нажмите на ваш аватар и перейдите в API-токены.

2. Нажмите + Токен.

3. Придумайте название для токена (например, «Токен для Jenkins») и нажмите Создать.

   ТестОпс сгенерирует токен и отобразит его в модальном окне.

4. Нажмите значок Копировать, чтобы скопировать токен в буфер обмена. Этот токен понадобится вам на следующем шаге.

2.2. Укажите сервер и токен в Jenkins

1. В Jenkins перейдите в Manage Jenkins → System.

2. В разделе Allure нажмите Add Allure Server → Allure Server.

3. Заполните поля:

   • ID — название, которое поможет вам распознать сервер ТестОпс.
   • Endpoint — URL-адрес сервера ТестОпс.

4. Рядом с полем Credentials нажмите Add → Jenkins.

5. В появившемся окне заполните поля:

   • Kind — Secret text.
   • Secret — API-токен, который вы получили на шаге 2.1.
   • ID — название, которое поможет вам распознать токен, например, “allure-credentials”.

   Нажмите Add, чтобы закрыть окно.

6. В выпадающем списке Credentials выберите название токена (“allure-credentials” из прошлого шага).

7. Если ваш сервер ТестОпс использует самоподписанный SSL-сертификат, снимите галочку Enable certificate validation. В противном случае оставьте его установленным.

8. Нажмите Test connection. Если учетные данные верны, через несколько секунд появится сообщение "Successfully authorized as ⟨USERNAME⟩".

9. Нажмите Advanced, чтобы настроить дополнительные параметры:

   • Threads count — максимальное количество потоков для загрузки файлов на сервер.
   • Batch size — максимальное количество файлов для загрузки на сервер за раз (одним потоком).
   • Results depth — количество уровней подкаталогов в директории с результатами тестов для сканирования и загрузки. "0" означает, что подкаталоги не будут загружены.
   • Process interval — минимальный интервал (в секундах) между отправкой пакетов файлов (одним потоком).
   • Indexing interval — интервал (в секундах) между сканированием директории с результатами тестов.
   • Delay interval — минимальный интервал (в секундах) перед загрузкой вновь созданного файла (чтобы избежать загрузки наполовину записанных файлов).
   • Delay before upload finish — интервал (в секундах) после завершения джобы перед предположением, что в директории не появятся другие файлы. Это необходимо для избежания проблем с некоторыми тестовыми раннерами, которые могут создавать новые процессы для записи файлов.

10. Нажмите Save внизу страницы.

2.3a. Измените freestyle-проект

В Jenkins freestyle-проект — это конфигурация сборки, для которой вы добавляете и редактируете шаги через веб-интерфейс. После установки плагина ТестОпс вы можете использовать тот же веб-интерфейс для включения и настройки автоматической загрузки результатов тестов на сервер ТестОпс.

1. В Jenkins выберите джобу, для которой вы хотите включить загрузку.

2. В меню слева нажмите Configure.

3. В разделе Build Environment поставьте галочку Allure: upload results.

4. Заполните поля:

   • Server — название сервера ТестОпс, которое вы указали на шаге 2.2.
   • Project — ID проекта ТестОпс.
   • Launch name — шаблон для именования запусков тестов. Вы можете использовать любые переменные окружения Jenkins (см. страницу /env-vars.html на вашем инстансе Jenkins для полного списка).
   • Launch tags — список тегов, которые должны быть присвоены запуску тестов (через запятую).

5. Нажмите Add results → Results.

6. В поле Results → Path укажите путь к директории с результатами тестов, например, “build/allure-results”.

   Совет

   Если у вас несколько шагов сборки, генерирующих результаты тестов в несколько директорий, используйте кнопку Add, чтобы указать больше путей.

   Плагин ТестОпс для Jenkins в настоящее время не поддерживает подстановочные символы и шаблоны в поле Path.

7. Нажмите Advanced, чтобы настроить дополнительные параметры джобы:

   • Silent mode — если установлено, ошибка соединения при попытке загрузить результаты тестов не будет считаться ошибкой джобы.

     Мы рекомендуем использовать этот режим только в случае, если у вас есть другие средства для просмотра результатов тестов (например, если у вас также установлен плагин Allure Report для Jenkins).

   • Index Existing Files — если установлено, ТестОпс загрузит все файлы, найденные в целевой директории, даже если они не были обновлены во время этого запуска.

8. Нажмите Save.

2.3b. Измените скрипт пайплайна Jenkins

Если вы храните джобу в скрипте пайплайна Jenkins, плагин ТестОпс добавит блок withAllureUpload() и веб-интерфейс для генерации фрагмента кода, который его использует.

1. В Jenkins выберите джобу, для которой вы хотите включить загрузку.

2. В меню слева нажмите Pipeline Syntax.

   Откроется интерфейс для генерации фрагментов кода для пайплайна Jenkins.

3. В выпадающем списке Sample Step выберите withAllureUpload: Allure: upload results.

4. Заполните поля:

   • Server — название сервера ТестОпс, которое вы указали на шаге 2.2.
   • Project — ID проекта ТестОпс.
   • Launch name — шаблон для именования запусков тестов. Вы можете использовать любые переменные окружения Jenkins (см. страницу /env-vars.html на вашем инстансе Jenkins для полного списка).
   • Launch tags — список тегов, которые должны быть присвоены запуску тестов (через запятую).

5. Нажмите Add results → Results.

6. В поле Results → Path укажите путь к директории с результатами тестирования, например, “build/allure-results”.

   Совет

   Если у вас несколько шагов сборки, генерирующих результаты тестов в несколько директорий, используйте кнопку Add, чтобы указать больше путей.

   Плагин ТестОпс для Jenkins в настоящее время не поддерживает подстановочные символы и шаблоны в поле Path.

7. Нажмите Advanced, чтобы настроить дополнительные параметры:

   • Silent mode — если установлено, ошибка соединения при попытке загрузить результаты тестов не будет считаться ошибкой джобы.

     Мы рекомендуем использовать этот режим только если у вас есть другие средства для просмотра результатов тестов (например, если у вас также установлен плагин Allure Report для Jenkins).

   • Index Existing Files — если установлено, ТестОпс загрузит все файлы, найденные в целевой директории, даже если они не были обновлены во время этого запуска.

8. Нажмите Generate Pipeline Script.

   В области под кнопкой появится фрагмент кода. Например:

   withAllureUpload(name: '${JOB_NAME} - #${BUILD_NUMBER}', projectId: '1', results: [[path: 'build/allure-results']], serverId: 'TestOps production', tags: '') {
       // блок кода
   }

9. Скопируйте сгенерированный фрагмент кода в буфер обмена для использования позже.

10. Откройте скрипт Groovy, который вы используете для проекта. Это может быть:

    • скрипт в текстовом поле в Configure → Pipeline;
    • Jenkinsfile в системе управления версиями проекта (см. официальную документацию).

11. Найдите команду (или набор команд), которая запускает тесты, и оберните их в блок withAllureUpload() из сгенерированного фрагмента.

12. Сохраните скрипт. В случае Jenkinsfile убедитесь, что изменения закомичены в репозиторий.

2.4. Запустите и проверьте джобу

1. В Jenkins выберите джобу, для которой вы настроили интеграцию с ТестОпс.

2. Нажмите Build Now.

   Дождитесь завершения сборки.

3. В Build History нажмите на последнюю сборку.

4. В меню и внизу страницы должны быть ссылки на отчет о тестировании в ТестОпс. Убедитесь, что они присутствуют и работают.

   

5. В отчете о тестировании в ТестОпс откройте результаты одного теста.

   Внизу страницы должна быть ссылка обратно на Jenkins. Убедитесь, что она присутствует и работает.

   

3. Включите запуск сборок Jenkins

Интеграция с сервером Jenkins должна быть настроена на двух уровнях.

Сначала администратору нужно указать URL-адрес сервера Jenkins.

Затем владельцу проекта нужно создать токен аутентификации в Jenkins, добавить его в ТестОпс и настроить джобу в ТестОпс.

3.1. Укажите сервер Jenkins в ТестОпс

1. Войдите в ТестОпс, используя учетную запись администратора.

2. Перейдите в раздел Администрирование → Интеграции.

3. Нажмите + Добавить интеграцию в правом верхнем углу страницы.

4. В появившемся окне выберите Jenkins.

5. Заполните поля:

   • Название — название, которое поможет вам распознать сервер Jenkins, например, Jenkins production.
   • Endpoint — URL-адрес сервера Jenkins, например, https://jenkins.example.com/.

6. Если ваш сервер Jenkins использует самоподписанный SSL-сертификат, поставьте галочку Disable certificate validation.

7. Нажмите Добавить интеграцию.

3.2. Создайте токен в Jenkins

1. В Jenkins нажмите на ваше имя пользователя и перейдите в Security.
2. В разделе API Token нажмите Add new Token.
3. Введите название (например, "Token for TestOps") и нажмите Generate.
4. В появившемся окне нажмите значок Копировать, чтобы скопировать токен в буфер обмена. Этот токен понадобится вам на следующем шаге.

3.3. Добавьте токен в проект ТестОпс

1. Откройте ваш проект в ТестОпс.

2. Перейдите в раздел Настройки → Интеграции.

3. В разделе Доступные интеграции найдите интеграцию Jenkins и нажмите Добавить интеграцию рядом с ней.

4. В появившемся окне заполните поля:

   • Имя пользователя — имя пользователя Jenkins (из профиля в Jenkins).
   • Токен — API-токен, который вы получили на шаге 3.2.

5. Нажмите Проверить соединение. Если учетные данные верны, через несколько секунд появится сообщение «Соединение установлено».

6. Нажмите Добавить интеграцию, чтобы сохранить настройки.

3.4. Настройте джобу в ТестОпс

1. Откройте ваш проект в ТестОпс.

2. Перейдите в раздел Джобы.

   На странице должна быть новая джоба, автоматически добавленная и настроенная во время запуска на шаге 2.4.

3. Нажмите ⋯ напротив джобы и выберите Настроить.

4. В появившемся окне заполните поля:

   • Название — название, которое поможет вам распознать джобу.
   • Сервер сборки — название интеграции, которую вы добавили на шаге 3.1.
   • Джоба может быть использована для запуска тестов — если установлено, пользователи смогут запускать эту джобу из ТестОпс.
   • Параметры — параметры, которые должны быть переданы в Jenkins через переменные окружения, см. Окружение.

   

5. Нажмите Отправить.

4. Параметризация джоб

Jenkins поддерживает параметризованные сборки. ТестОпс интегрирует эту функцию с собственной концепцией Окружения, которая позволяет вам как задавать параметры для новых джоб, так и видеть параметры, установленные для джоб, запущенных вне ТестОпс.

В Jenkins владельцу проекта нужно добавить переменные и их значения по умолчанию.

В ТестОпс администратору нужно глобально объявить требуемые названия для параметров. Затем владельцу проекта нужно настроить маппинг параметров в настройках проекта и в настройках джобы.

Важно

Если в репозитории вашего проекта есть несколько веток, обязательно создайте переменную окружения Branch в ТестОпс и передайте ее в вашу джобу. Это специальное имя укажет Jenkins, какую из веток нужно использовать.

4.1. Установите значения по умолчанию в Jenkins

1. В Jenkins выберите джобу, для которой вы настроили интеграцию с ТестОпс.

2. В меню слева нажмите Configure.

3. В разделе General поставьте галочку This project is parameterized.

4. Для каждого параметра, который вы хотите добавить, нажмите Add Parameter → String Parameter и заполните поля:

   • Name — имя переменной.
   • Default Value — значение по умолчанию, которое должно использоваться, если не переопределено для конкретного запуска.

   Нажмите Save, чтобы сохранить новые параметры.

   

4.2. Добавьте глобальные названия параметров в ТестОпс

1. Войдите в ТестОпс, используя учетную запись администратора.

2. Перейдите в раздел Администрирование → Окружения.

3. Для каждого параметра, который вы хотите добавить, нажмите + Создать, введите название параметра и нажмите Отправить.

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

   

4.3. Сопоставьте параметры с переменными окружения в ТестОпс

1. Откройте ваш проект в ТестОпс.

2. Перейдите в раздел Настройки → Окружение.

3. Для каждого параметра, который вы хотите использовать:

   1. Нажмите + Создать, если параметра нет в списке. Если параметр уже существует, нажмите значок Редактировать рядом с его названием.
   2. В поле Ключ укажите название переменной окружения из шага 4.1.
   3. В поле Переменная окружения выберите глобальное название параметра из шага 4.2.
   4. Нажмите Отправить.

   

4.4. Добавьте параметры в джобу ТестОпс

1. Откройте ваш проект в ТестОпс.

2. Перейдите в раздел Джобы.

3. Найдите джобу, которую вы хотите параметризовать. Нажмите Обновить рядом с ней.

   Имена параметров и их значения по умолчанию появятся в описании джобы.

   

4. Нажмите ⋯ справа от джобы и выберите Настроить.

   Появится окно настроек джобы, содержащее раздел Параметры.

5. Для каждого параметра, который вы хотите использовать, выберите соответствующую переменную окружения из шага 4.2.

   

6. Нажмите Отправить.

Устранение неполадок

Плагин Jenkins не может начать загрузку данных (сообщение "Could not create session for closed launch" в логах)

В некоторых случаях вы можете столкнуться с ситуацией, когда плагин Jenkins не может загрузить данные в ТестОпс и выводит сообщение "Could not create session for closed launch" в журнал.

Это связано с тем, что пайплайны Jenkins не имеют уникального идентификатора, кроме их названия. Следовательно, если вы удалите пайплайн и создадите новый с тем же названием, вы не сможете загрузить данные в ТестОпс, потому что это название уже использовалось.

Чтобы исправить это, переименуйте пайплайн, выбрав название, которое не использовали до этого.

Плагин Jenkins не может начать загрузку данных ("java.lang.UnsupportedClassVersionError")

Проблема

Возникли ошибки, вызвавшие проблемы с загрузкой результатов тестов:

java.lang.UnsupportedClassVersionError: io/qameta/allure/jenkins/callable/UploadResultsCallable has been compiled by a more recent version of
the Java Runtime (class file version 61.0), this version of the Java Runtime only recognizes class file versions up to 55.0

Далее следует:

Caused: hudson.remoting.ProxyException: io.qameta.allure.jenkins.AllurePluginException: Could not stop uploader

Причина

Это означает, что вы используете плагин ТестОпс, несовместимый с текущей версией Jenkins (Java, используемая Jenkins, новее, чем версия, используемая плагином ТестОпс).

Решение

Вам нужно обновить плагин до версии, совместимой с Java 17.

Также проверьте версию вашего Jenkins. Обязательно установите версию Java на агентах Jenkins такую же, как на хосте Jenkins. Для версий Jenkins выше 2.361.1 это Java 17. Если версии хоста и агента будут разными, код плагина не сможет быть запущен на агенте и работа с агентами будет невозможна.