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

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

Как и все другие интеграции CI для ТестОпс, это включает двустороннюю связь:

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

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

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

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

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

Чтобы GitLab отправлял статусы пайплайнов и результаты тестов в ТестОпс, вам нужно создать токен аутентификации в ТестОпс, добавить токен в GitLab и изменить сам пайплайн.

Затем запустите и проверьте пайплайн, чтобы убедиться, что все работает.

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

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

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

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

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

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

1.2. Укажите токен в GitLab

1. В GitLab откройте проект и перейдите в Settings → CI/CD.

2. В разделе Variables нажмите Add variable.

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

   • Type — Variable;
   • Visibility — Masked;
   • Key — ALLURE_TOKEN;
   • Value — API-токен, который вы получили на шаге 1.1.

4. Нажмите Add variable, чтобы сохранить настройки.

1.3. Измените пайплайн

Чтобы внести изменения в пайплайн, отредактируйте файл .gitlab-ci.yml в вашем репозитории GitLab. Вы можете сделать это либо в локальной директории, либо в редакторе GitLab (CI/CD → Editor в старой навигации, Build → Pipeline editor в новой навигации).

Для каждой джобы, которая запускает тесты, выполните следующие действия:

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

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

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

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

   • ALLURE_ENDPOINT — URL-адрес сервера ТестОпс.
   • ALLURE_PROJECT_ID — ID проекта ТестОпс.
   • ALLURE_RESULTS — путь к директории с результатами тестов, например, build/allure-results. Если в вашем проекте несколько директорий с результатами тестов, вы можете разделить их запятыми или использовать шаблон с подстановочными символами, например, modules/*/build/allure-results.

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

Примечание

Пример

Предположим, у нас есть проект на Java с файлом .gitlab-ci.yml такого вида:

test:
  stage: test
  image: gradle
  script:
    - gradle clean test

С интеграцией ТестОпс файл будет выглядеть примерно так:

test:
  stage: test
  image: gradle
  variables:
    ALLURE_ENDPOINT: https://testops.example.com
    ALLURE_PROJECT_ID: 1
    ALLURE_RESULTS: build/allure-results
  before_script:
    - curl -fsSL https://github.com/allure-framework/allurectl/releases/latest/download/allurectl_linux_amd64 -o allurectl
    - chmod +x allurectl
  script:
    - ./allurectl watch -- gradle clean test

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

1. В GitLab откройте проект и перейдите к выполнению пайплайна, запущенного последним коммитом.

2. Если выполнение пайплайна еще не завершено, дождитесь его завершения.

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

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

   

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

   Внизу страницы должна быть ссылка на пайплайн GitLab. Убедитесь, что она присутствует и работает.

   

2. Включите запуск пайплайнов GitLab

На стороне ТестОпс интеграция с GitLab должна быть настроена на двух уровнях.

Сначала администратору нужно включить интеграцию с сервером GitLab, указав URL-адрес сервера.

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

2.1. Включите интеграцию с сервером GitLab в ТестОпс

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

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

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

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

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

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

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

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

2.2. Создайте токен в GitLab

1. В GitLab нажмите на ваш аватар и перейдите в Preferences.

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

3. Если форма создания токена не появилась, нажмите Add new token над списком токенов.

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

   • Token name — название, которое поможет вам распознать токен, например, Токен для ТестОпс.
   • Expiration date — любая дата в пределах года с текущей даты. После этой даты интеграция перестанет работать, и вам нужно будет создать новый токен для продолжения использования интеграции.
   • Select scopes — api и read_api.

5. Нажмите Create personal access token.

   Страница обновится, и вверху появится поле Your new personal access token. Нажмите значок Копировать рядом с ним.

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

Таким же образом вы можете использовать токен доступа к проекту (project access token), но имейте в виду, что этот токен позволяет работать только с одним проектом.

2.3. Добавьте токен в проект ТестОпс

1. Откройте ваш проект в ТестОпс.
2. Перейдите в раздел Настройки → Интеграции.
3. В разделе Доступные интеграции найдите интеграцию GitLab и нажмите Добавить интеграцию рядом с ней.
4. В появившемся окне укажите Токен, который вы получили на шаге 2.2.
5. Нажмите Проверить соединение. Если токен указан верно, через несколько секунд появится сообщение «Соединение установлено».
6. Нажмите Добавить интеграцию, чтобы сохранить настройки.

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

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

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

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

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

4. В появившемся окне отредактируйте поля:

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

   

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

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

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

В GitLab владельцу проекта нужно добавить переменные и их значения по умолчанию.

В ТестОпс администратору нужно объявить требуемые названия параметров глобально, затем владельцу проекта нужно настроить сопоставление параметров в настройках проекта и в настройках джобы.

Важно

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

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

Чтобы внести изменения в пайплайн, отредактируйте файл .gitlab-ci.yml в вашем репозитории GitLab. Вы можете сделать это либо в локальной директории, либо в редакторе GitLab (CI/CD → Editor в старой навигации, Build → Pipeline editor в новой навигации).

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

test:
  stage: test
  image: gradle
  variables:
    ALLURE_ENDPOINT: https://testops.example.com
    ALLURE_PROJECT_ID: 1
    ALLURE_RESULTS: build/allure-results
    PRODUCT_VERSION: "1.23"
    TESTS_BROWSER: chrome
  before_script:
    - curl -fsSL https://github.com/allure-framework/allurectl/releases/latest/download/allurectl_linux_amd64 -o allurectl
    - chmod +x allurectl
  script:
    - ./allurectl watch -- gradle clean test

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.1.
   • Значение — значение по умолчанию, такое же, как значение из шага 3.1.
   • Переменная окружения — глобальное название параметра из шага 3.2.

   

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