Адаптер Jest

@doqa-tms/jest отправляет результаты тестов Jest в DoQA: автотесты создаются и обновляются сами, результаты приходят с шагами, фикстурами, параметрами, вложениями и ссылками. Существующие тесты менять не нужно: адаптер учитывает тесты, объявленные через test и it. Объект doqa нужен только для дополнительных данных.

Ошибки отправки не меняют результат прогона Jest. Если DoQA недоступен или отклоняет запрос, адаптер выводит предупреждение и записывает в файлы результаты, которые не удалось отправить.

Требования и установка

Node.js 22 или новее (адаптер проверяется на 22 и 24).
Jest 29.7 или 30 со стандартным раннером jest-circus.
jest-environment-jsdom той же версии, если тесты используют среду jsdom.

npm install --save-dev @doqa-tms/jest

Последняя опубликованная версия — 0.1.1. Подключите адаптер в конфигурации Jest:

// jest.config.cjs
const { withDoqa } = require('@doqa-tms/jest');
module.exports = withDoqa({ testEnvironment: 'node' });   // второй аргумент — настройки адаптера, необязателен

withDoqa возвращает вашу конфигурацию Jest, в которую добавлены reporter адаптера и обёртки над средами node и jsdom.

Уже на этом шаге, без настроек подключения, адаптер пишет результаты в ./results/ в Allure-совместимом формате. Загрузить их в DoQA можно любым способом со страницы Отправка результатов автотестов.

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

Для отправки напрямую в DoQA нужны адрес, токен и ID пространства. Задайте их в файле doqa.properties в каталоге, из которого запускается Jest, или переменными окружения:

properties

# doqa.properties (или DOQA_URL / DOQA_TOKEN / DOQA_SPACE_ID в CI)
url=https://demo.doqa.app
token=<project-токен>
spaceId=42

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

Внимание

Токен в doqa.properties означает, что каждый запуск тестов пишет в DoQA, включая локальные. Обычно ключи задают только в CI через переменные окружения DOQA_URL, DOQA_TOKEN и DOQA_SPACE_ID.

Источники настроек по убыванию приоритета: второй аргумент withDoqa, переменные окружения DOQA_*, файл doqa.properties. Токен из второго аргумента withDoqa не попадает в конфигурацию, которую видят --showConfig и workers.

Ключ	Переменная окружения	По умолчанию	Назначение
`url`	`DOQA_URL`	—	адрес DoQA
`token`	`DOQA_TOKEN`	—	токен проекта
`spaceId`	`DOQA_SPACE_ID`	—	ID пространства
`reporting`	`DOQA_REPORTING`	`auto`	`api` / `files` / `auto` / `off`
`adapterMode`	`DOQA_ADAPTER_MODE`	`2` (`1`, если задан `testRunId`)	`0`/`selective`, `1`/`existing`, `2`/`new`
`testRunId`	`DOQA_TEST_RUN_ID`	—	прогон для режимов 0 и 1
`testRunName`	`DOQA_TEST_RUN_NAME`	`Jest`	имя нового прогона (режим 2)
`configurationId`	`DOQA_CONFIGURATION_ID`	—	конфигурация прогона
`environment`	`DOQA_ENVIRONMENT`	—	метка окружения прогона
`ciRunId`	`DOQA_CI_RUN_ID`	—	запуск CI, который инициировал DoQA
`pipelineId`	`DOQA_PIPELINE_ID`	из переменных CI	пайплайн CI, к которому привязывается прогон
`sourceKey`	`DOQA_SOURCE_KEY`	—	CI-подключение пространства; DoQA передаёт его в пайплайн сам
`correlationId`	`DOQA_CORRELATION_ID`	—	связь с запуском, который DoQA поставил в очередь CI
`branch`	`DOQA_BRANCH`	`CI_COMMIT_REF_NAME` / `GITHUB_REF_NAME`	ветка прогона
`resultsDir`	`DOQA_RESULTS_DIR`	`results`	каталог для файлов результатов
`importRealtime`	`DOQA_IMPORT_REALTIME`	`false`	отправлять результаты после каждого тестового файла
`executionOrder`	`DOQA_EXECUTION_ORDER`	`jest`	`plan` — выполнять тесты в порядке плана DoQA
`batchSize`	`DOQA_BATCH_SIZE`	`100`	максимальное число результатов в одном запросе
`proxy`	`DOQA_PROXY`	—	HTTP-прокси `host:port`
`certValidation`	`DOQA_CERT_VALIDATION`	`true`	`false` отключает проверку TLS-сертификата

pipelineId подхватывается автоматически в GitLab, GitHub Actions, Jenkins и TeamCity.

