Загрузка результатов тестов из Bitbucket

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

Важно

Для правильной работы с повторными запусками пайплайна Bitbucket в ТестОпс необходимо использовать версию allurectl 2.15.3.

Этот раздел охватывает следующие моменты интеграции:

1. Аутентификация пайплайна Bitbucket в ТестОпс для загрузки результатов тестов.
2. Простой пример пайплайна для понимания рабочих процессов с использованием allurectl.

Токен аутентификации

На стороне ТестОпс вам нужно создать API-токен. Этот токен будет использоваться allurectl для аутентификации на сервере ТестОпс.

Шаги

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

2. Нажмите на ваш аватар и перейдите в API-токены.

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

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

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

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

Загрузка результатов тестов из Bitbucket

Предварительные условия

Прочитайте руководство по allurectl. В большинстве случаев вам нужно использовать сценарий watch.

Совет

Мы рекомендуем использовать переменные окружения вместо переключателей командной строки для настройки allurectl. Этот подход позволяет иметь более понятную командную строку.

Переменные, необходимые для allurectl

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

• ALLURE_ENDPOINT (обязательно) — URL-адрес сервера ТестОпс, например, https://testops.example.com.
• ALLURE_TOKEN (обязательно) — API-токен, используемый для аутентификации.
• ALLURE_PROJECT_ID (обязательно) — cистемный ID проекта, в который вы собираетесь загружать результаты тестов.
• ALLURE_LAUNCH_NAME (обязательно) — шаблон названия запуска.
• ALLURE_RESULTS (обязательно) — папка, в которой allurectl должен искать результаты тестов.
• ALLURE_LAUNCH_TAGS (опционально) — теги, которые будут присвоены созданному запуску.

В следующих разделах мы объясним, где эти параметры могут быть использованы.

ALLURE_ENDPOINT в переменных рабочего пространства

Совет

Это один из вариантов указания переменной. Вы также можете указать эту переменную в описании пайплайна.

Обычно у вас есть только один инстанс ТестОпс. Это означает, что переменную ALLURE_ENDPOINT можно определить на более высоком уровне сущностей Bitbucket, например, в настройках рабочего пространства. Чтобы открыть их, используйте следующий путь и замените {ORGNAME} на название вашей организации: https://bitbucket.org/{ORGNAME}/workspace/settings/addon/admin/pipelines/account-variables.

Добавьте переменную ALLURE_ENDPOINT и ее значение в настройки Bitbucket.

Вы также можете использовать эту переменную вместе с другими в пайплайне (объяснено ниже).

Простой пайплайн

Логика пайплайна указывается по умолчанию в файле bitbucket-pipelines.yml. Для примера мы приведем самый простой пайплайн с использованием allurectl.

Пример пайплайна

image: gradle:8.10-jdk21

pipelines:
  custom:
    test:
      - variables:
          - name: ALLURE_LAUNCH_NAME
            default: ""
          - name: ALLURE_LAUNCH_TAGS
            default: "bitbucket, junit5"

      - step:
          name: Run tests
          script:
            - printenv
            - wget https://github.com/allure-framework/allurectl/releases/latest/download/allurectl_linux_amd64 -O ./allurectl
            - chmod +x ./allurectl
            - ALLURE_LAUNCH_NAME="${BITBUCKET_REPO_FULL_NAME} - $BITBUCKET_BUILD_NUMBER"
            - ./allurectl watch -- gradle --no-daemon clean test

Комментарии

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

custom:
  test:
    - variables:

Все переменные из примера должны быть добавлены в эту часть.

• ALLURE_LAUNCH_NAME
• ALLURE_LAUNCH_TAGS

Настройка пайплайна — добавление переменных

В предыдущих разделах мы говорили, что есть переменные, используемые allurectl для отправки результатов тестов на сервер ТестОпс.

• ALLURE_ENDPOINT
• ALLURE_TOKEN
• ALLURE_PROJECT_ID

