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

Эта страница описывает, как настроить интеграцию ТестОпс с GitHub в проекте, который использует GitHub Actions для запуска тестов. Поддерживается как основной сервер GitHub (github.com), так и инстансы GitHub Enterprise Server.

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

• Одна джоба в ТестОпс соответствует одному workflow в GitHub.
• Один запуск в ТестОпс соответствует одному запуску workflow в GitHub.

Запуски workflow можно инициировать как из ТестОпс, так и с помощью самого GitHub. Обе стороны будут отображать статус запуска в своих интерфейсах.

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

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

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

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

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

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

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

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

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

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

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

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

1. В GitHub откройте проект и перейдите в его настройки (Settings).

2. В меню слева нажмите Secrets and variables → Actions.

3. Нажмите New repository secret.

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

   • Name — ALLURE_TOKEN.
   • Secret — API-токен, который вы получили на шаге 1.1.

5. Нажмите Add secret.

1.3. Измените workflows

Чтобы внести изменения в workflow, отредактируйте его YAML-файл в директории .github/workflows вашего репозитория GitHub. Вы можете сделать это локально или в веб-редакторе GitHub.

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

1. Добавьте следующие параметры в блок inputs для workflow_dispatch:

   • ALLURE_JOB_RUN_ID
   • ALLURE_USERNAME

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

   Примечание

   Вы также получите ошибку 422, если на стороне ТестОпс в параметрах джобы у вас будут указаны параметры (с левой стороны формы), которые отсутствуют в inputs для workflow_dispatch.

