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

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

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

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

Примечание

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

Настройка интеграции и подключений с Jenkins

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

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

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

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

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

1.2. Подключите интеграцию с Jenkins на уровне инстанса ТестОпс

Перейдите в ваш инстанс ТестОпс → раздел Администрирование → Интеграции.
Нажмите Добавить интеграцию.
В списке доступных интеграций выберите Jenkins.
Заполните поля:
- Название подключения — введите название, которое поможет вам распознать интеграцию (например, Jenkins production).
- Endpoint — введите URL-адрес вашего инстанса Jenkins (например, https://jenkins.example.com/).
- Типы учетных данных — нажмите на выпадающий список и выберите один или несколько типов учетных данных Jenkins, которые будет поддерживать интеграция.
  Примечание
  Подробнее о поддерживаемых типах учетных данных см. Интеграции с внешними системами → Учетные данные внешних систем.
Если ваш инстанс Jenkins использует самоподписанный SSL-сертификат, уберите галочку напротив Проверка SSL-сертификата.
Если интеграция может работать с глобальными учетными данными Jenkins, в секции Глобальные учетные данные:
1. Введите имя пользователя нужной учетной записи в Jenkins (например, ivanivanov).
2. Введите API-токен, который вы сохранили на шаге 1.1.
При необходимости проверьте соединение с Jenkins, чтобы убедиться в корректности указанных данных.
Нажмите Добавить подключение.

В разделе Администрирование → Интеграции появится интеграция с Jenkins с одним автоматически созданным подключением.

1.3. Добавьте настроенное подключение к Jenkins в проект ТестОпс

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

В ТестОпс перейдите в раздел Администрирование → Интеграции.
В списке настроенных интеграций найдите и откройте интеграцию с Jenkins.
В списке настроенных подключений найдите и откройте ваше подключение к Jenkins.
Нажмите Добавить в проект.
В списке доступных проектов выберите нужный проект ТестОпс.
Если интеграция настроена для работы и с глобальными, и с проектными учетными данными Jenkins, в поле Тип учетных данных нажмите на выпадающий список и выберите вариант, который будет использоваться в проекте.
Если интеграция будет работать с проектными учетными данными Jenkins, в секции Проектные учетные данные:
1. Введите имя пользователя нужной учетной записи в Jenkins (например, ivanivanov).
2. Введите API-токен, который вы сохранили на шаге 1.1.
При необходимости проверьте соединение с Jenkins, чтобы убедиться в корректности указанных данных.
Нажмите Добавить в проект.

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

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

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

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

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

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

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

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

Внимание

Доступные версии плагина:

версия 4.2.1 — для Jenkins 2.532 и выше;
версия 4.1.0 — для Jenkins 2.504.2-2.531;
версия 4.0.2 — для Jenkins 2.361.1-2.504.1.

Более ранние версии Jenkins не поддерживаются.

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

Примечание

Интерфейс и ссылки в шагах, описанные ниже, относятся к плагину версии 4.2.1 — для Jenkins 2.532 и выше.

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

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

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

В Jenkins в правом верхнем углу нажмите иконку Manage Jenkins и перейдите в раздел System.
В секции ТестОпс нажмите Add ТестОпс Server → ТестОпс Server.
Заполните поля:
- ID — введите название, которое поможет вам распознать инстанс ТестОпс.
- Endpoint — введите URL-адрес вашего инстанса ТестОпс.
Рядом с полем Credentials нажмите + Add → Jenkins.
Заполните поля:
- Kind — нажмите на выпадающий список и выберите Secret text.
- Secret — введите API-токен, который вы сохранили на шаге 2.1.
- ID — введите название, которое поможет вам распознать API-токен (например, testops-credentials).
Нажмите Add.
В поле Credentials нажмите на выпадающий список и выберите название API-токена, которое вы указали на предыдущих шагах (например, testops-credentials).
Если ваш инстанс ТестОпс использует самоподписанный SSL-сертификат, уберите галочку напротив Enable certificate validation.
Нажмите Test connection. Если учетные данные верны, через несколько секунд появится сообщение «Successfully authorized as ⟨ваше имя пользователя в ТестОпс⟩».
Нажмите Advanced и заполните поля:
- Threads count — введите максимальное количество потоков для импорта файлов в ТестОпс.
- Batch size — введите максимальное количество файлов для импорта в ТестОпс за один раз (одним потоком).
- Results depth — введите количество уровней подкаталогов в директории с результатами тестов, которые будут сканироваться и импортироваться в ТестОпс. Значение 0 означает, что подкаталоги не будут импортированы.
- Process interval — введите минимальный интервал (в секундах) между отправкой пакетов файлов (одним потоком).
- Indexing interval — введите интервал (в секундах) между повторными сканированиями директории с результатами тестов.
- Delay interval — введите минимальный интервал (в секундах) перед импортом вновь созданного файла в ТестОпс. Эта настройка позволяет избежать импорта неполных файлов.
- Delay before upload finish — введите интервал (в секундах) после завершения джобы, по истечении которого система будет предполагать, что в директории больше не появятся новые файлы. Эта настройка позволяет избежать проблем с тестовыми раннерами, которые создают дополнительные процессы для записи файлов.
Нажмите Save.

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

Чтобы настроить импорт результатов тестов из Jenkins в ТестОпс, воспользуйтесь одним из способов в зависимости от типа вашей джобы Jenkins:

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

В Jenkins откройте джобу, из которой будут импортироваться результаты тестов в ТестОпс.
В сайдбаре слева перейдите в раздел Configure.
В секции Environment поставьте галочку напротив ТестОпс Upload.
Заполните поля:
- Server — нажмите на выпадающий список и выберите название инстанса ТестОпс, которое вы указали на шаге 2.3.
- Credentials — нажмите на выпадающий список и выберите название API-токена, которое вы указали на шаге 2.3.
- Project — нажмите на выпадающий список и выберите название проекта ТестОпс, в который будут импортироваться результаты тестов.
- Launch name — введите шаблон для названий запусков в ТестОпс. Вы можете использовать любые переменные окружения Jenkins (см. полный список переменных по URL-адресу https://<ваш домен Jenkins>/env-vars.html).
- Launch tags — введите список тегов (через запятую), которые будут присвоены запускам в ТестОпс.
Нажмите Add results → Results.
В поле Path введите путь к директории с результатами тестов (например, build/allure-results).
Примечание
В поле Path не поддерживаются подстановочные символы и шаблоны.
Совет
Если у вас есть несколько шагов сборки, которые генерируют результаты тестов в несколько директорий, нажмите Add results → Results, чтобы указать больше путей.
Нажмите Advanced и при необходимости настройте дополнительные параметры:
- Silent Mode — поставьте галочку, чтобы ошибка соединения при попытке импортировать результаты тестов не считалась ошибкой джобы.
  Совет
  Мы рекомендуем использовать этот параметр только в случае, если у вас есть другие средства для просмотра результатов тестов (например, если у вас дополнительно установлен плагин от Allure Report для Jenkins).
- Index Existing Files — поставьте галочку, чтобы плагин импортировал все файлы, найденные в целевой директории, даже если они не были обновлены во время последнего запуска.
Нажмите Save.

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

В Jenkins откройте джобу, настроенную для импорта результатов тестов в ТестОпс.
В сайдбаре слева нажмите Build Now.
Под сайдбаром слева нажмите на название запущенной сборки, чтобы открыть ее карточку, и дождитесь завершения сборки.
В сайдбаре слева или в карточке сборки найдите ссылку ТестОпс Report на запуск в ТестОпс.
Перейдите по ссылке в ТестОпс и откройте результаты одного из тестов.
В строке под названием теста найдите название сборки Jenkins, из которой импортированы результаты этого теста.
Нажмите на название сборки Jenkins, чтобы открыть сборку и проверить корректность связи между Jenkins и ТестОпс.

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

Перейдите в ваш проект ТестОпс → раздел Джобы.
В списке будет отображаться новая джоба, автоматически добавленная во время запуска на шаге 2.5.
Напротив добавленной джобы нажмите ⋯ → Настроить.
Заполните поля:
- Название — введите название, которое поможет вам распознать джобу.
- Сервер сборки — нажмите на выпадающий список и выберите название подключения к Jenkins, которое вы добавили на шаге 1.2.
- Джоба может быть использована для запуска тестов — поставьте галочку, чтобы пользователи могли запускать джобу из ТестОпс.
Нажмите Отправить.

3. Параметризируйте джобы в ТестОпс и Jenkins

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

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

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

Перейдите в ваш инстанс Jenkins.
Откройте джобу, настроенную для импорта результатов тестов в ТестОпс.
В сайдбаре слева перейдите в раздел Configure.
В cекции General поставьте галочку напротив This project is parameterized.
Для каждого параметра, который вы хотите добавить, нажмите Add Parameter → String Parameter и заполните поля:
- Name — введите название параметра.
- Default Value — введите значение по умолчанию, которое будет использоваться, если значение не переопределено для конкретного запуска.
Нажмите Save.

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

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

Перейдите в ваш инстанс ТестОпс → раздел Администрирование → Окружения.
Для каждой переменной, которую вы хотите добавить:
1. Нажмите + Создать.
2. Введите название глобальной переменной.
3. Нажмите Отправить.
Важно
Если в репозитории вашего проекта в Jenkins есть несколько веток, обязательно создайте глобальную переменную окружения Branch в ТестОпс и передайте ее в вашу джобу. Эта переменная укажет Jenkins, какую из веток нужно использовать.

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

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

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

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

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

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

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

groovy

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 будет удалена из джоб ТестОпс, которые относятся к интеграции и находятся в этом проекте:
- Иконки для запуска и обновления этих джоб в разделе Джобы останутся активными.
- ТестОпс не сможет запустить тесты из проекта на стороне Jenkins. После закрытия запуска результаты этих тестов получат статус «Неизвестный».
- Результаты запусков тестов из Jenkins не будут отправляться в проект ТестОпс.

Чтобы удалить подключение на уровне проекта:

Перейдите в ваш проект ТестОпс → раздел Настройки → Интеграции.
В списке настроенных интеграций найдите и откройте интеграцию с Jenkins.
Напротив нужного подключения к Jenkins нажмите ⋯ → Удалить → Да, удалить.

Подключение перестанет работать в вашем проекте.

Удаление подключения на уровне инстанса

Важно

Последствия удаления всех подключений из интеграции с Jenkins на уровне инстанса:

Подключения и интеграция с Jenkins будут полностью удалены.
Связь с инстансом Jenkins будет удалена из всех джоб ТестОпс, которые относятся к интеграции:
- Иконки для запуска и обновления этих джоб в разделе Джобы станут неактивными.
- Результаты запусков тестов из Jenkins не будут отправляться в инстанс ТестОпс.

Чтобы удалить подключение на уровне инстанса:

Перейдите в ваш инстанс ТестОпс → раздел Администрирование → Интеграции.
В списке настроенных интеграций найдите и откройте интеграцию с Jenkins.
В списке настроенных подключений откройте карточку нужного подключения и напротив названия каждого проекта нажмите ⋯ → Удалить из проекта → Да, удалить.
Нажмите Назад в интеграцию, чтобы вернуться к списку подключений.
Напротив нужного подключения к Jenkins нажмите ⋯ → Удалить → Да, удалить.

Подключение перестанет работать во всех проектах инстанса.

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

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

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

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

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

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

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

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

shell

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

После этой ошибки появится сообщение:

shell

Caused: hudson.remoting.ProxyException: <...>.jenkins.AllurePluginException: Could not stop uploader

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

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

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

Ошибка «java.lang.NoClassDefFoundError» при запуске withAllureUpload()

На Jenkins 2.579 и выше плагин версии 4.2.0 может завершиться ошибкой при инициализации шага withAllureUpload():

shell

java.lang.NoClassDefFoundError: org/apache/commons/lang/BooleanUtils
at PluginClassLoader for testops-jenkins//io.qameta.allure.jenkins.AllureLogger.<init>(AllureLogger.java:22)
at PluginClassLoader for testops-jenkins//io.qameta.allure.jenkins.WithAllureUploadStep$Execution.start(WithAllureUploadStep.java:154)

В этом случае команды внутри блока withAllureUpload() не выполняются, тесты не запускаются, а результаты не импортируются в ТестОпс.

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

Установка ТестОпс

Аутентификация

Проектные роли

Индивидуальный доступ

Групповой доступ

Глобальные роли

Приглашение в инстанс

Деактивация и активация учетной записи

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

Настройка интеграции и подключений с Jenkins ​

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

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

1.2. Подключите интеграцию с Jenkins на уровне инстанса ТестОпс ​

1.3. Добавьте настроенное подключение к Jenkins в проект ТестОпс ​

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

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

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

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

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

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

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

3. Параметризируйте джобы в ТестОпс и Jenkins ​

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

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

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

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

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

Удаление подключений и интеграции с Jenkins ​

Удаление подключения на уровне проекта ​

Удаление подключения на уровне инстанса ​

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

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

Ошибка «java.lang.UnsupportedClassVersionError» при импорте данных из Jenkins ​

Ошибка «java.lang.NoClassDefFoundError» при запуске withAllureUpload() ​

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

Настройка интеграции и подключений с Jenkins

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

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

1.2. Подключите интеграцию с Jenkins на уровне инстанса ТестОпс

1.3. Добавьте настроенное подключение к Jenkins в проект ТестОпс

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

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

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

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

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

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

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

3. Параметризируйте джобы в ТестОпс и Jenkins

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

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

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

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

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

Удаление подключений и интеграции с Jenkins

Удаление подключения на уровне проекта

Удаление подключения на уровне инстанса

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

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

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

Ошибка «java.lang.NoClassDefFoundError» при запуске withAllureUpload()