Переменная ALLURE_ENDPOINT может быть добавлена либо в переменные рабочего пространства (см. выше), либо так же, как и другие две — на уровне конфигурации пайплайна.

Чтобы это сделать:

1. Выберите раздел Source.
2. Нажмите на bitbucket-pipelines.yml.
3. Нажмите Edit.
4. Снова нажмите Edit.
5. Вы увидите вкладку Configure и настройки Add variables, которые нужно развернуть.

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

• ALLURE_ENDPOINT — не secured;
• ALLURE_TOKEN — secured;
• ALLURE_PROJECT_ID — не secured;
• ALLURE_RESULTS — не secured.

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

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

Сбор информации о тестовой среде

Зачем?

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

• разные хосты для выполнения тестов, например, сервер QA, сервер staging и т. д.;
• разные браузеры для выполнения тестов для веб-интерфейса;
• ветка VCS для тестирования изменений перед их появлением в основной ветке.

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

Как?

Добавление переменных окружения в пайплайн на стороне Bitbucket

Переменные окружения могут быть добавлены в раздел, где мы добавили переменные, необходимые для allurectl:

custom:
  test:
    - variables:

Добавим информацию о версии продукта и о браузере, которые используются для тестов:

• PRODUCT_VERSION
• TESTS_BROWSER

Обновите пайплайн следующим образом

test:
  - variables:
      - name: ALLURE_LAUNCH_NAME
        default: ""
      - name: ALLURE_LAUNCH_TAGS
        default: "bitbucket, junit5"
      - name: PRODUCT_VERSION
        default: "1.23"
      - name: TESTS_BROWSER
        default: "chrome"

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

Пожалуйста, убедитесь, что переменная ALLURE_LAUNCH_NAME не оставлена пустой. Используйте следующий код в вашем пайплайне, чтобы задать значение переменной, которое затем будет передано в интерфейс ТестОпс:

- ALLURE_LAUNCH_NAME="${BITBUCKET_REPO_FULL_NAME} - $BITBUCKET_BUILD_NUMBER"

Настройка ТестОпс для обработки переменных окружения из Bitbucket

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

Настроим проект ТестОпс для обработки этой информации.

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

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

3. Для каждой переменной:

   1. Нажмите + Создать.
   2. Добавьте название переменной окружения в поле Ключ.
   3. Выберите глобальную переменную окружения из списка (эти переменные создаются администраторами ТестОпс).
   4. Нажмите Отправить.

4. Снова запустите джобу через интерфейс Bitbucket.

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

Запуск пайплайна из ТестОпс

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

Этот раздел охватывает следующие моменты:

1. Краткий обзор процесса интеграции.
2. Настройки джобы.

Подробно процесс настройки интеграций с внешними системами описан здесь.

Краткий обзор интеграции

1. Создайте учетные данные на внешней системе для использования API.
2. Добавьте необходимую интеграцию на глобальном уровне ТестОпс (нужны права администратора).
3. Добавьте необходимую интеграцию на уровне проекта и укажите учетные данные, которые вы получили на шаге 1.

Глобальный уровень

Важно

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

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

2. В правом верхнем углу нажмите + Добавить интеграцию.

3. Найдите Bitbucket.

4. Нажмите на логотип Bitbucket.

5. Укажите название для интеграции.

   Например, вы можете использовать URL-адрес сервера Bitbucket без http(s)://.

6. Укажите URL-адрес Bitbucket в поле Endpoint.

   Например, https://bitbucket.org.

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

На следующей странице вы можете протестировать соединение, обновить параметры или удалить интеграцию.

Уровень проекта

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

Учетные данные Bitbucket

Для интеграции с Bitbucket нам нужны имя пользователя и пароль приложения.

Вы можете использовать свою учетную запись или создать новую служебную учетную запись на ваше усмотрение.

1. Перейдите в настройки учетной записи — https://bitbucket.org/account/settings/.

2. Скопируйте свое имя пользователя (в разделе Bitbucket profile settings).

