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

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

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

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

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

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

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

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

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

Установить с URL-адреса

1. Посетите каталог jenkins-plugin на dl.qatools.ru и найдите последнюю версию плагина. Скопируйте URL-адрес HPI-файла.

Внимание

Пожалуйста, учтите, что начиная с 15 февраля 2024 года существуют 2 версии плагина

• Плагин вер. 4 для Jenkins CI 2.361.1+, работающий на Java 17
• Плагин вер. 3 для Jenkins CI ранее 2.361.1, работающий на Java 11

Внимание

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

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

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

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

   На странице Download progress дождитесь, пока каждый статус не станет “Success”.

Установить с файла

1. Посетите каталог jenkins-plugin на dl.qatools.ru и найдите последнюю версию плагина. Сохраните 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 также нужно изменить, чтобы включить взаимодействие с сервером. Плагин поддерживает это как для проектов свободного стиля, так и для проектов пайплайнов.

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

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

1. В ТестОпс нажмите на ваш аватар и перейдите в Ваш профиль.
2. В разделе API-токены нажмите + Токен.
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 выберите ID сохраненных учетных данных, например, “allure-credentials”.

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

   Совет

   Проверьте, что все правильно

   Нажмите Test connection. Через несколько мгновений должно появиться сообщение “Successfully authorized as ⟨USERNAME⟩”.

8. Нажмите Advanced для дополнительных параметров:

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

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

2.3a. Изменить проект свободного стиля

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

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: 'ТестОпс production', tags: '') {
       // some block
   }

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

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

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

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

    Для декларативных пайплайнов

    Если вы используете синтаксис декларативного пайплайна, блок withAllureUpload() должен быть размещен внутри блока steps. Например:

    pipeline {
        agent any
    
        stages {
            stage('Build') {
                steps {
                    git 'https://github.com/eroshenkoam/allure-example.git'
                    withAllureUpload(name: '${JOB_NAME} - #${BUILD_NUMBER}', projectId: '1', results: [[path: 'build/allure-results']], serverId: 'Allure TestOps production', tags: '') {
                        sh './gradlew clean test'
                    }
                }
            }
        }
    }

    Для скриптовых пайплайнов

    Если вы используете синтаксис скриптового пайплайна, блок withAllureUpload() должен быть размещен внутри блока stage(). Например:

    node {
        stage('Build') {
            git 'https://github.com/eroshenkoam/allure-example.git'
            withAllureUpload(name: '${JOB_NAME} - #${BUILD_NUMBER}', projectId: '1', results: [[path: 'build/allure-results']], serverId: 'Allure TestOps production', tags: '') {
                sh './gradlew clean test'
            }
        }
    }

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 ТестОпс”), затем нажмите Generate.

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

   Этот токен понадобится вам на следующем шаге.

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

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

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

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

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

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

   Проверьте правильность учетных данных

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

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

3.4. Настройте задание в ТестОпс

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

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

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

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

4. В появившемся окне отредактируйте поля:

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

   

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

4. Параметризация заданий

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

В 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

Причина

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

Решение

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

Также проверьте версию вашего Jenkins CI.

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