@rizias/tt-testops

Читающий шлюз к Allure TestOps. Достаёт тест-кейсы и отдаёт их как Markdown или самодостаточную HTML-страницу, попутно отмечая кейсы, которые пора переписать. Командная строка.

[!IMPORTANT] Инструмент никогда и ничем не пишет в TestOps. Любая команда — только чтение.

Полный список возможностей — docs/features.md.

Оглавление

• Установка
• Быстрый старт
• Настройка
• Команды
• Формат вывода
• Классы ошибок
• Скилл для агента
• Чего инструмент не делает

Установка

Нужен Node.js 22+.

npm install --global @rizias/tt-testops
tt-testops init
tt-testops config init

config init создаёт раскладку настроек в ~/.tt-testops/ и заготовки profile.json и credentials.json. Как их заполнить и что значит каждое поле — settings.md.

Быстрый старт

Когда настройки заполнены (см. Настройка), один кейс на экран:

tt-testops case <ид-кейса>

Настройка

1. Подготовьте настройки — агент сделает это сам, либо вручную:

   tt-testops config init

   В ~/.tt-testops/profiles/default/profile.json впишите адрес сервера в servers.testops.baseUrl.

2. В TestOps откройте свой профиль, выберите «API-токены», создайте новый токен и скопируйте его.

3. Вставьте токен в ~/.tt-testops/profiles/default/credentials.json (Windows: C:\Users\<вы>\.tt-testops\profiles\default\credentials.json):

   { "testops": { "token": "<токен>" } }

4. Проверьте: tt-testops config — токен показан как «задан». Каждое поле показано со значением и источником (flag, env, file, default); секрет testops.token — только признаком «задан» или «не задан», само значение команда не печатает никогда.

| Поле | Что меняет | Переменная | Умолчание | Где взять значение | |---|---|---|---|---| | description | заметка о контуре | — | — | по желанию | | servers.testops.baseUrl | адрес сервера TestOps | TT_TESTOPS_SERVER_TESTOPS_BASE_URL | обязателен | адресная строка браузера | | testops.token (в credentials.json) | API-токен | TT_TESTOPS_SERVER_TESTOPS_TOKEN | обязателен | TestOps: профиль → «API-токены» → создать новый | | defaultProject | проект по умолчанию, когда нет --project | TT_TESTOPS_DEFAULT_PROJECT | — | номер проекта в адресе его страницы | | projects | номер → имя, чтобы писать --project WEB | нет | — | tt-testops projects | | people | учётка сервера → как показывать | нет | — | по желанию | | trees | рабочее дерево разделов проекта — названием, как в интерфейсе TestOps: { "<ид>": "<название>" }; "none" — путь не нужен. Деревьев несколько, а выбора нет — case и list не начинают выгрузку | нет | — | tt-testops trees | | formatFile | путь к JSON-профилю оформления вывода | TT_TESTOPS_FORMAT_FILE | — | см. format.md |

Профиль выбирается флагом --profile, переменной TT_TESTOPS_PROFILE или полем profile общего файла config.json, иначе — default. Подкоманды config, каталоги, примеры profile.json/credentials.json — settings.md.

Команды

| Команда | Что делает | |---|---| | case <id> | один кейс по ID → Markdown (или --format html) | | list <запрос> | все кейсы по запросу → Markdown каждого + сводка проблемных | | count <запрос> | сколько кейсов подходит под запрос — одно число, без выгрузки | | fields [имя] | без имени — обзор полей и слоёв проекта; с именем — его значения и число кейсов; --find <текст> — поиск по проекту | | link <запрос> | ссылка на фильтр TestOps по запросу — открыть в браузере или переслать коллеге | | projects | согласованный список проектов из конфигурации и что есть на сервере сверх него | | trees | деревья разделов проекта: из каких полей собраны и какое сейчас рабочее | | attachments | хранилище вложений профиля: число файлов, объём, срок сессии | | attachments <id> | напечатать пути файлов вложений кейса; --out <каталог> — скопировать их туда | | attachments clear | удалить вложения, сессии и списки деревьев профиля | | config [init\|use\|profiles] | что действует сейчас; создать настройки, сменить профиль, список | | setup [путь] | как поставить инструмент именно в этот проект; ничего не меняет | | init [путь] | разложить скилл, чтобы агент знал про инструмент; спросит, куда именно | | update | обновить пакет до последней опубликованной версии через npm | | --version | версия установленного пакета |

