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

Интеграция с Jenkins позволяет:

• автоматически передавать результаты тестов из сборки (запуска джобы) Jenkins в ТестОпс с помощью плагина;
• запускать джобу Jenkins из интерфейса ТестОпс через запуск джобы ТестОпс;
• синхронизировать статус запуска джобы сразу в обеих системах — ТестОпс и Jenkins.

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

Примечание

Чтобы настроить или удалить любую интеграцию ТестОпс с внешней системой, необходимы права администратора инстанса ТестОпс и, как правило, права администратора инстанса внешней системы.

Настройка интеграции

Чтобы настроить интеграцию с Jenkins:

1. Настройте связь от ТестОпс к Jenkins:

   1. Создайте API-токен в Jenkins.

   2. На уровне инстанса ТестОпс добавьте интеграцию с Jenkins, указав:

      • название интеграции;
      • URL-адрес Jenkins.

   3. На уровне инстанса или проекта ТестОпс включите добавленную интеграцию для проекта, указав созданный API-токен из Jenkins.

2. Настройте связь от Jenkins к ТестОпс:

   1. Создайте API-токен в ТестОпс.
   2. Установите плагин ТестОпс в Jenkins.
   3. Укажите параметры инстанса ТестОпс в Jenkins, в том числе созданный API-токен из ТестОпс.
   4. Настройте джобу в Jenkins для загрузки результатов тестов в ТестОпс.
   5. Запустите и проверьте джобу в Jenkins.
   6. Настройте созданную джобу в ТестОпс.

3. Параметризируйте джобы Jenkins (если необходимо).

1. Настройте связь от ТестОпс к Jenkins

1.1. Создайте API-токен в Jenkins

1. Перейдите в ваш инстанс Jenkins.

2. Наведите курсор на ваш аватар и перейдите в раздел Security.

3. В секции API Token нажмите Add new token.

4. Введите название токена, которое поможет вам распознать интеграцию (например, Токен для ТестОпс).

5. Нажмите Generate.

6. В появившемся окне нажмите иконку Copy token, чтобы скопировать токен в буфер обмена.

   Cохраните токен в безопасном месте, он понадобится для настройки интеграции в проекте ТестОпс.

7. Нажмите Done.

1.2. Добавьте интеграцию с Jenkins в ТестОпс

1. Перейдите в ваш инстанс ТестОпс.

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

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

4. В списке доступных интеграций выберите Jenkins.

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

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

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

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

1.3. Включите интеграцию для проекта ТестОпс

Чтобы включить интеграцию в нужном проекте ТестОпс, воспользуйтесь одним из способов:

1. В ТестОпс перейдите в раздел Администрирование → Интеграции.

2. В списке настроенных интеграций найдите и откройте вашу интеграцию с Jenkins.

3. Перейдите на вкладку Проекты.

4. Справа от поля поиска нажмите +.

5. В поле Проект нажмите на выпадающий список и выберите нужный проект ТестОпс.

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

   • Имя пользователя — введите имя пользователя вашей учетной записи в Jenkins (например, ivanivanov).
   • API-токен — введите токен, который вы сохранили на шаге 1.1.

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

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

2. Настройте связь от Jenkins к ТестОпс

Выполните шаги ниже, чтобы настроить вторую часть двусторонней связи: отправку статусов сборок и результатов тестов из Jenkins в ТестОпс.

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

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

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

3. Введите название токена, которое поможет вам распознать интеграцию (например, Токен для Jenkins).

4. Нажмите Создать.

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

5. Нажмите иконку Копировать, чтобы скопировать токен в буфер обмена.

   Cохраните токен в безопасном месте, он понадобится для настройки интеграции в Jenkins.

6. Нажмите Готово.

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

Вы можете установить плагин ТестОпс для Jenkins двумя способами:

• указать URL-адрес плагина в настройках Jenkins (рекомендуемый способ);
• загрузить HPI-файл с плагином в Jenkins вручную (если у инстанса Jenkins нет доступа к интернету).

Выбранный метод установки не влияет на функциональность плагина.

Внимание

Начиная с 15 февраля 2024 года доступны две версии плагина:

• рекомендуемая версия 4 — для Jenkins 2.361.1 и выше на базе Java 17;
• устаревшая версия 3 — для Jenkins ниже 2.361.1 на базе Java 11.

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

Примечание

Интерфейс и ссылки в шагах, описанные ниже, относятся к плагину версии 4 — для Jenkins 2.361.1 и выше на базе Java 17.

Плагин версии 3 устанавливается и настраивается аналогичным способом.

1. Перейдите на страницу qatools-jenkins-plugin и скопируйте URL-адрес HPI-файла.
2. Перейдите в ваш инстанс Jenkins.
3. В правом верхнем углу нажмите иконку Manage Jenkins.
4. Перейдите в раздел Plugins.
5. В сайдбаре слева перейдите в раздел Advanced settings.
6. В секции Deploy Plugin → URL введите URL-адрес HPI-файла.
7. Нажмите Deploy.
8. Дождитесь установки плагина.

