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

Интеграция ТестОпс с TeamCity позволяет настроить следующие связи:

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

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

Во время выполнения тестов плагин ТестОпс для TeamCity регулярно сканирует новые файлы в директории результатов тестов (например, build/allure-results, см. Allure Report → Как это работает). Для каждого нового файла плагин немного ждет (чтобы избежать загрузки наполовину записанных файлов), затем загружает файл на сервер ТестОпс. Таким образом ТестОпс получает результаты тестов как можно скорее и может показать частичные результаты запуска еще до завершения джобы.

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

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

Важно

В настоящее время плагин для TeamCity не поддерживает инстансы ТестОпс с самоподписанными сертификатами.

Перед настройкой интеграции, пожалуйста, убедитесь, что вы используете правильно подписанный сертификат или рассмотрите возможность сделать ТестОпс доступным вашему серверу TeamCity через нешифрованный HTTP.

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

Рекомендуемый метод установки плагина ТестОпс — использовать функцию установки в один клик в JetBrains Marketplace. Однако, если ваша конфигурация TeamCity не имеет доступа к интернету, вы можете установить плагин, загрузив ZIP-архив в TeamCity вручную. Выбранный метод установки не влияет на функциональность плагина.

Установка из JetBrains Marketplace

1. В веб-интерфейсе TeamCity перейдите в Administration → Plugins и нажмите Browse plugins repository.

2. В появившемся окне нажмите Proceed.

   Ваш браузер будет перенаправлен на JetBrains Marketplace.

3. В уведомлении в правом нижнем углу нажмите Proceed.

   Это включит функцию установки в один клик для JetBrains Marketplace в вашем браузере.

4. Посетите страницу плагина ТестОпс в JetBrains Marketplace и нажмите Get → Install to ⟨hostname⟩.

5. Нажмите Install для подтверждения установки.

   Подождите, пока плагин будет загружен и установлен.

6. Нажмите Enable uploaded plugin.

7. В появившемся окне нажмите Enable для подтверждения активации плагина.

Установка из файла

1. Посетите страницу плагина ТестОпс в JetBrains Marketplace и нажмите Get → Download.

   Сохраните ZIP-архив в локальную директорию на вашем устройстве.

2. В веб-интерфейсе TeamCity перейдите в Administration → Plugins и нажмите Upload plugin zip.

3. В появившемся окне выберите ZIP-архив с вашего устройства.

4. Нажмите Upload plugin zip для подтверждения установки.

   Подождите, пока плагин будет загружен и установлен.

5. Нажмите Enable uploaded plugin.

6. В появившемся окне нажмите Enable для подтверждения активации плагина.

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

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

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

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

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

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

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

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

2.2. Укажите параметры сервера в TeamCity

Примечание

Для проекта на Kotlin DSL см. Справочник по Kotlin DSL ниже.

1. На главной странице TeamCity перейдите на страницу вашего проекта.

2. В правом верхнем углу нажмите Edit project.

3. В меню слева нажмите Allure Servers.

   (Если ссылка не видна, нажмите Show all, чтобы раскрыть ее.)

4. Нажмите Add new server.

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

   • Name — название, которое поможет вам распознать сервер ТестОпс.
   • URL — URL-адрес сервера ТестОпс.
   • Token — API-токен, который вы получили на шаге 2.1.
   • Threads count — максимальное количество потоков для загрузки файлов на сервер.
   • Batch size — максимальное количество файлов для загрузки на сервер за один раз (одним потоком).
   • Results depth — количество уровней подкаталогов в директории результатов тестов для сканирования и загрузки. «0» означает, что подкаталоги не будут загружены.
   • Process interval — минимальный интервал (в секундах) между отправками наборов файлов (одним потоком).
   • Indexing interval — интервал (в секундах) между сканированиями директории результатов тестов.
   • Delay interval — минимальный интервал (в секундах) перед загрузкой вновь созданного файла (чтобы избежать загрузки наполовину записанных файлов).