3. Перейдите в настройки паролей приложений — https://bitbucket.org/account/settings/app-passwords/.

4. Нажмите Create app password.

5. Придумайте название для пароля.

6. Укажите необходимые разрешения:

   • Account read (необходимо для тестирования соединения);
   • Issues > Write (если вы собираетесь связывать джобы из Bitbucket с сущностями ТестОпс);
   • Pipeline > Edit variables (для установки значений переменных);
   • Repositories > Read (для чтения файла пайплайна).

7. Создайте пароль приложения.

8. Скопируйте созданный пароль.

Настройка интеграции в вашем проекте ТестОпс

Важно

Вам нужно быть владельцем проекта для настройки этих параметров.

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

Теперь мы готовы настроить джобу.

Настройки джоб в ТестОпс

Джоба в ТестОпс — это сущность, связанная с пайплайнами CI-сервисов. Процесс загрузки результатов тестов — это запуск джобы. Все параметры запуска джобы управляются ТестОпс и CI-плагином (allurectl).

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

Чтобы иметь возможность запускать связанные пайплайны, вам нужно настроить сервер сборки (что было сделано на предыдущем шаге).

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

1. Выберите CI-сервер, настроенный на уровне проекта с валидными правами доступа.
2. Отметьте джобу как доступную для запуска тестов.
3. Свяжите переменные окружения, полученные от джобы, с глобальными переменными окружения.
4. Нажмите Отправить.

Важно

Как вы видите, есть 2 специальные переменные: Branch и CustomName.

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

CustomName не требует соответствующей переменной справа, но требует установки значения по умолчанию. Это значение — название вашего пайплайна из файла bitbucket-pipelines.yml.

Запуск пайплайна

Запуск пайплайна (который создаст запуск в ТестОпс) можно выполнить в следующих разделах ТестОпс:

• Список тест-кейсов — выберите тест-кейсы и используйте массовую операцию Запустить.
• Список результатов тестов — выберите результаты и используйте массовую операцию Перезапустить.
• Тест-планы — нажмите кнопку Запустить нужного тест-плана.
• Джобы — нажмите кнопку Запустить нужной джобы.

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

Запуск пайплайна на альтернативном окружении

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

В окне редактирования джобы в ТестОпс нажмите Добавить переменную окружения.

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

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

Пример завершенного пайплайна

Вот очень простой пример файла пайплайна Bitbucket, который должен дать общее представление о настройке работы с ТестОпс:

# bitbucket-pipelines.yml
image: python:3.8

pipelines:
  custom:
    pytest python tests:
      - variables:
          - name: ALLURE_LAUNCH_NAME
            default: ""
          - name: ALLURE_LAUNCH_TAGS
            default: "bitbucket, pytest"
          - name: ALLURE_RESULTS
            default: "allure-results"
          - name: TESTS_ENDPOINT
            default: "https://testops.testing.com"
          - name: TESTS_BROWSER
            default: "firefox"
          - name: ALLURE_PROJECT_ID
            default: "830"
          - name: ALLURE_ENDPOINT
            default: "https://testops.example.com"

      - step:
          name: pytest tests
          script:
            - /usr/local/bin/python -m pip install --upgrade pip
            - pip install pytest allure-pytest
            - ALLURE_LAUNCH_NAME="${BITBUCKET_REPO_FULL_NAME} - $BITBUCKET_BUILD_NUMBER"
            - wget https://github.com/allure-framework/allurectl/releases/download/2.15.6/allurectl_linux_amd64 -O ./allurectl
            - chmod +x ./allurectl
            - ./allurectl watch -- pytest test --alluredir=${ALLURE_RESULTS}

Здесь pytest python tests: — обязательное название пайплайна, необходимое для вызова пайплайна через API.

ALLURE_LAUNCH_NAME, ALLURE_LAUNCH_TAGS, ALLURE_RESULTS, ALLURE_PROJECT_ID и ALLURE_ENDPOINT — это переменные, необходимые для allurectl, чтобы загрузить результаты тестов в ТестОпс.