Перейти к основному содержимому

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

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

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

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

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

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

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

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

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

Установить с URL​

  1. Посетите каталог allure-testops-jenkins на dl.qameta.io и найдите последнюю версию плагина. Скопируйте URL HPI файла.
Внимание

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

Внимание

Если вы используете Плагин вер. 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. Посетите каталог allure-testops-jenkins на dl.qameta.io и найдите последнюю версию плагина. Сохраните 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, который вы используете для проекта. Это может быть:

  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'
                    }
                }
            }
        }
    }

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

2.4. Запустите и проверьте задание​

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

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

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

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

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

    Ссылка на запуск находится в логах выполнения пайплайна.

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

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

    Ссылка на пайплайн Jenkins находится в нижней части экрана.

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

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

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

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

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

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

  2. Нажмите на свой аватар и перейдите в Administration → Integrations.

  3. Нажмите Add integration в правом верхнем углу страницы.

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

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

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

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

  7. Нажмите Add integration.

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

  1. В Jenkins нажмите на свое имя пользователя и перейдите в Security.

  2. В разделе API Token нажмите Add new Token.

  3. Введите имя (например, “Token for ТестОпс”), затем нажмите Generate.

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

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

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

  1. В ТестОпс перейдите на страницу проекта.

  2. В меню слева нажмите Settings → Integrations.

  3. В разделе Available integrations найдите интеграцию Jenkins и нажмите Add integration рядом с ней.

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

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

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

    Нажмите Test connection. Через несколько секунд должно появиться сообщение “Connection established”.

  5. Нажмите Add integration, чтобы закрыть диалоговое окно и сохранить настройки.

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

  1. В ТестОпс перейдите на страницу проекта.

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

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

  3. Нажмите на меню с тремя точками задания, затем выберите Configure.

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

    • Name — имя, которое поможет вам распознать задание.
    • Build server — имя интеграции, которую вы добавили на шаге 3.1.
    • Job can be used to run tests — если установлено, пользователи смогут запускать это задание из ТестОпс.
    • Parameters — параметры, которые должны быть переданы в Jenkins через переменные окружения, см. Environment.

    Диалоговое окно позволяет настроить параметры джобы.

  5. Нажмите Submit.

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, чтобы сохранить новые параметры.

    Строковый параметр можно добавить в пайплайн Jenkins.

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

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

  2. Нажмите на свой аватар и перейдите в Administration → Environment.

  3. Для каждого имени параметра, которое вы хотите добавить, нажмите Create, введите имя нового параметра и нажмите Submit.

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

    Имена переменных окружения добавляются в настройках Администрации.

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

  1. В ТестОпс перейдите на страницу проекта.

  2. В меню слева нажмите Settings → Environment.

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

    1. Нажмите Create, если параметра нет в списке. В противном случае нажмите значок Edit рядом с его именем.

    2. В поле Mapping key укажите имя переменной окружения из шага 4.1.

    3. В поле Environment variable выберите глобальное имя параметра из шага 4.2.

    4. Нажмите Submit.

    Настройка отображения переменных окружения в настройках проекта.

4.4. Загрузите параметры в задание ТестОпс​

  1. В ТестОпс перейдите на страницу проекта.

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

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

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

    Список параметров находится под названием джобы.

  4. В меню с тремя точками задания нажмите Configure.

    Появится диалоговое окно настроек задания, содержащее раздел Parameters.

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

    В диалоговом окне можно указать несколько переменных окружения.

  6. Нажмите Submit.

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

Плагин 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. Если версии хоста и агента будут разными, код плагина не сможет быть запущен на агенте и работа с агентами будет невозможна.