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

Руководство описывает два отдельных сценария: перенос каталога кейсов
Test IT в Mockarty и отправку результатов CI из JUnit XML через mockarty-cli.
Преобразованный JSON тоже поддерживается. Существующие адаптеры Test IT
отправляют HTTP-запросы прямо в Test IT: замены трёх переменных
окружения для их переключения недостаточно.

Mockarty не реализует wire-протокол /api/v2/* TestIT.
Перевод происходит внутри mockarty-cli: он локально парсит
JUnit XML или подготовленный JSON и POST’ит нормализованный payload в
канонический эндпоинт /tcm/external-runs, который Mockarty уже
поддерживает для Allure, Ginkgo, pytest.

1. Настройки подключения CLI

Замените три TestIT-переменные в CI-конфиге:

mockarty-cli принимает обе формы. Если MOCKARTY_* пустые,
mockarty-cli автоматически подбирает TMS_* для своих команд.
Укажите URL Mockarty admin, API-токен Mockarty и его пространство имён:
токен Test IT и числовой ID проекта здесь не подходят.

# Настройки команд mockarty-cli testit.
export TMS_URL=https://mockarty.example.com
export TMS_PRIVATE_TOKEN=<ваш API-токен Mockarty>
export TMS_PROJECT_ID=team-a

Формат токена

Если вставить «сырое» значение заголовка Authorization
(PrivateToken hexhex…) в TMS_PRIVATE_TOKEN, mockarty-cli
автоматически отрежет префикс PrivateToken . То же касается
префикса Bearer . Чистить значение вручную не нужно.

2. Результаты CI из JUnit XML

Если ваш тестовый раннер создаёт JUnit XML, передайте --results/-r путь к
файлу или каталогу с XML. mockarty-cli принимает одноимённые параметры
testit-cli results upload: --configuration-id/-ci, --testrun-id/-ti,
--separator/-s, --namespace/-ns (идентичность JUnit-теста),
--classname/-cn и --ignore-flaky-failure/-iff. Пространство имён
Mockarty задаётся через TMS_PROJECT_ID или MOCKARTY_NAMESPACE.

# 1. Создать test run на текущую CI-задачу.
export TMS_TEST_RUN_NAME="CI #${CI_PIPELINE_IID}"
mockarty-cli testit testrun create --output ./testrun.id
RUN_ID=$(cat ./testrun.id)

# 2. Запустить тесты с выводом JUnit XML в ./junit-reports.

# 3. Загрузить все XML-файлы; ID прогона прочитан из ./testrun.id.
mockarty-cli testit results upload --results ./junit-reports --testrun-id "$RUN_ID"

# 4. Закрыть run.
mockarty-cli testit testrun complete "$RUN_ID"

Пустой каталог, некорректный XML или файл без кейсов останавливает команду
до отправки результатов. Неуспешный или отменённый прогон даёт ненулевой код
выхода у testrun complete.

JUnit XML передаёт имя, classname, длительность и маркеры успеха/ошибки/
пропуска. В нём нет шагов Test IT, встроенных картинок, вложений,
параметров и произвольных метаданных. Для них нужен более богатый адаптер
или преобразованный JSON вместе с файлами вложений. Официальные адаптеры
Test IT отправляют запросы прямо в Test IT; подмена бинаря CLI их не
перенаправит.

Подготовленный JSON

Если ваш конвертер создаёт JSON-массив объектов
AutoTestResultsForTestRunModel, оставьте --file:

mockarty-cli testit results upload --file ./converted-results.json

Например, converted-results.json может содержать:

[{"autoTestExternalId":"suite.test_login","outcome":"Passed","duration":250}]

Что делает upload

results upload парсит каждый кейс JUnit или элемент подготовленного JSON
и POST’ит каждый результат
(параллельными воркерами с retry/backoff):

POST /api/v1/namespaces/<ns>/tcm/external-runs

Подготовленный JSON может передать файлы результата, если каталог
--attachments-dir содержит файлы с именем ID вложения (или ID с расширением).
Файлы вложенных шагов сохраняются на результате, а путь исходного шага — в
метаданных. Если файл отсутствует, пуст или превышает лимит 256 КиБ на файл
(1 МиБ на результат, до 32 файлов), команда останавливается до отправки
результатов. Для больших файлов нужен полный сценарий миграции: этот вариант
CLI пока не может их сохранить. ID конфигурации результата, ID work items,
ссылки, свойства и вложенные шаги сохраняются вместе с case-run.

3. Configuration UUID

TestIT использует configurationId как UUID-описатель «среды» теста
(Chrome vs Safari, prod vs staging, …).

В Mockarty конфигурации — first-class сущность:

# Сгенерировать UUID для CI.
export TMS_CONFIGURATION_ID="$(mockarty-cli testit configuration generate)"

# Список существующих конфигураций в namespace.
mockarty-cli testit configuration list

# Создать конфигурацию с понятным именем.
mockarty-cli testit configuration create \
    --id "$TMS_CONFIGURATION_ID" \
    --name "Chrome / prod"

Когда TMS_CONFIGURATION_ID установлен, каждый результат, который
CLI загружает в этой CI-задаче, тэгируется этим UUID. Панель отчётов
Mockarty показывает разбивку «по конфигурации» — удобно сравнить
один запуск под разными окружениями.

4. Workflow states

Стандартный процесс тест-кейса Mockarty содержит пять состояний: Draft,
In Review, Changes Requested, Active и Archived. В вашем пространстве может
использоваться другой процесс.

Собственный набор состояний work item в TestIT короче (NeedsWork,
NotReady, Ready плюс состояния, заданные в вашем проекте). Импортёр
переносит состояние каждого кейса: значение из TestIT сопоставляется с
состояниями воркфлоу пространства имён сначала по коду, затем по
подписи, без учёта регистра и пробелов по краям. Стандартное состояние
Test IT с кодом NotReady попадает в draft, если оно есть в Mockarty.
Точное совпадение в процессе пространства имеет приоритет; для остальных
состояний, включая Ready, нужен совпадающий код или подпись. При повторном
импорте состояние кейса обновляется вслед за изменением в Test IT.
Новый кейс без эквивалента состояния остаётся в состоянии пространства по
умолчанию; существующий сохраняет текущий статус. Массив warnings в сводке
импорта называет кейс и его исходное состояние. Добавьте совпадающее состояние
(или переименуйте существующее) и повторите импорт.

Состояния редактируются (переименование / новый цвет / новые
состояния). CRUD доступен через POST /tcm/workflow-states и
Admin UI.

Получить состояния воркфлоу (и их UUID) через API:

curl -H "X-API-Key: mk_..." \
  http://localhost:5770/api/v1/namespaces/<ns>/tcm/workflow-states

5. Алиас бинаря для поддерживаемых команд

Для поддерживаемых подкоманд testit можно сделать симлинк:

ln -s /usr/local/bin/mockarty-cli /usr/local/bin/testit-cli

CLI распознаёт это имя бинаря и направляет вызов в подкоманды testit.
Такой алиас не добавляет поддержку HTTP API Test IT или всех флагов
исходного testit-cli.

В CI можно вместо алиаса заменить команду на mockarty-cli testit (или назвать
тот же бинарь mcrtyctl и запускать mcrtyctl testit). Укажите адрес сервера
и токен Mockarty. Команда отправляет результаты в Mockarty, а не в Test IT;
старый PAT Test IT не подходит для входа в Mockarty.

testrun create --testruntags smoke,nightly сохраняет теги прогона. Команды
results upload и results import объединяют --testruntags с тегами
существующего прогона после проверки входных данных. --autotest-layer API
(или TMS_AUTOTEST_LAYER) сохраняется в метаданных результата. Типизированные
--testrunlinks отклоняются до загрузки: прогон Mockarty пока не хранит такие
ссылки. Убирайте флаг только если ссылки не нужны вашему CI. Сохранённый слой
пока нельзя фильтровать как отдельное поле автотеста.

6. Покрытие функций на сегодня

Тесты Python pytest

Если тесты используют testit-adapter-pytest, установите вместо него
mockarty[test] и замените import testit на
import mockarty.testit as testit. Укажите MOCKARTY_BASE_URL, MOCKARTY_API_KEY и
MOCKARTY_NAMESPACE; команду pytest --testit -q можно оставить. Удалите
старый адаптер из зависимостей: оба плагина регистрируют --testit. Обёртка
отправляет результаты только в Mockarty. ID проекта, конфигурации и прогона
Test IT не становятся ID Mockarty.

Поддержаны externalId, displayName, контекст step(...) и
addAttachments(...) с текстом или файлом. Байты файла сохраняются в пределах
ограничений: 256 КиБ на файл, 1 МиБ и 32 файла на результат. Вложения,
добавленные внутри шага, пока относятся к результату целиком; вложенные шаги,
шаги фикстур, статус workflow и сопоставление по TMS_TEST_RUN_ID эта обёртка
не сохраняет. Ошибка отправки делает результат pytest неуспешным.

7. Массовый импорт экспорта TestIT

Разделы выше обеспечивают потоковую загрузку результатов CI в Mockarty по
одному. Чтобы перенести существующий каталог TestIT — секции, кейсы,
метаданные шагов — за один раз, используйте живой pull из следующего
раздела: он подключается к вашему серверу TestIT и читает каталог через его
API. Это рекомендуемый путь.

Собственный UI TestIT выгружает work items в .xlsx, а не в JSON. Если у
вас такой файл — импортируйте его через табличный эндпойнт
(POST /api/v1/namespaces/{namespace}/tcm/import/xlsx).

Есть и JSON-эндпойнт массового импорта:

POST /api/v1/namespaces/{namespace}/tcm/import/testit

Он принимает промежуточную структуру самого Mockarty ({project, sections, workItems, attributes, configurations}) — ту, которую живой pull строит
внутри, — а не файл, который отдаёт TestIT. Используйте его, если собрали
такую структуру сами, например своим скриптом поверх API TestIT. Тело — JSON
(не multipart), ограничение 64 МиБ; более крупные payload’ы отклоняются с
ошибкой валидации.

CLI читает такой файл и отправляет его за вас:

mockarty-cli testit import --file ./testit-export.json

У этого JSON-эндпойнта нет подключения к Test IT, из которого можно скачать
файлы по ссылкам. Кейс со ссылками на исходные вложения получает ошибку в
результате импорта, чтобы медиа не пропали незаметно. Для таких кейсов
используйте живую загрузку ниже.

Нет файла экспорта? Заберите проект прямо с сервера TestIT

Если сервер TestIT доступен из Mockarty, файл экспорта не нужен — Mockarty
сам заберёт проект по REST API TestIT и импортирует его через тот же
конвейер:

POST /api/v1/namespaces/{namespace}/tcm/import/testit/pull

Для повторного импорта создайте подключение Test IT в Настройки → Интеграции.
Укажите URL сервера без пути, UUID проекта и ID записи секрета, содержащей
PrivateToken. Включите подключение и проверьте доступ кнопкой проверки.
В Тест-кейсы → Импорт → С сервера Test IT выберите сохранённое подключение:
токен остаётся на сервере, повторно вводить его не нужно.

В API сохранённое подключение выбирается так:

{"integrationId":"11111111-2222-3333-4444-555555555555","createPlan":false}

Для этого режима нужны права test_case:write и integrations:read в текущем
пространстве имён. Подключение должно быть активно и относиться к Test IT.
Не передавайте baseUrl, token или projectId вместе с integrationId:
адрес и проект берутся из сохранённого подключения. Импорт запускается по запросу;
это подключение само по себе не включает фоновую синхронизацию.

Во время импорта временные ответы источника (429, 502, 503, 504) и
сетевые сбои при чтении повторяются не более двух раз. Mockarty учитывает
Retry-After; если источник требует ждать более 30 секунд, импорт возвращает
ошибку, и его можно запустить позже, не нарушая этот лимит. Отмена импорта
прерывает ожидание повтора.

Для разового подключения передайте координаты напрямую:

curl -X POST http://127.0.0.1:5770/api/v1/namespaces/default/tcm/import/testit/pull \
  -H "Authorization: Bearer $MOCKARTY_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
        "baseUrl":   "https://testit.example.com",
        "token":     "<PrivateToken из TestIT>",
        "projectId": "0fff1111-2222-3333-4444-555566667777"
      }'

В интерфейсе: Тест-кейсы → Импорт → С сервера Test IT — укажите URL
сервера, PrivateToken и ID проекта; по завершении появится тост с итоговой
сводкой.

Живая загрузка также скачивает байты вложений из кейсов и шагов, включая
ссылки на общие шаги и встроенные изображения. Mockarty проверяет размер и
контрольную сумму источника, применяет ограничения целевого хранилища по
размеру, квоте, MIME и проверке файлов, сохраняет исходные байты. Импортированные
файлы принадлежат целевому кейсу; пути и идентификаторы источника сохраняются
рядом с ним. Ошибка переноса файла отмечает кейс как неудачный в сводке.
Повторный pull использует ту же ревизию файла; переименование в источнике
сохраняется как новая ревизия. HTML-действия шагов сохраняют исходное
содержимое; заголовок шага становится читаемым текстом, а встроенные
изображения открываются через защищённый адрес
файла импортированного кейса. После pull открытый кейс обновляется
автоматически, если в нём нет несохранённых правок. Перед повтором проверьте
файлы, превышающие лимиты целевого хранилища. Выгрузка с сервера создаёт
переиспользуемые общие шаги с доступными пронумерованными версиями и
сохраняет живые ссылки на них в кейсах. Файлы общего шага прикрепляются к
импортированному общему шагу.

Что забирается: дерево секций, все рабочие элементы (тест-кейсы, чек-листы,
общие шаги — с шагами, ссылками на общие шаги, тегами, ссылками на задачи в
трекере, параметрами итераций), определения кастомных атрибутов проекта (GUID-ключи резолвятся в
имена и подписи опций) и конфигурации прогонов. Ответ — та же сводка, что и у
импорта файла, плюс массив warnings для некритичных проблем (например,
старый сервер без эндпойнта атрибутов).
Панель результата оставляет полный список предупреждений и ошибок доступным
для проверки. Если часть исходных данных ещё требует переноса, ответ содержит
warningCode: "source_reconciliation_pending" и unmappedCounts, а панель
показывает понятное сообщение на выбранном языке. Для проекта только с кейсами
без неперенесённых данных это сообщение не выводится.

Важно:

• Токен используется только для этой выгрузки — он нигде не сохраняется,
  не логируется и не возвращается в ответе.
• Необязательные поля тела: "createPlan": true сразу собирает тест-план из
  импортированных кейсов, "planName" задаёт его имя.
• Большие проекты выгружаются постранично; одна выгрузка ограничена 50 000
  рабочих элементов. Если проект превышает лимит, один из найденных элементов
  не читается или общее число элементов меняется во время выгрузки, импорт
  останавливается до записи кейсов. Исправьте ошибку источника и повторите
  выгрузку: неполный каталог не выдаётся за успешный импорт.
• Повторный импорт сопоставляет автоматизированные кейсы по первому внешнему
  ID, а ручные — по ID проекта и рабочего элемента. Переименование сохраняет
  существующий целевой кейс; разные исходные кейсы с одинаковым названием
  остаются отдельными. Старые данные без ID рабочего элемента сопоставляются по имени.

Или вызовите эндпойнт напрямую:

curl -X POST http://127.0.0.1:5770/api/v1/namespaces/default/tcm/import/testit \
  -H "Authorization: Bearer $MOCKARTY_API_TOKEN" \
  -H "Content-Type: application/json" \
  --data-binary @testit-export.json

Ответ:

{
  "created": 124,
  "updated": 6,
  "placed": 118,
  "configsCreated": 3,
  "failed": 2,
  "errors": [
    "work item 91f3…: empty name"
  ]
}

Аутентификация и права. Передавайте API-токен Mockarty как
Authorization: Bearer <token>. Эндпойнт требует право test_case:write и
функцию TCM. Импорт затрагивает только пространство имён из пути URL.

Что импортируется

• Секции → папки. Дерево секций TestIT восстанавливается (осиротевшие и
  циклические секции обрабатываются защитно, никогда не отбрасываются), и кейсы
  размещаются в соответствующей папке. Отсутствующая секция просто помещает кейс
  в корень.
• Рабочие элементы → кейсы. Тест-кейсы и чек-листы становятся кейсами.
  Общие шаги (shared steps) пропускаются (они встраиваются в ссылающиеся на них
  кейсы).
• Приоритет отображается на четыре уровня Mockarty: Lowest/Low → low,
  Medium → medium, High → high, Highest → critical (неизвестные значения — по
  умолчанию medium).
• Теги и описание переносятся. Внешние задачи (Jira и т. п.)
  и ссылки рабочего элемента из карточки источника становятся внешними
  ссылками кейса. ID и метаданные исходной задачи хранятся отдельно для
  последующей сверки. Проект со связанными задачами всё же следует сверить после импорта.
• Атрибуты → пользовательские поля, разрешённые без потерь: ключи атрибутов
  (в TestIT они хранятся как GUID) превращаются в человекочитаемые имена, а
  значения типа «опции» (хранятся как GUID опций) — в их названия. Тип
  атрибута сохраняется. Структурные значения доступны для последующего
  сопоставления; в карточке значения показаны в читаемом виде, а сведения об
  источнике отделены от пользовательских полей. См.
  Пользовательские поля TCM.
• Названия кейсов и шаги: разметка в названии Test IT превращается в
  читаемое имя кейса. Содержимое шага остаётся форматированным, а его краткий
  заголовок показывается обычным текстом — теги не попадают в дерево и список шагов.
• Параметры → пользовательские поля. Параметры итераций
  параметризованного рабочего элемента становятся типизированными полями
  param:<имя>, поэтому привязка сохраняется на кейсе.
• Конфигурации → tcm_configurations. Каждая конфигурация тест-рана TestIT
  (матрица browser/OS/env) импортируется как конфигурация Mockarty. Её UUID из
  TestIT сохраняется в external_id конфигурации, поэтому последующий
  results upload с тем же UUID попадает в импортированную конфигурацию, а не
  оставляет прогон «Unspecified».
• Идентичность автотеста. Первый externalId автотеста рабочего элемента
  становится внешним полным именем кейса, поэтому повторный импорт или
  последующая синхронизация обнаружения / внешний прогон
  попадают в тот же кейс.

При повторном импорте пользовательские поля сливаются — значения, добавленные
вручную в UI, сохраняются; перезаписываются только ключи, которые несёт импорт.

Живая выгрузка теперь читает исходные планы, наборы, тестовые точки, прогоны,
подробные результаты, доступные версии кейсов, историю изменений и комментарии
до импорта кейсов. Если чтение одного из этих разделов не удалось, кейсы не
импортируются: устраните ошибку источника и повторите запрос. Некоторые
серверы Test IT отвечают 404 на список версий, хотя история изменений есть.
Тогда выгрузка сохраняет историю и доступные снимки версий, а оставшийся
пробел записывает для сверки.

Для исторического результата выгрузка сверяет ID и номер исходной версии кейса
с сохранённым снимком. Она копирует упомянутые изображения и файлы, затем
сравнивает ID и содержимое шагов с версией Mockarty того же номера. Если
содержимое отличается, выгрузка сохраняет отдельную историческую версию,
не меняя текущий кейс. Повторная выгрузка использует ту же версию; изменение
исходного содержимого при прежнем ID останавливает импорт для проверки.
Отсутствующий ID исходной версии или определение общего шага, необходимое
для исторического результата, остаётся ожидающим сверки. Результат версии 1 не привязывается к текущей
версии 2 только потому, что это один и тот же кейс. После точной привязки
версии и проверки поддерживаемого конечного статуса результата выгрузка
создаёт прогон кейса на исторической версии. Она переносит лишь
исходы шагов, которые действительно есть в Test IT: комментарий к шагу сам
по себе не превращается в пройденный шаг. Если Test IT не передал время
начала, в прогоне записывается, какое доступное исходное время использовано.
Повторная выгрузка использует тот же прогон, а исправления результата
сохраняются как ревизии без перезаписи локальных изменений.

Результат автотеста без тестовой точки может появиться в отдельном прогоне
Test IT. Если у него есть корректный ID автотеста, выгрузка сохраняет его в
отчёте как ожидающий сверки: она не создаёт вымышленную точку, версию кейса
или прогон кейса Mockarty. Результат с исходами внутри ссылки на общий шаг
тоже остаётся ожидающим, пока не сопоставлены исходы каждого вложенного шага.
Видимый родительский прогон сам по себе не означает, что эти исходы перенесены.
Проверьте ожидающие элементы перед переходом команды.

Эти исходные записи доступны для сверки миграции. Если все точки исходного
тест-плана сопоставлены с импортированными кейсами или чек-листами, выгрузка
создаёт запускаемый план Mockarty с устойчивой связью с кейсами. Исходные
статус и даты плана, атрибуты, дерево наборов, статусы точек и конфигурации
ещё требуют проверки; план остаётся в состоянии pending в отчёте
миграции. Пустой план или план с несопоставленными точками остаётся pending
без создания неполного плана. Поддерживаемые исторические результаты и их
файлы после проверки checksum привязываются к прогонам кейсов Mockarty;
исходные комментарии к шагам сохраняются в метаданных результата. Исходная
завершённая попытка тест-плана с одним поддерживаемым результатом на точку
получает постоянный прогон плана Mockarty. В его снимок входят только точки
с реальными результатами; при повторной выгрузке те же прогоны кейсов
связываются с этими точками. Дополнительные метаданные исходного прогона,
неподдерживаемые вложенные исходы шагов и самостоятельные комментарии к
обсуждению ещё требуют проверки миграции.
Полный каталог автотестов тоже ещё требует переноса.
Проверьте счётчики сверки до перехода команды на Mockarty.

Дедупликация

При повторном импорте применяются следующие правила сопоставления:

• Автоматизированные элементы дедуплицируются по их внешнему полному
  имени (externalId автотеста).
• Ручные элементы с исходным ID сопоставляются по ID проекта и элемента.
  Переименование обновляет тот же кейс. Разные исходные кейсы с одинаковыми
  именами остаются отдельными: если имя занято, импортируемый кейс получает
  постоянный суффикс [Test IT …]. Исходное имя и ID сохраняются в
  пользовательских полях кейса mockarty:testit:*.
• Старые входные данные без ID элемента по-прежнему сопоставляются по точному имени.

Существующий одноимённый кейс без привязки к источнику не принимается автоматически.
Это относится и к старым импортам, сделанным до сохранения исходных ID. Проверьте
такие записи перед новым импортом: старый непривязанный кейс может остаться рядом
с новым привязанным. Исходные атрибуты не должны использовать зарезервированный
префикс полей mockarty:testit:. Необязательный создаваемый план включает именно
кейсы этого импорта, даже если их исходные имена совпадают.

Переданные шаги обновляются при повторном импорте. Одинаковые шаги не создают
новую версию; явный пустой список очищает их, а отсутствие списка оставляет
существующие шаги без изменений. Неразрешимая ссылка на общий шаг приводит
к ошибке этого кейса, без молчаливой потери содержимого. Если сохранение шагов
завершилось ошибкой после создания кейса, повторите импорт: привязка к
источнику сохранена для повторной попытки.

8. Troubleshooting

401 на каждый вызов. Проверьте токен:
mockarty-cli testit auth login — выводит пространства имён Mockarty,
доступные токену Mockarty. Если значение начинается с PrivateToken или
Bearer , CLI отрежет эту часть; токен Test IT от этого не станет токеном
Mockarty.

configuration_id must be a UUID. TestIT иногда выдаёт UUID в
фигурных скобках ({abc-...}); CLI принимает оба варианта, но
пользователь должен сгенерировать валидный UUID через
testit configuration generate.

Cross-tenant результаты. Namespace’ы Mockarty 1:1 соответствуют
проектам TestIT. Токен, привязанный к team-a, не может грузить в
team-b — вызов вернёт 403.

9. См. также

• Справочник CLI-команд
• Интеграция с Allure — родственный
  адаптер; тот же эндпоинт /tcm/external-runs под капотом
• Синхронизация обнаружения тестов — регистрация всего инвентаря из CI
• Пользовательские поля TCM
• Миграция с Postman / Newman