Интеграция с 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

Рекомендуемый метод установки плагина Allure Report — использовать функцию установки в один клик в 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. В ТестОпс нажмите на свой аватар и перейдите в Ваш профиль.

2. В разделе API tokens нажмите Создать.

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 — минимальный интервал (в секундах) перед загрузкой вновь созданного файла (чтобы избежать загрузки наполовину записанных файлов).
   Совет

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

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

6. Нажмите Сохранить.

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. Нажмите Сохранить.

---

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Примечание

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

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

2. В меню слева нажмите Токены доступа.

3. Нажмите Создать токен доступа.

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

   • Имя токена — имя, которое поможет вам распознать токен, например, “тестопс”.
   • Область разрешений — “Ограничить по проекту”.
   • Проект — проект TeamCity, для которого вы настраиваете интеграцию.
   • Разрешения — “Запуск сборки”, "Комментировать сборку".

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

6. Рядом со значением Токена нажмите значок Копировать, чтобы скопировать токен в буфер обмена.

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

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

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

2. В меню слева нажмите Настройки → Интеграции.

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

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

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

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

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

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

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

   Совет

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

   Нажмите Тестировать подключение. Через несколько мгновений должно появиться сообщение “Подключение установлено”.

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

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. В правом верхнем углу нажмите Редактировать конфигурацию.

3. В меню слева нажмите Параметры.

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

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

   • Имя — имя переменной.
   • Тип — “Переменная окружения”. Обратите внимание, что это автоматически добавляет префикс “env.” к Имени.
   • Значение — значение по умолчанию, которое должно использоваться, если не переопределено для конкретного запуска.

   Нажмите Сохранить, чтобы сохранить новый параметр.

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")
        }
    }
})