Режимы работы с прогоном

2 / new (по умолчанию) — адаптер создаёт один прогон на весь запуск Jest, включая все workers и projects.
1 / existing — результаты уходят в прогон testRunId.
0 / selective — адаптер получает из DoQA список автотестов прогона и выполняет только их. Остальные тесты Jest показывает как skipped, в DoQA они не отправляются. Этот режим DoQA включает сам при запуске выбранных автотестов из интерфейса.

С executionOrder: 'plan' в режиме 0 адаптер выполняет тестовые файлы и тесты в порядке плана DoQA. Если применить порядок нельзя (например, в файле есть test.concurrent или задан собственный testSequencer), адаптер выводит предупреждение и оставляет порядок Jest.

Для Jest DoQA также передаёт в пайплайн нативный фильтр DOQA_NATIVE_FILTER, его используют в команде npx jest -t "$DOQA_NATIVE_FILTER".

При --shard каждый шард — отдельный процесс Jest: в режиме 2 каждый создаст свой прогон, поэтому для шардов используйте режим 1. В режиме watch адаптер ничего не отправляет.

Разметка тестов

Разметка необязательна.

const { doqa } = require('@doqa-tms/jest');

doqa.test('создание заявки', {
  id: 'REQUEST-CREATE',                         // стабильный внешний ID автотеста (рекомендуется)
  title: 'Пользователь создаёт заявку',
  description: 'Заявка сохраняется и получает номер',
  caseIds: [123],                                // привязка к тест-кейсам DoQA
  labels: { owner: 'requests' },
  tags: ['smoke'],
  links: [{ url: 'https://example.org/REQ-1', title: 'Требование', type: 'requirement' }],
  createManualCase: true,                        // завести связанный ручной кейс
}, async () => {
  await doqa.step('заполнить форму', async () => {
    doqa.parameter('role', 'user');
    doqa.attach('request.txt', 'демонстрационное вложение', 'text/plain');
  });
});

doqa.test.each([['admin'], ['user']])('роль %s', { id: 'REQUEST-ROLE' }, (role) => {
  doqa.parameter('role', role);
});

doqa.test поддерживает .only, .skip, .concurrent и .each. Для doqa.test.each все строки данных относятся к одному автотесту, а аргументы строки приходят параметрами результата. Обычный test.each создаёт отдельный автотест на каждую строку.

Внутри теста и хуков доступны:

doqa.metadata({ caseIds: [42], labels: { severity: 'critical' } });   // дополняет метаданные теста
doqa.parameter('env', 'staging');
await doqa.step('дождаться ответа', async () => { /* ... */ });
doqa.attach('response.json', JSON.stringify(body), 'application/json');
doqa.attachFile('artifacts/screenshot.png');

Внешний ID

Адаптер берёт внешний ID из id в метаданных теста или из названия теста в форме [DOQA-123] или @DOQA:123. Если идентификатора нет, он вычисляется как хэш от имени проекта Jest, пути к файлу, цепочки describe и названия теста. Переименование теста или перенос в другой файл или describe-блок меняют такой идентификатор, и DoQA создаёт новый автотест без истории. Чтобы история сохранялась, задайте id.

Фикстуры и исходы

Хуки попадают в отчёт без дополнительной настройки: beforeEach и afterEach — шаги setup и teardown теста, beforeAll и afterAll — шаги setup и teardown каждого теста своего describe-блока.

Что случилось	Исход в DoQA
Тест прошёл	`passed`
Не выполнилась проверка (`expect`, `node:assert`, chai)	`failed`
Другое исключение, таймаут	`broken`
Упал хук	`broken`
`test.skip`, `describe.skip`, `test.todo`	`skipped`
Повтор через `jest.retryTimes`	каждая попытка — отдельный результат того же автотеста

Параллельный запуск

Отдельная настройка не нужна. Прогон в DoQA создаёт reporter в главном процессе Jest, а workers записывают результаты в каталог .doqa/, откуда reporter их отправляет.

Ограничения

Метаданные на уровне describe и плейсхолдеры {param} в идентификаторах не поддерживаются.
Разметка Allure (allure-js-commons) не используется. При переходе с jest-junit или Allure автотесты создаются заново, без прежней истории. Чтобы история начиналась с первого прогона через адаптер, задайте id до перехода.
Раннер jest-jasmine2 не поддерживается.
Проекты, заданные строками в projects, не отчитываются: описывайте их объектами.

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

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

Адаптер Jest ​

Требования и установка ​

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

Режимы работы с прогоном ​

Разметка тестов ​

Внешний ID ​

Фикстуры и исходы ​

Параллельный запуск ​

Ограничения ​