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

Примечание

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

• Администрирование — необходимы права администратора инстанса;
• Настройки в конкретном проекте — необходима роль владельца этого проекта.

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

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

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

Для интеграции ТестОпс с TeamCity используется плагин, который во время запуска тестов:

1. Регулярно сканирует новые файлы в директории результатов тестов (например, build/allure-results, см. How it works) в документации Allure Report.
2. Делает паузу перед загрузкой нового файла, чтобы исключить передачу неполных данных.
3. Загружает готовый файл на инстанс ТестОпс.

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

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

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

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

   1. Создайте токен в TeamCity.

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

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

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

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

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

   2. Установите плагин Allure TestOps в TeamCity.

      Примечание

      Для интеграции с TeamCity используется плагин Allure TestOps, который совместим с ТестОпс.

   3. Укажите параметры инстанса ТестОпс в TeamCity, в том числе созданный API-токен из ТестОпс.

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

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

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

Важно

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

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

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

1.1. Создайте токен в TeamCity

Примечание

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

1. В TeamCity нажмите на ваш аватар и перейдите в раздел Profile.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

     На вкладке basic введите имя пользователя и пароль учетной записи в TeamCity.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

1. В TeamCity перейдите в раздел Administration → Plugins и нажмите Browse plugins repository.

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

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

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

   Это активирует возможность установки плагина из JetBrains Marketplace напрямую через ваш браузер.

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

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

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

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

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

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

1. Посетите страницу плагина Allure TestOps в 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.3. Укажите параметры инстанса ТестОпс в 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.4. Измените конфигурацию сборки в TeamCity

Примечание

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

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

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

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

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

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

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

   • Allure Server — название инстанса, который вы добавили на шаге 2.3.
   • 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.

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

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

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

Чтобы создать новую джобу вручную:

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

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

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

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

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

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

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

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

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

Важно

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

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

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

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

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

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

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

   • Name — название переменной.
   • Kind — Environment variable. Обратите внимание, что это автоматически добавляет префикс env. к названию переменной.
   • Value — значение по умолчанию, которое должно использоваться, если не указано для конкретного запуска.

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

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

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

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

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

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

   

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

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

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

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

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

   

3.4. Загрузите параметры в джобу ТестОпс

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

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

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

   

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

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

   

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

Справочник по 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")
        }
    }
})

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

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

Важно

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

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

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

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

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

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

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

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

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

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

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

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