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

В этой инструкции описывается, как настроить интеграцию ТестОпс с CircleCI в проекте, который использует CircleCI для запуска тестов.

Примечание

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

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

• Джоба в пайплайне CircleCI использует allurectl, чтобы отправить свой статус и результаты тестов в ТестОпс.
• ТестОпс использует API CircleCI для запуска новых пайплайнов, при необходимости передавая тест-план.

После остановки пайплайна соответствующий запуск в ТестОпс можно закрыть вручную или автоматически в соответствии с настройками автоматического закрытия.

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

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

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

   1. Создайте токен в CircleCI.
   2. Подключите интеграцию с CircleCI на уровне инстанса ТестОпс.
   3. Добавьте настроенное подключение к CircleCI в проект ТестОпс.

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

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

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

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

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

1. В CircleCI нажмите на ваш аватар в левом нижнем углу.

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

3. Нажмите Create New Token.

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

5. Нажмите Add API Token.

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

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

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

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

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

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

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

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

   • Название подключения — введите название, которое поможет вам распознать интеграцию (например, CircleCI production).

   • Endpoint — введите URL-адрес вашего инстанса CircleCI (например, https://circleci.com/).

   • Тип учетных данных — нажмите на выпадающий список и выберите тип учетных данных CircleCI, который будет поддерживать интеграция:

     • Все (глобальные и проектные) — интеграция может работать как с глобальными, так и с проектными учетными данными;
     • Только глобальные — интеграция может работать только с глобальными учетными данными;
     • Только проектные — интеграция может работать только с проектными учетными данными.

     Примечание

     Подробнее о поддерживаемых типах учетных данных см. Интеграции с внешними системами → Глобальные и проектные учетные данные

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

7. Если интеграция может работать с глобальными учетными данными CircleCI, в секции Глобальные учетные данные введите токен, который вы сохранили на шаге 1.1.

8. Нажмите Добавить подключение.

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

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

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

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

3. В списке настроенных подключений найдите и откройте ваше подключение к CircleCI.

4. Нажмите Добавить в проект.

5. В списке доступных проектов выберите нужный проект ТестОпс.

6. Если интеграция может работать и с глобальными, и с проектными учетными данными CircleCI, в поле Тип учетных данных нажмите на выпадающий список и выберите вариант, который будет использоваться в проекте:

   • Проектные — использовать проектные учетные данные для подключения к CircleCI;
   • Глобальные — использовать глобальные учетные данные для подключения к CircleCI.

7. Если интеграция будет работать с проектными учетными данными CircleCI, в секции Проектные учетные данные введите токен, который вы сохранили на шаге 1.1.

8. Нажмите Добавить в проект.

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

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

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

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

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

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

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

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

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

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

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

2.2. Укажите токен в CircleCI

1. В CircleCI откройте страницу проекта и нажмите Project Settings в правом верхнем углу.

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

3. Нажмите Add Environment Variable.

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

   • Name — введите ALLURE_TOKEN.
   • Value — введите API-токен, который вы сохранили на шаге 2.1.

5. Нажмите Add Environment Variable.

2.3. Измените джобу

Чтобы внести изменения в пайплайн, перейдите в ваш репозиторий и внесите изменения в файл .circleci/config.yml:

1. Убедитесь, что параметр version имеет значение 2.1.

2. Добавьте или расширьте блок parameters. Он должен включать два необязательных строковых параметра: ALLURE_JOB_RUN_ID и ALLURE_USERNAME.

3. Для каждой джобы CircleCI, которая запускает тесты:

   1. В steps добавьте первый шаг, который загружает инструмент allurectl и делает его исполняемым.

      В приведенном ниже примере мы используем curl для загрузки файла. Если curl не включен в образ Docker, который вы используете для джобы, используйте wget или аналогичный инструмент.

      Вы также можете создать и использовать собственный образ Docker с allurectl.

   2. Добавьте или расширьте блок environment. Он должен включать следующие переменные:

      • ALLURE_ENDPOINT — URL-адрес инстанса ТестОпс.

      • ALLURE_PROJECT_ID — ID проекта ТестОпс.

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

        Если в вашем проекте несколько директорий с результатами тестов, вы можете разделить их запятыми или использовать шаблон с подстановочными символами (например, modules/*/build/allure-results).

      • ALLURE_JOB_RUN_ID — << pipeline.parameters.ALLURE_JOB_RUN_ID >>.

      • ALLURE_USERNAME — << pipeline.parameters.ALLURE_USERNAME >>.

   3. Оберните команду, которая запускает тесты, в команду ./allurectl watch.

Пример изменения джобы

Предположим, вы работаете с Java-проектом, в котором файл .circleci/config.yml выглядит следующим образом:

version: 2.1
workflows:
  test:
    jobs:
      - test
jobs:
  test:
    docker:
      - image: cimg/openjdk:17.0
    working_directory: ~/repo
    steps:
      - checkout
      - run:
          name: Run tests
          command: gradle clean test

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

version: 2.1
workflows:
  test:
    jobs:
      - test
parameters:
  ALLURE_JOB_RUN_ID:
    type: string
    default: ""
  ALLURE_USERNAME:
    type: string
    default: ""
jobs:
  test:
    docker:
      - image: cimg/openjdk:17.0
    working_directory: ~/repo
    environment:
      ALLURE_ENDPOINT: https://testops.example.com
      ALLURE_PROJECT_ID: 1
      ALLURE_RESULTS: build/allure-results
      ALLURE_JOB_RUN_ID: << pipeline.parameters.ALLURE_JOB_RUN_ID >>
      ALLURE_USERNAME: << pipeline.parameters.ALLURE_USERNAME >>
    steps:
      - checkout
      - run:
          name: Download allurectl
          command: curl -fsSL https://github.com/allure-framework/allurectl/releases/latest/download/allurectl_linux_amd64 -o allurectl && chmod +x allurectl
      - run:
          name: Run tests
          command: ./allurectl --insecure watch -- gradle clean test

2.4. Запустите и проверьте пайплайн

1. В CircleCI откройте проект, для которого вы настраиваете интеграцию.

2. Перейдите к запуску пайплайна, инициированному последним коммитом.

   Примечание

   Если у вас отключен автоматический запуск пайплайнов после коммитов, выполните запуск вручную.

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

4. В деталях выполнения пайплайна нажмите на шаг, который запускает тесты.

5. Ближе к концу лога найдите ссылку на запуск в ТестОпс.

   

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

7. В карточке результата теста в левом нижнем углу найдите ссылку на пайплайн CircleCI.

   

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

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

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

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

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

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

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

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

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

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

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

Важно

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

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

Чтобы внести изменения в пайплайн, отредактируйте .circleci/config.yml в вашем репозитории.

1. В глобальном блоке parameters объявите параметры и их значения по умолчанию.
2. В блоке environment оберните параметры в переменные окружения, чтобы инструмент allurectl мог получить к ним доступ.

Например:

version: 2.1
workflows:
  test:
    jobs:
      - test
parameters:
  ALLURE_JOB_RUN_ID:
    type: string
    default: ""
  ALLURE_USERNAME:
    type: string
    default: ""
  PRODUCT_VERSION:
    type: string
    default: "1.23"
  TESTS_BROWSER:
    type: string
    default: chrome
jobs:
  test:
    docker:
      - image: cimg/openjdk:17.0
    working_directory: ~/repo
    environment:
      ALLURE_ENDPOINT: https://testops.example.com
      ALLURE_PROJECT_ID: 1
      ALLURE_RESULTS: build/allure-results
      ALLURE_JOB_RUN_ID: << pipeline.parameters.ALLURE_JOB_RUN_ID >>
      ALLURE_USERNAME: << pipeline.parameters.ALLURE_USERNAME >>
      PRODUCT_VERSION: << pipeline.parameters.PRODUCT_VERSION >>
      TESTS_BROWSER: << pipeline.parameters.TESTS_BROWSER >>
    steps:
      - checkout
      - run:
          name: Download allurectl
          command: curl -fsSL https://github.com/allure-framework/allurectl/releases/latest/download/allurectl_linux_amd64 -o allurectl && chmod +x allurectl
      - run:
          name: Run tests
          command: ./allurectl --insecure watch -- gradle clean test

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

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

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

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

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

   

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

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

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

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

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

   

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

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

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

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

   • Название — введите _название переменной окружения из шага 3.1.
   • Значение — введите значение по умолчанию, такое же, как default из шага 3.1.
   • Переменная окружения — нажмите на выпадающий список и выберите глобальное название переменной в ТестОпс из шага 3.2.

   

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

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

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

Важно

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

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

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

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

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

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

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

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

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

4. Напротив нужного подключения к CircleCI нажмите ⋯ → Удалить → Да, удалить.