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

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

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

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

Интеграция поддерживает как основной сервер GitHub (github.com), так и инстансы GitHub Enterprise Server.

Для правильной работы интеграции вам нужно будет изменить свои workflows так, чтобы они использовали Action setup-allurectl. Этот Action настроит утилиту allurectl для связи с ТестОпс. Перед запуском тестов утилита получает тест-план, т.е. набор тестов, которые нужно запустить. Затем, во время выполнения тестов, утилита регулярно сканирует новые файлы в директории результатов тестов (например, "build/allure-results" — см. Allure Report → Как это работает) и загружает их на сервер ТестОпс. Таким образом, ТестОпс получает результаты тестов как можно быстрее и может показать частичные результаты запуска еще до завершения работы.

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

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

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

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

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

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

В ТестОпс нажмите на ваш аватар и перейдите в API-токены.
Нажмите + Токен.
Придумайте название для токена (например, «Токен для GitHub») и нажмите Создать.
ТестОпс сгенерирует токен и отобразит его в модальном окне.
Нажмите значок Копировать, чтобы скопировать токен в буфер обмена. Этот токен понадобится вам на следующем шаге.

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

В GitHub откройте проект и перейдите в его настройки (Settings).
В меню слева нажмите Secrets and variables → Actions.
Нажмите New repository secret.
Заполните поля:
- Key — ALLURE_TOKEN.
- Value — API-токен, который вы получили на шаге 1.1.
Нажмите Add secret.

1.3. Измените workflows

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

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

Объявите входные данные (inputs) workflow для события workflow_dispatch:
- ALLURE_JOB_RUN_ID
- ALLURE_USERNAME
Эти переменные обязательны. Если переменные не будут добавлены, запуск workflows со стороны ТестОпс не будет работать и вы получите ошибку 422.
Совет
Вы также получите ошибку 422, если на стороне ТестОпс в параметрах джобы у вас будут указаны параметры (с левой стороны формы), которые отсутствуют в inputs для workflow_dispatch.
Добавьте или расширьте блок env workflow. Он должен включать:
- ALLURE_ENDPOINT — URL-адрес сервера ТестОпс, например, “https://demo.testops.cloud/”.
- 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”.
Перед запуском тестов добавьте два новых шага:
1. Шаг, который загружает утилиту allurectl. Рекомендуется для этого использовать Action allure-framework/setup-allurectl@v1.
2. Есть еще один вариант загрузки и настройки allurectl без этого Action. Мы предоставим оба примера ниже.

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

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

Примечание

Пример

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

yaml

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

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

yaml

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://demo.testops.cloud/
  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

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

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

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

В GitHub откройте проект и перейдите к запуску workflow, инициированному последним коммитом.
Если запуск еще не завершен, дождитесь его завершения.
В деталях запуска нажмите на джобу, которая запускает тесты.
Ближе к концу лога должна быть ссылка на отчет о тестировании в ТестОпс. Убедитесь, что она присутствует и работает.
В отчете о тестировании в ТестОпс откройте результаты одного теста.
В нижней части страницы должна быть ссылка обратно на запуск workflow в GitHub. Убедитесь, что она присутствует и работает.

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

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

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

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

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

Войдите в ТестОпс, используя учетную запись администратора.
Перейдите в раздел Администрирование → Интеграции.
Нажмите + Добавить интеграцию в правом верхнем углу страницы.
В появившемся окне выберите GitHub.
Заполните поля:
- Название — название, которое поможет вам распознать сервер 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.
Если вы используете GitHub Enterprise Server с самоподписанным SSL-сертификатом, поставьте галочку Отключить проверку сертификата.
Нажмите Добавить интеграцию.

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

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

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

В GitHub нажмите на ваш аватар и перейдите в настройки (Settings).
В меню слева нажмите Developer settings.
Перейдите в Personal access tokens → Fine-grained tokens.
Нажмите Generate new token.
Заполните поля:
- Token name — название, которое поможет вам распознать токен (например, Токен для ТестОпс).
- Expiration — как долго токен должен быть действителен. После этой даты интеграция перестанет работать, и вам нужно будет создать новый токен для продолжения использования интеграции.
В разделе Repository access нажмите Only select repositories. В появившемся выпадающем списке выберите репозитории, содержащие workflow и задачи, которые вы планируете использовать.
В разделе Permissions нажмите Repository permissions. В появившемся списке разрешений найдите Actions и выберите Read and write рядом с ним.
Если вы планируете добавлять ссылки на задачи GitHub Issues, дополнительно укажите для Issues разрешение Read and write.
Нажмите Generate token.
Страница обновится, и новый токен станет временно видимым. Нажмите значок Копировать рядом с ним.
Этот токен понадобится вам на следующем шаге.

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

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

3. Параметризация workflow

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

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

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

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

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

yaml

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"

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

yaml

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

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

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

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

Войдите в ТестОпс, используя учетную запись администратора.
Перейдите в раздел Администрирование → Окружение.
Для каждой переменной, которую вы хотите добавить:
1. Нажмите + Создать.
2. Введите название переменной.
3. Нажмите Отправить.

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

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

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

3.4. Добавление параметров к джобе

Откройте ваш проект в ТестОпс.
Перейдите в раздел Джобы.
Найдите джобу, которую вы хотите параметризовать. Нажмите ⋯ напротив джобы, затем выберите Настроить.
Появится окно настроек джобы, содержащее раздел Параметры.
Для каждой переменной, которую вы хотите добавить, нажмите Добавить и заполните поля:
- Название — имя переменной окружения (такое же, как Ключ из шага 3.3).
- Значение — значение по умолчанию, которое должно использоваться, если не указано другое значение для конкретного запуска.
- Переменная окружения — переменная окружения из шага 3.2.
Нажмите Отправить.

Обратите внимание, что рекомендуется устанавливать одинаковые значения по умолчанию как в ТестОпс, так и в 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.

yaml

name: run-and-upload-to-allure-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://demo.testops.cloud
          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) требует дополнительных обязательных данных (например, название браузера, название системы для тестирования), эти параметры должны быть настроены в ТестОпс как параметры конфигурации джобы.

Пример

yaml

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 вам необходимо иметь следующие параметры в ТестОпс для созданной джобы:

Branch:
- Связан с переменной окружения Branch (оба с заглавной буквы B).
- Это специальная переменная, которая не указана явно в inputs, но ее значение передается в параметр ref при вызове API. Поэтому эта переменная обязательна (не может быть пропущена).
TEST_BROWSER:
- Передает название браузера в workflow_dispatch.
- Должен быть включен в параметры джобы, так как определен в workflow_dispatch как required: true.
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.

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

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

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

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

1.3. Измените workflows ​

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

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

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

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

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

3. Параметризация workflow ​

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

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

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

3.4. Добавление параметров к джобе ​

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

Примеры ​

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

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

Причина ​

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

Пример ​

Решение ​

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

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

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

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

1.3. Измените workflows

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

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

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

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

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

3. Параметризация workflow

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

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

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

3.4. Добавление параметров к джобе

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

Примеры

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

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

Причина

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

Пример

Решение