Адаптер Cucumber JVM

app.doqa:doqa-cucumber — плагин Cucumber-JVM, который отправляет результаты сценариев в DoQA. Каждый сценарий из .feature-файла становится автотестом, шаги Gherkin («Дано / Когда / Тогда») — шагами результата, хуки @Before и @After — шагами setup и teardown, а каждая строка Examples у Scenario Outline — отдельным результатом с параметрами. Тест-кейсы DoQA привязываются тегами прямо в .feature-файле.

Если DoQA недоступен или не настроен, сценарии проходят как обычно: ошибка отправки не роняет сборку, плагин только пишет предупреждение в лог.

Требования

• Cucumber-JVM 7.x или 8.x.
• JDK 11 или новее. Cucumber 8 сам требует JDK 17.
• Любой из трёх способов запуска Cucumber: JUnit Platform (cucumber-junit-platform-engine, JUnit 5 и 6, платформа 1.8 или новее), JUnit 4 (cucumber-junit) или TestNG (cucumber-testng). Один модуль работает со всеми тремя.

Установка

Шаг 1. Добавьте зависимость:

Maven

<dependency>
  <groupId>app.doqa</groupId>
  <artifactId>doqa-cucumber</artifactId>
  <version>0.1.9</version>
  <scope>test</scope>
</dependency>

Gradle

testImplementation("app.doqa:doqa-cucumber:0.1.9")

Шаг 2. Подключите плагин в конфигурации Cucumber. Автоматического подключения плагинов у Cucumber нет, поэтому без этой строки адаптер не работает.

JUnit Platform, файл src/test/resources/junit-platform.properties (через запятую с плагинами, которые там уже есть):

cucumber.plugin=app.doqa.cucumber.DoqaCucumberPlugin

Если плагины заданы на классе @Suite через @ConfigurationParameter, допишите плагин туда: это значение перекрывает и файл, и -Dcucumber.plugin.

@Suite
@IncludeEngines("cucumber")
@SelectClasspathResource("features")
@ConfigurationParameter(key = PLUGIN_PROPERTY_NAME,
        value = "pretty, app.doqa.cucumber.DoqaCucumberPlugin")
public class RunCucumberTest {
}

JUnit 4 и TestNG:

@CucumberOptions(plugin = {"pretty", "app.doqa.cucumber.DoqaCucumberPlugin"})

Здесь плагины из всех источников складываются, поэтому плагин можно подключить и снаружи, не меняя код: переменной окружения CUCUMBER_PLUGIN=app.doqa.cucumber.DoqaCucumberPlugin в CI или -Dcucumber.plugin=….

Шаг 3. Запустите сценарии. Если подключение к DoQA не настроено, адаптер записывает результаты в ./results/ в Allure-совместимом формате. Загрузить их можно любым способом со страницы Отправка результатов автотестов. Чтобы отправлять результаты напрямую, задайте адрес, токен и ID пространства:

url=https://demo.doqa.app
token=<project-токен>
spaceId=42

Как создать токен и узнать ID пространства — в разделах «Создание API-токена» и «Как узнать ID пространства».

Конфигурация

Настройки такие же, как у остальных JVM-адаптеров: файл doqa.properties, переменные окружения DOQA_* и системные свойства -Ddoqa.*, способы отправки reporting=auto|api|files|off, режимы прогона 0, 1 и 2. Полная таблица ключей — на странице адаптера TestNG.

Особенности Cucumber:

• importRealtime=true отправляет результаты после каждого сценария: события «фича завершена» у Cucumber нет.
• Если DoQA недоступен на старте, результаты всего прогона записываются в resultsDir. Если DoQA отклонил пакет посреди прогона, в файлы записывается только этот пакет.

Что приходит в DoQA

Поле автотеста	Значение
Имя	имя сценария. У Scenario Outline — шаблон с <параметрами>, у результата строки Examples — имя с подставленными значениями
Пространство имён	каталог фичи относительно корня classpath, например features/payments
Класс	имя Feature
Теги	теги всех уровней (Feature, Rule, сценарий, Examples) без @, кроме служебных тегов DoQA
Параметры результата	строка Examples списком «колонка = значение»

Шаги, хуки и вложения

В Cucumber	В DoQA
Шаг Gherkin, включая Background	шаг «ключевое слово + текст» с ключевым словом из файла (Дано …)
DocString, DataTable	текстовое вложение шага
@Before / @After	шаги setup / teardown с именем Класс.метод
@BeforeStep / @AfterStep	отдельными шагами не показываются; их ошибки, вложения и сообщения попадают в соседний шаг Gherkin
@BeforeAll / @AfterAll	не показываются
scenario.attach(...)	вложение текущего шага, вне шага — вложение сценария
scenario.log(...)	сообщение текущего шага
Doqa.step, @Step в коде шага	вложенный шаг текущего шага Gherkin

Фасад Doqa работает в коде шагов и хуков так же, как в JUnit 5 и TestNG: Doqa.addLabel, Doqa.addLink, Doqa.addCaseIds, Doqa.addExternalId и остальные методы.

Исходы