2. Добавьте или расширьте блок env workflow. Он должен включать:

   • ALLURE_ENDPOINT — URL-адрес сервера ТестОпс (например, https://testops.example.com/).
   • ALLURE_PROJECT_ID — ID проекта ТестОпс (например, 1). ID отображается перед названием проекта в интерфейсе ТестОпс и в адресной строке браузера.
   • ALLURE_TOKEN — ${{ secrets.ALLURE_TOKEN }}
   • ALLURE_JOB_RUN_ID — ${{ github.event.inputs.ALLURE_JOB_RUN_ID }}
   • ALLURE_RESULTS — путь к директории с результатами тестов (например, build/allure-results). Если в вашем проекте несколько директорий с результатами тестов, вы можете разделить их запятыми или использовать шаблон с подстановочными символами (например, modules/*/build/allure-results).

3. Добавьте шаг, загружающий утилиту allurectl, перед командой запуска тестов.

   Рекомендуем использовать для этого готовый GitHub Action allure-framework/setup-allurectl@v1.

   Вариант загрузки и настройки allurectl без использования GitHub Action описан в разделе Примеры.

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

   Если ваш сервер ТестОпс использует самоподписанный SSL-сертификат, используйте вместо этого allurectl --insecure watch.

   Пример

   Предположим, у нас есть проект на Java с файлом workflow, похожим на этот:

   name: Run tests
   
   on:
     push:
   
   jobs:
     all-tests:
       runs-on: ubuntu-latest
       steps:
         - uses: actions/checkout@v3
   
         - name: Set up JDK
           uses: actions/setup-java@v3
           with:
             distribution: oracle
             java-version: 17
   
         - name: Build with Gradle
           run: ./gradlew clean test

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

   name: Run tests
   
   on:
     push:
     workflow_dispatch:
       inputs:
         ALLURE_JOB_RUN_ID:
           description: ALLURE_JOB_RUN_ID service parameter. Leave blank.
         ALLURE_USERNAME:
           description: ALLURE_USERNAME service parameter. Leave blank.
   
   env:
     ALLURE_TOKEN: ${{ secrets.ALLURE_TOKEN }}
     ALLURE_JOB_RUN_ID: ${{ github.event.inputs.ALLURE_JOB_RUN_ID }}
     ALLURE_ENDPOINT: https://testops.example.com
     ALLURE_PROJECT_ID: 1
     ALLURE_RESULTS: build/allure-results
   
   jobs:
     all-tests:
       runs-on: ubuntu-latest
       steps:
         - uses: actions/checkout@v3
   
         - name: Set up JDK
           uses: actions/setup-java@v3
           with:
             distribution: oracle
             java-version: 17
   
         - name: Install allurectl
           uses: allure-framework/setup-allurectl@v1
   
         - name: Build with Gradle
           run: allurectl watch -- ./gradlew clean test

GitHub Action для allurectl принимает следующие параметры:

• allure-endpoint — Обязательный параметр. URL-адрес инстанса ТестОпс для загрузки результатов тестов.
• allure-token — Обязательный параметр. API-токен, использующийся для аутентификации allurectl на инстансе ТестОпс.
• allure-project-id — Обязательный параметр. ID проекта ТестОпс, в котором должен быть создан запуск с результатами тестов.
• allurectl-version — Необязательный параметр. Версия allurectl, которая будет использована для загрузки результатов тестов. Информацию о доступных релизах можно найти здесь.
• github-token — Необязательный параметр. Альтернативный GitHub-токен.

1.4. Запустите и проверьте workflow

1. В GitHub откройте проект и перейдите к запуску workflow, инициированному последним коммитом.

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

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

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

   

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

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

   

2. Включите запуск GitHub workflows

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

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

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

2.1. Укажите сервер GitHub в ТестОпс

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

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

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

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

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

   • Название — название, которое поможет вам распознать сервер GitHub (например, GitHub production).
   • Endpoint — базовый URL-адрес GitHub. Для github.com используйте https://github.com. Для GitHub Enterprise Server используйте URL-адрес вашего инстанса GitHub.
   • Endpoint for API calls — URL-адрес GitHub API. Для github.com используйте https://api.github.com. Для GitHub Enterprise Server используйте ⟨URL⟩/api/v3, где ⟨URL⟩ — URL-адрес вашего инстанса GitHub.

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

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

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

Чтобы иметь возможность запускать workflows, ТестОпс нужен персональный токен доступа, созданный сервером GitHub. Вы можете выбрать тип токена при его создании в GitHub: fine-grained или classic (см. Управление вашими персональными токенами доступа в документации GitHub).

Инструкции по созданию токена немного различаются в зависимости от его типа.

1. В GitHub нажмите на ваш аватар и перейдите в настройки (Settings).

2. В меню слева нажмите Developer settings.

3. Перейдите в Personal access tokens → Fine-grained tokens.

4. Нажмите Generate new token.

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

   • Token name — название, которое поможет вам распознать токен (например, Токен для ТестОпс).
   • Expiration — как долго токен должен быть действителен. После этой даты интеграция перестанет работать, и вам нужно будет создать новый токен для продолжения использования интеграции.

6. В разделе Repository access нажмите Only select repositories. В появившемся выпадающем списке выберите репозитории, содержащие workflow и задачи, которые вы планируете использовать.

7. В разделе Permissions нажмите Repository permissions. В появившемся списке разрешений найдите Actions и выберите Read and write рядом с ним.

   Если вы планируете добавлять ссылки на задачи GitHub Issues, дополнительно укажите для Issues разрешение Read and write.

8. Нажмите Generate token.

   Страница обновится, и новый токен станет временно видимым. Нажмите значок Копировать рядом с ним.

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

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

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

3. Параметризуйте workflow

GitHub использует блок inputs в YAML-файле для передачи параметров в контекст workflow. Чтобы параметризировать workflow, вам нужно добавить параметр в этот блок и указать его в поле env, чтобы использовать его как переменную окружения в тестах.

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

Независимо от инструмента, используемого для загрузки результатов тестов в ТестОпс (allurectl или CI-плагин), весь контекст workflow передается в ТестОпс и может быть использован для связи данных окружения с загруженными результатами тестов.

3.1. Объявите входные данные в workflow GitHub

Чтобы внести изменения в workflow, отредактируйте его YAML-файл в директории .github/workflows вашего репозитория GitHub. Вы можете сделать это локально или в веб-редакторе GitHub.

Добавьте входные данные для запуска workflow, их описания и значения по умолчанию в блок inputs. Например:

name: Run tests

on:
  workflow_dispatch:
    inputs:
      ALLURE_JOB_RUN_ID:
        description: ALLURE_JOB_RUN_ID service parameter. Leave blank.
      ALLURE_USERNAME:
        description: ALLURE_USERNAME service parameter. Leave blank.
      TESTS_BROWSER:
        description: Browser to use for tests
        default: chrome
      PRODUCT_VERSION:
        description: Product version
        default: "1.23"

Затем укажите эти значения в блоке env для передачи информации в ваши тесты через переменные окружения:

env:
  PRODUCT_VERSION: ${{ github.event.inputs.PRODUCT_VERSION }}
  TESTS_BROWSER: ${{ github.event.inputs.TESTS_BROWSER }}

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

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

Перед использованием значений переменных окружения из workflow GitHub (или из любого другого типа пайплайна) вам нужно создать глобальную переменную окружения, которая будет хранить эти данные.

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

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

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

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

   

3.3. Сопоставьте переменные окружения workflow с глобальными переменными окружения

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

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

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

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

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

   

3.4. Добавьте параметры к джобе

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

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

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

   Появится окно настроек джобы, содержащее раздел Параметры.

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

   • Название — имя переменной окружения (такое же, как Ключ из шага 3.3).
   • Значение — значение по умолчанию, которое должно использоваться, если не указано другое значение для конкретного запуска.
   • Переменная окружения — переменная окружения из шага 3.2.

   

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

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

3.5. Выполните workflow с определенными значениями переменных

На предыдущих шагах мы настроили джобу на стороне ТестОпс, которая теперь имеет все параметры, которые мы хотим передать в наш workflow в GitHub.

Настроенные параметры джобы — это те параметры, которые вы сможете передать в свой пайплайн при запуске CI-пайплайнов из интерфейса ТестОпс.

Параметр, отображаемый первым в списке, — это имя переменной окружения, которую мы собираемся объявить на стороне CI-сервера (например, TESTS_BROWSER). Параметр в скобках — это имя глобальной переменной окружения, которая будет предоставлять предложения для значений (например, Browser). А значение (в нашем примере это "chrome") — это значение по умолчанию, которое мы собираемся передать в CI-систему, если не указано другое значение.

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

• массовый запуск тест-кейсов;
• запуск тест-плана;
• запуск всей джобы (этот раздел).

Важно

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

Когда вы выполняете любое из указанных действий, вы увидите следующую форму для создания запуска.

Вам нужно нажать кнопку Добавить в разделе Окружение.

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

Затем вы можете изменить значения, которые хотите передать в CI-пайплайн.

Если вам нужно выполнить свой пайплайн несколько раз с разными наборами параметров, вам нужно создать новый набор переменных окружения, и ТестОпс запросит CI-сервер выполнить несколько пайплайнов с разными наборами параметров.

Примеры

Ниже представлен очень простой workflow, который вы можете использовать в качестве основы для вашего workflow в GitHub, чтобы попробовать запуск тестов и загрузку данных в ТестОпс. Он использует pytest в качестве примера и содержит все элементы, необходимые для загрузки результатов тестов в ТестОпс, и позволяет запускать workflow с стороны ТестОпс.

Как мы упоминали ранее, есть два способа добавить allurectl в workflow:

• Используя GitHub Action:

  1. Action скачивает allurectl.
  2. Action создает все нужные параметры на основе контекста workflow или контекста, предоставленного ТестОпс.
  3. Action предоставляет параметры конфигурации, необходимые для загрузки результатов тестов.

• Используя скрипт внутри вашего workflow (этот вариант используется в том случае, если GitHub не может быть использован из-за каких-то ограничений):

  1. Скрипт скачивает allurectl.
  2. Скрипт создает необходимые параметры на основе контекста workflow.

name: run-and-upload-to-testops

on:
  workflow_dispatch:
    inputs:
      GITHUB_TESTS_ENDPOINT:
        description: "System under test"
        required: true
        default: https://system.under.test
      GITHUB_TESTS_BROWSER:
        description: "Browser to be used in tests"
        required: true
        default: chrome
      ALLURE_JOB_RUN_ID:
        description: "ALLURE_JOB_RUN_ID is service parameter required for triggering workflows from TestOps. Leave blank."
        required: false
      ALLURE_USERNAME:
        description: "ALLURE_USERNAME service parameter. Leave blank"
        required: false

env:
  ALLURE_RESULTS: "allure-results"
  ALLURE_JOB_RUN_ID: ${{ github.event.inputs.ALLURE_JOB_RUN_ID }}

jobs:
  all-tests:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - uses: actions/setup-python@v4
        with:
          python-version: "3.11"
      - name: Install dependencies for pytest and allure framework integration
        run: |
          python -m pip install --upgrade pip
          pip install allure-pytest pytest
      - name: install and configure allurectl using GH Action
        uses: allure-framework/setup-allurectl@v1
        with:
          allure-endpoint: https://testops.example.com
          allure-token: ${{ secrets.ALLURE_TOKEN }}
          allure-project-id: 9999
      - name: Run pytest tests
        run: |
          allurectl watch -- pytest ./test --alluredir=${ALLURE_RESULTS} --capture=no || true
        env:
          GITHUB_TESTS_ENDPOINT: ${{ github.event.inputs.GITHUB_TESTS_ENDPOINT }}
          GITHUB_TESTS_BROWSER: ${{ github.event.inputs.GITHUB_TESTS_BROWSER }}
          GITHUB_TESTS_BRANCH: ${{ github.ref_name }}

Устранение неполадок

Ошибка 422 при запуске GitHub workflow через интерфейс ТестОпс

Причина

Обычно ошибка 422 возникает, когда вы пытаетесь запустить GitHub workflow с использованием workflow_dispatch, и параметры, определенные в inputs для workflow_dispatch, не совпадают с теми, которые передаются из ТестОпс.

Ожидаемая конфигурация

Как уже упоминалось в инструкции, существуют как минимум два обязательных параметра (с атрибутом required в значении false), которые должны быть указаны как inputs в разделе workflow_dispatch, чтобы ТестОпс мог запустить GitHub workflow:

• ALLURE_JOB_RUN_ID,
• ALLURE_USERNAME.

ТестОпс устанавливает эти параметры автоматически без участия пользователя. Оба параметра необходимы для успешного запуска GitHub workflow.

Если логика вашего пайплайна (GitHub workflow) требует дополнительных обязательных данных (например, название браузера или название системы для тестирования), эти параметры должны быть настроены в ТестОпс как параметры конфигурации джобы.

Пример

name: Integration of TestOps with GitHub
on:
  workflow_dispatch:
    inputs:
      ALLURE_JOB_RUN_ID:
        description: "ALLURE_JOB_RUN_ID service parameter. Leave blank."
        required: false
      ALLURE_USERNAME:
        description: "ALLURE_USERNAME service parameter. Leave blank"
        required: false
      TEST_BROWSER:
        description: "Browser for tests"
        required: true
        default: chrome
      TEST_ENDPOINT:
        description: "System under test"
        required: false
        default: https://staging.system.under.test

Для описанной конфигурации inputs в workflow_dispatch вам необходимо иметь следующие параметры в ТестОпс для созданной джобы:

1. Branch:

   • Связан с переменной окружения Branch (оба с заглавной буквы B).
   • Это специальная переменная, которая не указана явно в inputs, но ее значение передается в параметр ref при вызове API. Поэтому эта переменная обязательна (не может быть пропущена).

2. TEST_BROWSER:

   • Передает название браузера в workflow_dispatch.
   • Должен быть включен в параметры джобы, так как определен в workflow_dispatch как required: true.

3. TEST_ENDPOINT:

   • Может быть включен опционально как необязательный параметр джобы, так как определен в workflow_dispatch как required: false.

Примеры поведения GitHub при попытке запустить настроенную джобу

Результат запуска	Конфигурация джобы в ТестОпс
Будет работать корректно. Все параметры присутствуют в inputs
Будет работать корректно. Присутствует параметр TEST_BROWSER, обязательный для inputs в workflow_dispatch
Не будет работать, ошибка 422. Параметр RELEASE_ID отсутствует в inputs в workflow_dispatch
Не будет работать, ошибка 422. Отсутствует параметр TEST_BROWSER, обязательный для inputs в workflow_dispatch

Решение

Единственное возможное решение — синхронизировать параметры джобы, созданной в ТестОпс, с inputs в workflow_dispatch.