Опции — --profile и --out у всех команд; --project, --limit, --format markdown|html|raw, --no-marks, --tree, --rql/--rql-file, --find, --text — каждая у своих команд, флаг не той команды и незнакомый флаг — ошибка. Разбор каждой команды с примерами, несколько проектов в одном вызове и язык AQL — commands.md и aql.md.

Запрос — AQL или ссылка на фильтр TestOps с любыми его условиями; --text <фраза> добавляет отбор по содержимому кейса. Подробно — commands.md.

Формат вывода

Markdown кейса — стандартный CommonMark: жирная шапка # **{имя}** (ID: {номер}), под ней строки карточки, литерал Нет шагов, вложенность шагов отступом. Кейсы в пачке идут подряд, каждый с шапки.

Кейс без своих шагов показывает шаги тестового результата под строкой > ⚠️ **Нет шагов** (сценарий взят из автотеста) — format.md.

# **Проверка входа** (ID: 10001)
- **Адрес в TestOps:** <адрес кейса>

### Сценарий
1. Открыть страницу входа

Вложения кейса — картинки и файлы — после case и list лежат файлами в хранилище профиля: attachments/case-<ид кейса>/<ид вложения>.<расширение>. Ссылка в Markdown ведёт на файл, адрес TestOps стоит в ней заголовком: ![](<путь> "<адрес>"). Вложение, которое не скачалось, остаётся ссылкой на адрес TestOps.

--format html — самодостаточная страница. Форматы, HTML-страница и свой профиль оформления — format.md.

Классы ошибок

Результат идёт в стандартный вывод, диагностика — в служебный вывод.

| Класс | Когда | Что происходит | |---|---|---| | Код возврата | любой вызов | 0 — успех; 1 — любая ошибка, включая ошибку настроек, с сообщением о причине | | Запрос AQL | синтаксис не разобран, поле или значение не найдено | сообщение называет операторы и реальные поля проекта; на опечатку — похожее написание | | Несколько проектов | число --project и число --rql/--rql-file не совпало | отказ с обоими числами, ничего не выгружается | | Настройки | битый или невалидный formatFile | ошибка называет путь и причину, ещё до обращения к TestOps | | Сеть и сервер TestOps | первый 401 | однократное восстановление сессии |

Скилл для агента

Без скилла агент не знает про инструмент и лезет в API TestOps с вашим токеном. Скилл описывает команды и прямо запрещает обход. Скилл едет вместе с пакетом: папка skills/tt-testops/ — SKILL.md и дополнения к скиллу в references/, подробности, которые агент читает по необходимости:

• settings.md — настройки, профили, переменные окружения;
• commands.md — все команды и флаги;
• aql.md — язык запросов;
• format.md — оформление вывода.

tt-testops init                      # спросит, куда ставить, в текущем проекте
tt-testops init C:\путь --for claude # без вопроса: только .claude/skills/

| Каталог | Кто читает | |---|---| | .claude/skills/ | Claude Code | | .agents/skills/ | Codex, OpenCode |

Команда показывает полный список путей и до подтверждения не создаёт ни одного файла; во все каталоги сразу не ставит никогда. Глобальной установки нет — скилл живёт в проекте; путь к домашней папке команда отклоняет. Места установки запоминаются в ~/.tt-testops/skills-registry.json; после обновления пакета копии обновляются сами при следующем запуске любой команды. init ставит папку скилла целиком, дополнения обновляются вместе с программой. Свои файлы кладите прямо в папку скилла у агента: программа их не трогает, агент их находит.

О новой версии пакета инструмент сообщает раз в сутки при выводе в терминал; обновление — tt-testops update.

Чего инструмент не делает

• Не пишет в TestOps ничем и никогда — любая команда только читает.
• Не ставит скилл агента глобально: устанавливает только в текущий проект и до подтверждения не создаёт ни одного файла.
• Не трогает файлы, добавленные рядом со скиллом вручную.