2.3. Укажите параметры инстанса ТестОпс в Jenkins

1. В Jenkins в правом верхнем углу нажмите иконку Manage Jenkins.

2. Перейдите в раздел System.

3. В секции ТестОпс нажмите Add ТестОпс Server → ТестОпс Server.

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

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

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

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

   • Kind — нажмите на выпадающий список и выберите Secret text.
   • Secret — введите API-токен, который вы сохранили на шаге 2.1.
   • ID — введите название, которое поможет вам распознать токен (например, testops-credentials).

7. Нажмите Add.

8. В поле Credentials нажмите на выпадающий список и выберите название токена, которое вы указали на предыдущих шагах (например, testops-credentials).

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

10. Нажмите Test connection. Если учетные данные верны, через несколько секунд появится сообщение «Successfully authorized as ⟨ваше имя пользователя в ТестОпс⟩».

11. Нажмите Advanced и заполните поля:

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

12. Нажмите Save.

2.4 Настройте джобу в Jenkins для загрузки результатов тестов в ТестОпс

Настроить загрузку результатов тестов из Jenkins в ТестОпс можно для двух типов джоб — freestyle-проекта и пайплайна.

2.4a Настройте freestyle-проект в Jenkins

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

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

2. В сайдбаре слева перейдите в раздел Configure.

