Autotest API

Autotest API — прямое HTTP-API /api/autotests/*, через которое адаптеры тестовых фреймворков отправляют результаты в DoQA в реальном времени. Эта страница — для тех, кто пишет собственный адаптер или интеграцию, потому что готового адаптера под их язык или фреймворк нет.

Когда нужно Autotest API

По сравнению с выгрузкой готового отчёта прямое API даёт:

• результаты в прогоне по ходу выполнения, а не после его окончания;
• шаги и фикстуры со статусами, длительностью и вложениями;
• вложения (скриншоты, видео, логи), привязанные к результату;
• определения автотестов в каталоге: заголовок, описание, метки, ссылки, дерево шагов;
• привязку автотестов к тест-кейсам;
• управление тест-раном: создать прогон, узнать набор выбранных к запуску автотестов, следить за сводкой;
• конфигурацию, в которой получен результат.

Если из этого списка ничего не нужно — проще отправлять готовые отчёты.

Тест-ран в Autotest API — это обычный прогон DoQA; отдельной сущности нет.

Аутентификация

Все запросы адаптера авторизуются API-токеном проекта — как его создать, см. Создание API-токена.

• Токен передаётся в поле token: в теле POST-запросов и в query-параметре GET-запросов. Заголовок Authorization не используется.
• Токен привязан к проекту: работать можно с любым пространством этого проекта. Пространство чужого проекта — ошибка 403 {"error":{"message":"Token is not allowed for this space","status":403}}.
• Токен не передан или не найден — ошибка 401 {"error":{"message":"Invalid token","status":401}}.

Домен экземпляра в облачной поставке

В облаке запросы отправляйте на домен вашего экземпляра (например, https://company.doqa.app): токен ищется в базе конкретного клиента, и на другом адресе тот же токен вернёт 401.

Обзор эндпоинтов

Эндпоинты адаптера (авторизация — токен проекта):

Метод и путь	Назначение
POST /api/autotests/test-runs	создать пустой прогон (тест-ран)
GET /api/autotests/test-runs/{id}	статус и сводка прогона по статусам
GET /api/autotests/test-runs/{id}/autotests	какие автотесты числятся в прогоне — набор для выполнения
POST /api/autotests/run-start	создать прогон и сразу привязать его к пайплайну CI
POST /api/autotests/upsert	создать или обновить определения автотестов в каталоге
POST /api/autotests/sync-ids	сопоставить локальные тесты со стабильными ID DoQA
POST /api/autotests/results	загрузить пачку результатов в прогон
POST /api/autotests/attachments	загрузить файл вложения

Остальные эндпоинты /api/autotests/* — каталог, карточка и история автотеста, массовые действия, запуск выбранных, перестановка порядка тест-рана — обслуживают интерфейс DoQA и работают под авторизацией пользователя. Адаптеру они не нужны.

Типовой сценарий адаптера

Autotest API — не набор независимых эндпоинтов, а последовательность:

1. Определения (необязательно). POST upsert — зарегистрировать или обновить определения автотестов: заголовки, описания, метки, дерево шагов, привязку к кейсам. Можно делать до старта тестов или в конце прогона.
2. Прогон. Если задана переменная окружения DOQA_TEST_RUN_ID — прогон уже создан DoQA, репортите в него. Иначе создайте свой: POST test-runs → runId.
3. Набор. Если DOQA_ADAPTER_MODE=0 (запуск выбранных из DoQA) — запросите GET test-runs/{id}/autotests?ciRunId=$DOQA_CI_RUN_ID и выполняйте только перечисленные автотесты, в отданном порядке.
4. Результаты. По ходу прогона отправляйте POST results батчами. Вложения загружайте заранее через POST attachments и ссылайтесь на них по mediaFileId.
5. Завершение. Эндпоинта завершения прогона в Autotest API нет. Прогон, привязанный к пайплайну CI, DoQA завершает сама по окончании пайплайна (см. Запуск автотестов из DoQA); прогон локального запуска завершают в интерфейсе.

Переменные DOQA_TEST_RUN_ID, DOQA_ADAPTER_MODE, DOQA_CI_RUN_ID DoQA передаёт пайплайну при запуске автотестов из интерфейса — полный список переменных и их смысл описаны на странице Запуск автотестов из DoQA.

Тест-раны

Создание: POST /api/autotests/test-runs

Тело запроса (имена полей — camelCase):

Поле	Обязательное	Смысл
token	да	API-токен проекта
spaceId	да	ID пространства
name	нет	название прогона; по умолчанию — «Autotest run» (с externalKey — «Autotest run {ключ}»)
configurationId	нет	конфигурация прогона; должна принадлежать пространству
externalKey	нет	внешний ключ запуска — попадает в название прогона
pipelineId	нет	ID пайплайна CI (эхо CI_PIPELINE_ID) — привязывает прогон к пайплайну
branch	нет	ветка пайплайна

Ответ — 201 {"runId": <id>}. Прогон создаётся пустым и наполняется результатами по мере их загрузки.

POST run-start делает то же самое с телом {token, spaceId, title?, pipelineId?, branch?} — используйте любой из двух путей, оба привязывают прогон к пайплайну, если передан pipelineId. Без привязки прогон из CI не покажет пайплайн и джобы, и по нему не сработает автоматика финализации.

externalKey — не ключ идемпотентности

externalKey используется только в названии прогона. Повторный POST test-runs с тем же ключом создаст второй прогон. Не полагайтесь на него для дедупликации — не повторяйте запрос создания, если ответ получен.

Сводка: GET /api/autotests/test-runs/{id}

Ответ: {runId, spaceId, name, status, summary: {total, passed, failed, broken, blocked, skipped, initial}, createdAt, updatedAt}. Токен передаётся query-параметром token.

Набор автотестов: GET /api/autotests/test-runs/{id}/autotests

Возвращает, какие автотесты числятся в прогоне: {runId, configurationId, source, ordered, autotests: [{autotestId, externalId, name, position?}]}. Адаптер должен выполнить только их и в порядке position, если ordered = true.

• Параметр ?ciRunId= (эхо переменной DOQA_CI_RUN_ID) сужает набор до автотестов, назначенных именно этому пайплайну. Когда на один прогон запущено несколько пайплайнов, без него не обойтись: пустой ответ с ciRunId означает «этому пайплайну выполнять нечего», а не «выполняй всё».
• Без ciRunId возвращаются ещё не прогнанные автотесты прогона, а если таких нет — весь набор.
• Для свежего пустого прогона возвращаются все автотесты пространства (source = 'space-fallback').

Загрузка результатов: POST /api/autotests/results

Сохраняет пачку результатов в существующий прогон. Тело: {token, spaceId, testRunId, configurationId?, ciRunId?, pipelineId?, results: [...]}. Ответ: {accepted, elementIds}.

Поля элемента results[]:

Поле	Обязательное	Смысл
externalId	да	внешний ID автотеста, до 255 символов
outcome	да	исход: passed, failed, skipped или broken
name	нет	полное имя автотеста, до 255 символов. Обязательно, пока автотеста с таким externalId ещё нет в пространстве — безымянный результат для неизвестного автотеста пропускается
startedOn, completedOn	нет	время старта и окончания: ISO-8601 или epoch в миллисекундах
durationMs	нет	длительность в миллисекундах
message, traces	нет	сообщение и стек-трейс. Для failed/broken это ошибка результата; message у passed — информационное сообщение
parameters	нет	параметры запуска — только списком [{name, value}]; форма-словарь {"имя": "значение"} отклоняется с 422
stepResults, setupResults, teardownResults	нет	шаги, setup- и teardown-фикстуры: {title, outcome?, durationMs?, message?, attachments?, steps?}, вложенность через steps
attachments	нет	вложения результата: [{mediaFileId, kind?}] — ID заранее загруженных файлов
links	нет	ссылки результата: [{url, type?, title?, description?}]; type — related, defect, requirement, blocked_by или repository

Повторная доставка безопасна: существующий результат обновляется, только если новый строго новее по времени старта, а поздние повторы отбрасываются без создания дублей. Результаты одного теста с разными наборами параметров или в разных конфигурациях хранятся отдельными строками — набор параметров входит в ключ сопоставления.

Корреляция с пайплайном: передавайте ciRunId (эхо DOQA_CI_RUN_ID) или pipelineId. Если у прогона ровно один пайплайн, DoQA сопоставит результат и без них, но при нескольких пайплайнах результат без эха останется не привязанным к своему пайплайну — его не учтут критерии приёмки и источники автотестов.

Вложения: POST /api/autotests/attachments

Multipart-запрос {token, spaceId, file}. Ответ — 201 {"mediaFileId": <id>}. Полученный ID указывается в results[].attachments. Лимит размера файла — по умолчанию 100 МБ.

Сослаться можно только на файл, загруженный в то же пространство: чужой или несуществующий mediaFileId пропускается без ошибки.

Определения автотестов: upsert и sync-ids

POST upsert — bulk-создание и обновление определений в каталоге автотестов. Тело: {token, spaceId, autotests: [{externalId, name, title?, description?, namespace?, classname?, labels?, tags?, links?, steps?, caseIds?}]}; ответ — {map: {"<externalId>": {autotestId, created}}}.

• Обновление частичное: перетираются только присланные ключи, пустая строка очищает поле.
• caseIds привязывает автотест к существующим тест-кейсам (аддитивно); тест-кейсы не создаются.
• steps — авторское дерево шагов определения (что тест должен делать), оно не заменяет шаги результата из results[].
• Элемент без externalId или без name пропускается.

POST sync-ids — сопоставление локальных тестов со стабильными ID DoQA. Тело: {token, spaceId, create?, items: [{externalId?, name, signature?, file?, line?}]}. Ответ — {map: {"<ключ>": {autotestId, assignedId, caseIds, created}}, orphans: [...]}:

• assignedId — стабильный внешний ID, который стоит записать в код теста (например, аннотацией);
• caseIds — тест-кейсы, уже привязанные к автотесту;
• orphans — автотесты пространства, которых не оказалось среди присланных (например, удалённые из кода);
• create = true создаёт недостающие автотесты, иначе запрос только читает.

Правила externalId

externalId — стабильный идентификатор автотеста, главный ключ всего API.

• Уникален в пределах пространства. За уникальность отвечает адаптер: два разных теста с одним externalId сольются в один автотест.
• Стабилен: пока externalId не меняется, переименование теста не рвёт историю и привязку к кейсам.
• Не длиннее 255 символов.

Поведение без externalId, усыновление истории и переход на стабильные ID — Автотесты.

Рекомендации

• Батчируйте результаты. Отправляйте results[] пачками, а не по запросу на тест: адаптер DoQA для JVM шлёт до 100 результатов в одном запросе.
• Повторяйте только идемпотентные запросы. GET-запросы и ответы 429 можно повторять безопасно. POST results и POST test-runs повторяйте только если соединение вообще не установилось: потерянный ответ на доставленный запрос при повторе создаст дубль прогона.
• Ограничивайте объем на своей стороне. Обрезайте длинные стек-трейсы и сообщения до отправки (адаптер DoQA для JVM режет трейс до 100 000 символов, сообщения — до 10 000).
• Не логируйте токен — в том числе в сообщениях об ошибках HTTP-клиента.

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

• Отправка результатов автотестов — готовые отчёты: интерфейс, doqa-cli, report-API
• Адаптеры для тестовых фреймворков — готовые адаптеры вместо собственного
• Запуск автотестов из DoQA — переменные пайплайна и финализация прогона
• Автотесты — внешний ID и связь автотестов с тест-кейсами
• Каталог автотестов — где видны определения, метки и привязки