Cucumber	DoQA
PASSED	passed
FAILED	failed для AssertionError, иначе broken
SKIPPED	skipped: шаги после упавшего и пропущенные по предположению (assumption)
PENDING	skipped с сообщением, что шаг не реализован
UNDEFINED	broken с сообщением, что для шага нет определения
AMBIGUOUS	broken с сообщением Cucumber

Сценарии, отфильтрованные cucumber.filter.tags или cucumber.filter.name, в DoQA не уходят. Повтор сценария (rerun Surefire, rerun-файл) даёт новый результат того же автотеста.

Теги DoQA

Аннотации @Doqa* в .feature-файле не повесить, поэтому разметку задают тегами:

Тег	Что делает	Аналог в коде
@doqa.id:<значение>	явный идентификатор автотеста. {колонка} подставляется из строки Examples, и строка становится отдельным автотестом	@DoqaId
@DOQA-<n> или @DOQA:<n>	идентификатор DOQA-<n>. То же даёт [DOQA-<n>] в имени сценария	—
@allure.id:<n>	идентификатор ALLURE-<n> и привязка к тест-кейсу <n>	@AllureId
@doqa.case:<n>	привязка к тест-кейсу <n>. Несколько кейсов задаются повтором тега	@DoqaCaseIds

@doqa.case:101
Feature: Перевод между счетами

  @doqa.id:transfer-basic
  Scenario: Простой перевод
    ...

  Scenario Outline: Перевод <amount> на счёт <to>
    ...
    @doqa.id:transfer-{to}
    Examples:
      | amount | to      |
      | 10     | savings |

• Источники идентификатора проверяются сверху вниз, как в таблице. Внутри одного источника побеждает самый узкий уровень: Examples, сценарий, Rule, Feature.
• Кейсы из @doqa.case: объединяются со всех уровней и с Doqa.addCaseIds(...).
• Вместо : можно писать = (@allure.id=5, как пишет allure-cucumber). Список через запятую не поддерживается — повторяйте тег.

Идентификатор без тегов

Если тегов нет, идентификатор вычисляется как cucumber:<sha1> от пути фичи и имени сценария (внутри Rule — ещё и имени Rule). Путь берётся относительно корня classpath, номер строки в идентификатор не входит. Переименование сценария, Rule или файла меняет идентификатор, как переименование метода в Java. Чтобы история сохранилась, закрепите идентификатор тегом @doqa.id:.

Выборочный прогон

При запуске выбранных автотестов из DoQA адаптер работает в режиме 0:

• JUnit Platform. Невыбранные сценарии, вплоть до отдельных строк Examples, исключаются из плана запуска до выполнения.
• JUnit 4 и TestNG. Исключить сценарий до запуска плагин не может: выполняются все сценарии, а в DoQA уходят только выбранные. Лишнее выполнение убирает нативный фильтр.

Для Cucumber DoQA строит нативный фильтр по именам сценариев и передаёт его в пайплайн переменной DOQA_NATIVE_FILTER:

# .gitlab-ci.yml
test:
  script:
    - mvn test ${DOQA_NATIVE_FILTER:+-Dcucumber.filter.name="$DOQA_NATIVE_FILTER"}

Порядок выполнения по плану DoQA не поддерживается: порядком сценариев управляет Cucumber.

Совместная работа с другими адаптерами

Юнит-тесты и сценарии часто живут в одном модуле. Если подключён DoqaCucumberPlugin, адаптеры doqa-junit5, doqa-junit4 и doqa-testng пропускают сценарии Cucumber: каждый сценарий отправляется один раз, а юнит-тесты сохраняют свои идентификаторы. Прогон в DoQA при этом один.

Ограничения

• Переход на doqa-cucumber начинает историю заново. Адаптеры раннеров отправляли сценарии с другими идентификаторами. Сохранить историю можно только у сценариев с [DOQA-<n>] в имени.
• Нет фикстур уровня прогона. @BeforeAll / @AfterAll в результаты не попадают.
• Нет отбора до запуска на JUnit 4 и TestNG и порядка по плану.
• DocString и DataTable одновременно (Cucumber 8): плагин получает только один аргумент шага.

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

Симптом	Причина и решение
Сценарии не приходят, в логе WARNING «Cucumber scenarios are running without the DoQA plugin»	не добавлена строка cucumber.plugin. На JUnit Platform проверьте @ConfigurationParameter на классе @Suite: он перекрывает junit-platform.properties
Сценарии не приходят, в логе ничего нет (JUnit 4, TestNG)	плагин не указан в @CucumberOptions(plugin = …), CUCUMBER_PLUGIN или -Dcucumber.plugin
Результаты в results/, а ожидались в DoQA	не заданы url, token, spaceId или DoQA был недоступен на старте
У строк Outline разные автотесты	в @doqa.id: есть {колонка}. Уберите подстановку, чтобы строки стали результатами одного автотеста
В режиме 0 на JUnit 4 или TestNG выполняются все сценарии	так устроены эти раннеры: передайте нативный фильтр (-Dcucumber.filter.name)

Смотрите также

• Адаптеры для тестовых фреймворков — когда адаптер, а когда отчёты
• Адаптер pytest — сценарии pytest-bdd на Python
• Запуск автотестов из DoQA — как формируется прогон для выборочного режима