6. Нажмите Проверить соединение. Если учетные данные верны, через несколько секунд появится сообщение “Successfully authorized as ⟨USERNAME⟩”. Нажмите OK, чтобы закрыть сообщение.

7. Нажмите Save.

2.3. Измените конфигурацию сборки

Примечание

Для проекта на Kotlin DSL см. Справочник по Kotlin DSL ниже.

1. На главной странице TeamCity перейдите на страницу настроек вашей сборки.

2. В правом верхнем углу нажмите Edit configuration.

3. В меню слева нажмите Build Features.

4. Нажмите Add build features.

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

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

   • Allure Server — название сервера, который вы добавили на шаге 2.2.
   • Project ID — идентификатор проекта в ТестОпс.
   • Launch name — шаблон для именования запусков тестов. Здесь вы можете использовать предопределенные параметры сборки TeamCity.
   • Launch tags — список тегов, которые должны быть присвоены запуску тестов (через запятую).
   • Test Results Directories — путь к директории результатов тестов, например, build/allure-results. Если в вашем проекте несколько директорий с результатами тестов, вы можете разделить их запятыми или новыми строками, или использовать шаблон с подстановочными символами, например, modules/*/build/allure-results.
   • Index existing files — если не отмечено, плагин не будет загружать файлы, созданные до начала выполнения сборки. Это означает, что файлы, уже находящиеся в папке allure-results до начала работы плагина, будут проигнорированы.
   • Enable full log — если отмечено, плагин будет выводить больше деталей в журнал сборки. Такой журнал может быть полезен для устранения неполадок.

7. Нажмите Save.

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

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

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

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

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

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

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

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

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

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

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

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

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

3.2. Создайте токен доступа в TeamCity

Примечание

Пропустите этот шаг, если вы планируете использовать свое имя пользователя и пароль в качестве учетных данных на следующем шаге.

1. В TeamCity нажмите на ваш аватар и перейдите в Профиль.

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

3. Нажмите Create access token.

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

   • Token name — название, которое поможет вам распознать токен, например, «тестопс».
   • Permission scope — Limit per project
   • Project — проект TeamCity, для которого вы настраиваете интеграцию.
   • Permissions — Run build и Comment build.

5. Нажмите Create.

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

3.3. Добавьте учетные данные TeamCity в ТестОпс

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

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

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

   Появится окно для ввода учетных данных.

4. Введите учетные данные для подключения к серверу TeamCity. Есть два способа аутентификации:

   • Базовая аутентификация

     На вкладке Базовая введите Имя пользователя и Пароль пользователя TeamCity.

   • Аутентификация по токену

     На вкладке Токен введите Токен, который вы получили на шаге 3.2.

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

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

3.4. Добавьте новую джобу в ТестОпс

Самый простой и надежный способ создать джобу в ТестОпс — запустить сборку в TeamCity один раз, загрузить результаты тестов в ТестОпс и затем закрыть созданный запуск.

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

Создайте новую джобу вручную

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

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

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

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

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

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

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

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

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

Важно

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

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

1. На главной странице TeamCity перейдите на страницу настроек вашей сборки.

2. В правом верхнем углу нажмите Edit configuration.

3. В меню слева нажмите Parameters.

   (Если ссылка не видна, нажмите Show all, чтобы раскрыть ее.)

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

   • Name — название переменной.
   • Kind — Environment variable. Обратите внимание, что это автоматически добавляет префикс env. к названию переменной.
   • 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. Нажмите Отправить.

Справочник по Kotlin DSL

Если вы используете подход конфигурация как код и храните конфигурацию сборки в скрипте Kotlin DSL, вам нужно добавить настройки для интеграции с ТестОпс в ваш файл .teamcity/settings.kts.

Настройки на уровне проекта

Настройки на уровне проекта должны содержаться в блоке feature с указанным свойством type со значением io.qameta.allure.teamcity.AllureServerConfig. Все остальные настройки в блоке задаются с помощью функции param().

Поддерживаются следующие настройки:

• allure.server.config.id — уникальный идентификатор сервера. Рекомендуется использовать UUID.
• allure.server.config.name — название, которое поможет вам распознать сервер ТестОпс, например, TestOps production.
• allure.server.config.url — URL-адрес сервера ТестОпс, например, https://testops.example.com/.
• allure.server.config.token — API-токен, который вы получили на шаге 2.1.
• allure.server.config.threadsCount — максимальное количество потоков для загрузки файлов на сервер.
• allure.server.config.batchSize — максимальное количество файлов для загрузки на сервер за один раз (одним потоком).
• allure.server.config.maxDepth — количество уровней подкаталогов в директории результатов тестирования для сканирования и загрузки. «0» означает, что подкаталоги не будут загружены.
• allure.server.config.processInterval — минимальный интервал (в секундах) между отправкой наборов файлов (одним потоком).
• allure.server.config.indexInterval — интервал (в секундах) между сканированием директории с результатами тестирования.
• allure.server.config.delayInterval — минимальный интервал (в секундах) перед загрузкой вновь созданного файла (чтобы избежать загрузки наполовину записанных файлов).

Вот пример project с рабочей конфигурацией сервера ТестОпс:

project {
    vcsRoot(ExampleProject_VcsRoot)
    buildType(ExampleBuildConfiguration)
    features {
        feature {
            type = "io.qameta.allure.teamcity.AllureServerConfig"
            param("allure.server.config.id", "7040a01f-dadf-4d3b-b449-f8f227cb2f79")
            param("allure.server.config.name", "TestOps production")
            param("allure.server.config.url", "http://testops.example.com/")
            param("allure.server.config.token", "8d7e66eb-0bac-4dcf-9828-446a818f4d8c")
            param("allure.server.config.threadsCount", "5")
            param("allure.server.config.batchSize", "10")
            param("allure.server.config.maxDepth", "1")
            param("allure.server.config.processInterval", "2")
            param("allure.server.config.indexInterval", "1")
            param("allure.server.config.delayInterval", "5")
        }
    }
}

Настройки на уровне конфигурации сборки

Настройки на уровне конфигурации сборки должны содержаться в блоке feature с указанным свойством type со значением allure.serverBuildFeature. Все остальные настройки в блоке задаются с помощью функции param().

Поддерживаются следующие настройки:

• allure.server.id — идентификатор сервера (такой же, как allure.server.config.id в Настройках на уровне проекта).
• project.id — идентификатор проекта в ТестОпс.
• allure.server.launch.name — шаблон для именования запусков тестов. Здесь вы можете использовать предопределенные параметры сборки TeamCity.
• allure.server.launch.tags — список тегов, которые должны быть присвоены запуску тестов (через запятую).
• allure.result.directory — путь к директории результатов тестирования, например, build/allure-results. Если в вашем проекте несколько директорий с результатами тестирования, вы можете разделить их запятыми или новыми строками, или использовать шаблон с подстановочными символами, например, modules/*/build/allure-results.
• allure.indexExistingFiles — если отмечено, плагин не будет загружать файлы, которые не были созданы или изменены джобой.
• allure.debug.enable — если отмечено, плагин будет выводить больше деталей в журнал сборки. Такой журнал может быть полезен для устранения неполадок.

Вот пример BuildType с рабочими настройками:

object ExampleBuildConfiguration : BuildType({
    id = AbsoluteId("ExampleBuildConfiguration")
    name = "Example Build Configuration"
    vcs {
        root(DslContext.settingsRoot)
    }
    steps {
        gradle {
            tasks = "clean test"
        }
    }
    triggers {
        vcs {
        }
    }
    features {
        feature {
            type = "allure.serverBuildFeature"
            param("allure.server.id", "7040a01f-dadf-4d3b-b449-f8f227cb2f79")
            param("project.id", "1")
            param("allure.server.launch.name", "%env.TEAMCITY_BUILDCONF_NAME% - #%env.BUILD_NUMBER%")
            param("allure.server.launch.tags", "tests,teamcity")
            param("allure.result.directory", "build/allure-results")
            param("allure.indexExistingFiles", "true")
            param("allure.debug.enable", "true")
        }
    }
})