x-test-matrix

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.go
• features/
• 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 — обязательный шаблон итогового документа