3. В секции Environment поставьте галочку напротив ТестОпс Upload.

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

   • Server — нажмите на выпадающий список и выберите название инстанса ТестОпс, которое вы указали на шаге 2.3.
   • Credentials — нажмите на выпадающий список и выберите название токена, которое вы указали на шаге 2.3.
   • Project — нажмите на выпадающий список и выберите название проекта ТестОпс, в который будут загружаться результаты тестов.
   • Launch name — введите шаблон для названий запусков в ТестОпс. Вы можете использовать любые переменные окружения Jenkins (см. полный список переменных по URL-адресу https://<ваш домен Jenkins>/env-vars.html).
   • Launch tags — введите список тегов (через запятую), которые будут присвоены запускам в ТестОпс.

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

6. В поле Path введите путь к директории с результатами тестов (например, build/allure-results).

   Примечание

   В поле Path не поддерживаются подстановочные символы и шаблоны.

   Совет

   Если у вас есть несколько шагов сборки, которые генерируют результаты тестов в несколько директорий, нажмите Add results → Results, чтобы указать больше путей.

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

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

     Совет

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

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

8. Нажмите Save.

2.4b Настройте пайплайн в Jenkins

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

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

2. В сайдбаре слева перейдите в раздел Pipeline Syntax.

3. В поле Sample Step нажмите на выпадающий список и выберите withAllureUpload: With ТестОпс Upload.

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

   • Server — нажмите на выпадающий список и выберите название инстанса ТестОпс, которое вы указали на шаге 2.3.
   • Credentials — нажмите на выпадающий список и выберите название токена, которое вы указали на шаге 2.3.
   • Project — нажмите на выпадающий список и выберите название проекта ТестОпс, в который будут загружаться результаты тестов.
   • Launch name — введите шаблон для названий запусков в ТестОпс. Вы можете использовать любые переменные окружения Jenkins (см. полный список переменных по URL-адресу https://<ваш домен Jenkins>/env-vars.html).
   • Launch tags — введите список тегов (через запятую), которые будут присвоены запускам в ТестОпс.

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

6. В поле Path введите путь к директории с результатами тестов (например, build/allure-results).

   Примечание

   В поле Path не поддерживаются подстановочные символы и шаблоны.

   Совет

   Если у вас есть несколько шагов сборки, которые генерируют результаты тестов в несколько директорий, нажмите Add results → Results, чтобы указать больше путей.

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

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

     Совет

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

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

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

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

   Пример фрагмента кода

   withAllureUpload(credentialsId: 'testops-credentials', name: '${JOB_NAME} - #${BUILD_NUMBER}', projectId: '1', results: [[path: 'build/allure-results']], serverId: 'TestOps production', tags: '') {
    // some block
   }

9. Нажмите иконку Copy, чтобы скопировать фрагмент кода в буфер обмена.

   Cохраните фрагмент кода в безопасном месте, он понадобится для дальнейшей настройки скрипта пайплайна.

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

    • скрипт в текстовом поле из раздела Configure → Pipeline;
    • Jenkinsfile в системе управления версиями проекта.

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

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

    Например:

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

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

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

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

2. В сайдбаре слева нажмите Build Now.

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

4. В сайдбаре слева или в карточке сборки найдите ссылку ТестОпс Report на запуск в ТестОпс.

   

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

6. В карточке результата теста в левом нижнем углу найдите ссылку на сборку Jenkins.

   

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

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

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

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

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

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

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

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

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

3. Параметризируйте джобы

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

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

3.1. Укажите параметры в джобе Jenkins

1. Перейдите в ваш инстанс Jenkins.

2. Откройте джобу, настроенную для загрузки результатов тестов в ТестОпс.

3. В сайдбаре слева перейдите в раздел Configure.

4. В cекции General поставьте галочку напротив This project is parameterized.

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

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

   

6. Нажмите Save.

3.2. Добавьте глобальные переменные окружения в ТестОпс

Перед тем как использовать значения параметров из джобы Jenkins, создайте глобальные переменные окружения на уровне инстанса ТестОпс, которые будут хранить эти данные:

1. Перейдите в ваш инстанс ТестОпс.

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

3. Для каждой переменной, которую вы хотите добавить:

   1. Нажмите + Создать.
   2. Введите глобальное название переменной.
   3. Нажмите Отправить.

   

   Важно

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

3.3. Сопоставьте параметры джобы Jenkins с глобальными переменными окружения в ТестОпс

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

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

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

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

   

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

1. В ТестОпс перейдите в раздел Джобы.

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

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

   

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

4. Для каждого параметра, который вы хотите использовать, в секции Параметры → Переменная окружения нажмите на выпадающий список и выберите соответствующую глобальную переменную окружения в ТестОпс из шага 3.2.

   

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

Примеры настроенных пайплайнов Jenkins

Как упоминалось выше, интеграция с Jenkins настраивается для двух типов джоб — freestyle-проекта и пайплайна.

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

pipeline {
    agent any

    stages {
        stage('git pull') {
            steps {
                git branch: '${BRANCH_NAME}', url: 'https://github.com/ivanivanov/testops-example.git'
            }
        }
        stage('Running tests') {
            steps {
                catchError(buildResult: 'SUCCESS', message: 'There are some troubles with withAllureUpload', stageResult: 'UNSTABLE') {
                    withAllureUpload(indexExistingFiles: true, name: '${JOB_NAME} - #${BUILD_NUMBER}', projectId: '2199', results: [[path: 'build/allure-results']], serverId: 'TestOps production', silent: true,  tags: 'demo,${BRANCH_NAME},RELEASE:1-2-3') {
                    sh 'chmod +x ./gradlew'
                    sh './gradlew clean test'
                    sh 'printenv | grep ALLURE_'
                    sh 'printenv'
                    }

                }
                
            }
        }
    }
}

Удаление интеграции

Вы можете удалить интеграцию с Jenkins двумя способами — на уровне всего инстанса ТестОпс (через раздел Администрирование) или на уровне отдельного проекта (через настройки проекта).

Важно

Последствия удаления интеграции:

• Удаление на уровне инстанса — связь с инстансом Jenkins будет удалена из всех джоб ТестОпс, которые относятся к интеграции:

  • Иконки для запуска и обновления этих джоб в разделе Джобы станут неактивными.
  • Результаты запусков тестов из Jenkins не будут отправляться в инстанс ТестОпс.

• Удаление на уровне проекта — связь с инстансом Jenkins будет удалена из джобы ТестОпс, которая относится к интеграции и находится в этом проекте:

  • Иконки для запуска и обновления этой джобы в разделе Джобы останутся активными.
  • ТестОпс не сможет запустить тесты из проекта на стороне Jenkins. После закрытия запуска результаты этих тестов получат статус «Неизвестный».
  • Результаты запусков тестов из Jenkins не будут отправляться в проект ТестОпс.

1. В ТестОпс перейдите в раздел Администрирование → Интеграции.

2. В списке настроенных интеграций найдите и откройте вашу интеграцию с Jenkins.

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

   Если интеграция подключена к проектам, удалите ее из них. Для этого напротив названия каждого проекта нажмите иконку корзины → Удалять.

4. Перейдите на вкладку Конфигурация.

5. Нажмите Удалить интеграцию.

6. Нажмите Удалить.

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

Ошибка «Could not create session for closed launch» при загрузке данных из Jenkins

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

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

Чтобы исправить ошибку:

1. Переименуйте джобу Jenkins, выбрав название, которое не использовали ранее.
2. Повторите загрузку данных.

Ошибка «java.lang.UnsupportedClassVersionError» при загрузке данных из Jenkins

При загрузке результатов тестов плагин ТестОпс может завершиться ошибкой:

java.lang.UnsupportedClassVersionError: <...>/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: <...>.jenkins.AllurePluginException: Could not stop uploader

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

Чтобы исправить ошибку:

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

2. Убедитесь, что вы используете версию Jenkins выше 2.361.1.

3. Убедитесь, что на агентах и хосте Jenkins совпадают версии Java.

   Важно

   Если версии агента и хоста Jenkins отличаются, плагин ТестОпс не сможет запуститься на агенте и работа с агентами будет недоступна.