| name | x-test-matrix |
| description | Применяй когда нужно создать или актуализировать `docs/TEST-MATRIX.md` в сервисном репозитории: инвентаризация test layers, feature inventory, покрытие runner-ами, перечень test cases, сводная таблица и секция code coverage. Формат должен повторять project template из `assets/TEST-MATRIX.md.tmpl` без самовольной переработки структуры |
| compatibility | Go or frontend monorepo/service repo with unit, BDD and smoke tests |
Матрица тестирования
Когда применять
Используй этот скилл, когда нужно:
- создать
docs/TEST-MATRIX.md с нуля
- актуализировать матрицу после добавления, удаления или переноса тестов между слоями
- синхронизировать документацию тестового ландшафта перед review, release или handoff
Не применяй для:
- локальной правки одного теста без изменения тестового ландшафта
- toolchain-only репозиториев, где нет прикладного сервиса и матрица тестирования не является артефактом проекта
Для level85 этот скилл создаётся как reusable bundle, но сам docs/TEST-MATRIX.md в этом репозитории заводить не нужно.
Главный принцип
Формат docs/TEST-MATRIX.md должен повторять шаблон из assets/TEST-MATRIX.md.tmpl.
Не изобретай собственную структуру, не меняй порядок разделов и не схлопывай крупные секции "для краткости".
Если в целевом репозитории уже есть docs/TEST-MATRIX.md, обновляй его в существующем формате только если он уже совпадает с этим шаблоном или близок к нему.
Если формат расходится существенно, сначала обсуди с пользователем, нужно ли мигрировать документ к шаблону целиком.
Workflow
1. Сначала проверь, нужен ли документ в этом репозитории
Матрица нужна, когда в репозитории есть прикладной сервис с понятными test layers:
internal/**/*_test.gofeatures/- API BDD runner: monorepo
backend/test/bdd/, backend-only test/bdd/
- browser BDD runner: monorepo
frontend/test/bdd/, frontend-only test/bdd/
test/smoke/
Если репозиторий содержит только toolchain, skills, CI или вспомогательные scripts, не создавай docs/TEST-MATRIX.md автоматически.
2. Собери инвентарь тестовых слоёв
Определи:
- какие слои реально существуют
- где лежат тестовые файлы
- какие пакеты покрыты unit-тестами
- какие сценарии есть в
features/
- какие сценарии покрыты API BDD runner-ом
- какие сценарии покрыты browser BDD runner-ом
- какие smoke-проверки есть
Сначала считай фактические файлы и каталоги, а уже потом формулируй выводы.
3. Заполни секцию Контекст
Кратко зафиксируй:
- что это за сервис
- основные внешние интерфейсы
- основные инфраструктурные зависимости
- укрупнённую архитектуру по пакетам
- структуру
features/ и runner-ов по слоям
Это не маркетинговое описание и не README.
Нужен плотный технический контекст, который помогает читать остальную матрицу.
4. Заполни покрытие по пакетам
Сделай краткую таблицу:
- пакет
- есть ли unit-тесты
- есть ли покрытие через API BDD, browser BDD или smoke
Используй её как быстрый индекс перед детальными разделами.
5. Заполни детальные разделы по слоям
Для каждого реально существующего слоя:
- выдели отдельный раздел
- перечисли файлы
- зафиксируй test cases таблицами
ID | Тест | Статус
- для BDD не считай наличие
.feature автоматическим покрытием runner-а
- в monorepo отдельно показывай execution coverage по
@api и @browser
- в backend-only/frontend-only показывай coverage единственного runner-а без execution tags
Если слой отсутствует, не выдумывай для него фиктивный список тестов.
Но структура итогового документа должна оставаться узнаваемой и близкой к шаблону.
6. Сохраняй стабильные идентификаторы
ID должны быть:
- стабильными между обновлениями
- человеко-читаемыми
- согласованными внутри слоя
Предпочтительный паттерн:
- package/layer prefix (
CFG, CTRL, REPO, SVC, GQL, GRPC)
- для unit допустим
-U-
- для API BDD
API-BDD-
- для browser BDD
BROWSER-BDD-
- для smoke
SMOKE-
Не перенумеровывай существующие ID без необходимости.
Если добавляешь новый тест между двумя старыми, предпочитай новый номер в хвосте, а не массовую перенумерацию документа.
7. Собери сводную таблицу
После детальных разделов добавь агрегированную таблицу по пакетам и слоям.
Она должна давать быстрый ответ:
- сколько unit-тестов есть по каждому пакету
- где покрытие идёт через API BDD, browser BDD или smoke
8. Добавь секцию покрытия кода
Запусти task cover. Выход:
- stdout: общий процент покрытия (
📊 Общее покрытие кода: NN.N%)
.coverage/.txt — coverage profile (формат go tool cover)
Для per-package таблицы парси .coverage/.txt через go tool cover -func=.coverage/.txt — каждая строка содержит file:line: funcName percent%, последняя строка — total: (statements) NN.N%.
Для секции coverage зафиксируй команду task cover, общий процент и таблицу per-package.
Если coverage данные недостоверны, не выдумывай числа.
В таком случае оставь секцию, но явно напиши, что покрытие не снято.
9. Проверь документ перед завершением
Проверь:
- порядок разделов совпадает с шаблоном
- названия пакетов и файлов совпадают с реальной структурой репозитория
- количество тестов в сводной таблице не противоречит детальным разделам
- не смешаны unit, feature inventory, API BDD, browser BDD и smoke
- нет ссылок на чужие сервисы, чужие пакеты и внешний эталонный репозиторий
Не делай
- не ссылайся на внешний пример как на источник истины
- не придумывай тесты, которых нет в коде
- не превращай документ в narrative-отчёт вместо матрицы
- не меняй формат документа самовольно, если задача была "обновить матрицу"
- не создавай
docs/TEST-MATRIX.md в toolchain-only репозитории без явного запроса пользователя
Полезные ресурсы
assets/TEST-MATRIX.md.tmpl — обязательный шаблон итогового документа
