Перейти к основному содержимому

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

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

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

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

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

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

Чтобы включить поддержку Allure в вашем проекте GitHub:

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

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

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

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

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

  1. В ТестОпс нажмите на свой аватар и перейдите в Ваш профиль.

  2. В разделе API токены нажмите Создать.

  3. Введите Имя токена (например, “Токен для GitHub”), затем нажмите Отправить.

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

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

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

  1. В GitHub откройте проект и перейдите в его Настройки.

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

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

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

    • Key — “ALLURE_TOKEN”.
    • Value — API токен, который вы получили на шаге 1.1.

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

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

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

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

  1. Объявите входные данные (inputs) workflow для события workflow_dispatch:

    • ALLURE_JOB_RUN_ID
    • ALLURE_USERNAME

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

Совет

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

  1. Добавьте или расширьте блок 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. Перед запуском тестов добавьте два новых шага:

    1. Шаг, который загружает утилиту allurectl. Рекомендуется использовать действие allure-framework/setup-allurectl@v1 для этого.
    2. Есть еще один вариант загрузки и настройки allurectl без указанного действия. Мы предоставим оба примера ниже.

  2. Оберните команду, которая запускает тесты, в команду 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://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

действие настройки allurectl принимает следующие параметры:

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

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

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

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

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

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

    Ссылка на запуск находится в логе выполнения workflow.

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

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

    Ссылка на запуск workflow в GitHub находится в нижней части правой панели.

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

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

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

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

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

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

  2. Нажмите на свой аватар и перейдите в Администрирование → Интеграции.

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

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

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

    • Имя — имя, которое поможет вам распознать сервер GitHub, например, “GitHub production”.
    • Endpoint — базовый URL API GitHub. Для 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 будет генерировать: детализированный или классический (см. Управление вашими персональными токенами доступа в документации GitHub).

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

  1. В GitHub нажмите на свой аватар и перейдите в Настройки.

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

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

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

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

    • Имя токена — имя, которое поможет вам распознать токен, например, “Токен для ТестОпс”.
    • Срок действия — укажите, как долго токен должен быть действителен. После этой даты интеграция перестанет работать, и вам нужно будет создать новый токен для продолжения использования интеграции.

  6. В разделе Доступ к репозиторию нажмите Только выбранные репозитории. В появившемся выпадающем списке выберите репозиторий, содержащий workflows, которые вы хотите интегрировать.

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

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

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

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

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

  1. В ТестОпс перейдите на страницу проекта.

  2. В меню слева нажмите Настройки → Интеграции.

  3. В разделе Доступные интеграции найдите интеграцию с GitHub и нажмите Добавить интеграцию рядом с ней.

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

    Совет

    Проверьте правильность учетных данных

    Нажмите Тестировать соединение. Через несколько мгновений должно появиться сообщение “Соединение установлено”.

  5. Нажмите Добавить интеграцию, чтобы закрыть диалоговое окно и сохранить настройки.

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

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

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

Независимо от инструмента, используемого для загрузки (allurectl или плагин CI) результатов тестов в ТестОпс, весь контекст пайплайна (в случае GitHub – контекст 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"

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

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

Среди других переменных окружения workflow GitHub эти переменные окружения, которые мы только что создали, будут отправлены 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, например, TEST_BROWSER; параметр в скобках — это имя глобальной переменной окружения, которая будет предоставлять предложения для значений, например, Browser. А значение (в нашем примере это "opera") — это значение по умолчанию, которое мы собираемся передать в систему CI, если не указано другое значение.

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

  • Массовая операция с тест-кейсами Запуск
  • Выполнение тест-плана
  • Выполнение всей джобы (этот раздел)
Примечание

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

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

Кнопка “Добавить” находится внизу диалогового окна.

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

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

Значения параметров можно ввести или выбрать из списков.

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

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

Примеры​

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

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

  1. использование действия GH
    • действие загрузит allurectl
    • действие сгенерирует все необходимые параметры на основе контекста workflow или контекста, предоставленного из ТестОпс
    • действие предоставит параметры конфигурации, необходимые для загрузки результатов тестов
  2. использование скрипта внутри вашего workflow
    • этот вариант используется в случае, если GH не может быть использован из-за некоторых ограничений
    • скрипт загрузит allurectl
    • скрипт сгенерирует необходимые параметры на основе контекста workflow
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, когда вы пытаетесь запустить 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		В окне конфигурации джобы указана переменная, отсутствующая в "inputs".
Не будет работать, ошибка 422.
Отсутствует переменная TEST_BROWSER, обязательная для inputs в workflow_dispatch		В окне конфигурации джобы отсутствует обязательная переменная "TEST_BROWSER".

Решение​

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