ns-backend-tests — скилл для Claude Code: PHPUnit тесты в Docker
Скилл ns-backend-tests для написания и запуска unit- и интеграционных тестов PHPUnit прямо в IDE. Работает только в Docker-контейнере, помогает быстро покрыть тестами новый Laravel-проект или переписать существующие тесты.
Apache-2.0 151 установок обновлён 2026-10-24
npx skills add nextstage-brasil/skills --skill ns-backend-tests -a claude-codeЧто делает ns-backend-tests
ns-backend-tests встраивает в IDE полный цикл работы с PHPUnit: находит или создаёт структуру тестов, читает код под тестирование, пишет unit- и feature-тесты, запускает их в Docker-контейнере с таймаутом 120 секунд и выводит результат. Скилл автоматически загружает правила тестирования из .nextstage-harness/rules/, если они есть, и следует архитектуре проекта — искать phpunit.xml в backend/, в корне репо или рядом с composer.json.
При работе на зелёном поле (нет структуры тестов) скилл создаёт минимальный набор: phpunit.xml, tests/TestCase.php, папки tests/Unit/ и tests/Feature/. Unit-тесты по умолчанию не трогают БД, не ходят в сеть и не обращаются к внешним сервисам — используются mock'и и фикстуры. Feature-тесты проверяют HTTP, авторизацию, кросс-тенантность. Тесты на реальные внешние сервисы или LLM помечаются группой live и исключаются из дефолтного запуска.
Запуск возможен только внутри Docker-контейнера — хост не поддерживается. Скилл требует, чтобы контейнер был задокументирован в docs/context/stack-confirmed.md или architecture-rules.md; если документация отсутствует, спрашивает один раз. Если тест зависает дольше 120 секунд, скилл отменяет запуск и сообщает о блокере.
Какие задачи решает
- написать unit-тесты для Service или FormRequest в Laravel
- запустить PHPUnit в изолированной среде без загрязнения хоста
- создать структуру тестов на новом проекте с нуля
- расширить существующие тесты без дублирования
- отследить, какие файлы тестируют каждый компонент
Примеры запросов агенту
- Напиши unit-тесты для UserService с mock-зависимостями
- Создай feature-тесты для API
/api/usersс проверкой 401 и 403 - Запусти PHPUnit в контейнере с фильтром на один тестовый класс
Как установить ns-backend-tests
1Через Skills CLI (Vercel)
npx skills add nextstage-brasil/skills --skill ns-backend-tests -a claude-code2Вручную: положить файлы
~/.claude/skills/ns-backend-tests/SKILL.mdПапка скилла целиком; для одного проекта — .claude/skills/ns-backend-tests/
1Через Skills CLI (Vercel)
npx skills add nextstage-brasil/skills --skill ns-backend-tests -a codex2Вручную: положить файлы
.agents/skills/ns-backend-tests/SKILL.mdДля всех проектов — ~/.agents/skills/
1Через Skills CLI (Vercel)
npx skills add nextstage-brasil/skills --skill ns-backend-tests -a cursor2Вручную: положить файлы
.cursor/skills/ns-backend-tests/SKILL.mdCursor читает и .agents/skills/, и .claude/skills/
1GitHub CLI
gh skill install nextstage-brasil/skills skills/ns-backend-tests2Вручную: положить файлы
.github/skills/ns-backend-tests/SKILL.md1Через Skills CLI (Vercel)
npx skills add nextstage-brasil/skills --skill ns-backend-tests -a gemini-cli2Командой платформы
gemini skills install https://github.com/nextstage-brasil/skills --path skills/ns-backend-testsВручную: положить файлы
.devin/skills/ns-backend-tests/SKILL.mdСтарый путь .windsurf/skills/ тоже читается
Через Skills CLI (Vercel)
npx skills add nextstage-brasil/skills --skill ns-backend-tests -a opencodeClaude.ai
Упакуйте папку в zip и загрузите в Settings → Capabilities → Skills
По шагам, с командами для каждой платформы: Как установить скилл в Claude Code: пять способов
Вопросы о ns-backend-tests
Как установить ns-backend-tests в Claude Code?
Выполни команду npx skills add nextstage-brasil/skills --skill ns-backend-tests -a claude-code, затем открой ~/.claude/skills/ns-backend-tests/SKILL.md.
Что делает ns-backend-tests?
Скилл пишет и запускает PHPUnit тесты в Docker-контейнере. Находит или создаёт структуру тестов, загружает правила из проекта и выполняет тесты с таймаутом 120 секунд, не допуская зависаний.
Почему ns-backend-tests требует Docker?
Docker гарантирует чистую среду без влияния на хост-машину, изолирует БД и кэш, и позволяет запускать тесты внутри той же конфигурации, что и production. На хосте PHPUnit не запускается.
Исходный текст
SKILL.md · Apache-2.0
---
name: ns-backend-tests
description: "(NS) PHPUnit unit/integration in backend package (bootstrap tests/ when missing). Docker-only: phpunit --testdox --stop-on-failure --stop-on-error, 120s. Use when writing/refactoring PHPUnit, unit-test tasks, or scaffolding backend tests on greenfield Laravel/PHP — not when planning test task markdown (ns-spec-driven references/unit-test-task-generator.md)."
license: Apache-2.0
metadata:
author: nextstage-brasil
version: "1.1"
depends:
- ns-harness
---
# Create Backend Tests
Execution-phase PHPUnit implementation. Planning-phase: `ns-spec-driven/references/unit-test-task-generator.md`.
## Session boot
Load `.nextstage-harness/rules/backend-tests-rules.mdc` and `backend-rules.mdc` when present. See `references/backend-testing-architecture.md` for layout, run contract, and bootstrap summary.
## Phase 0 — Resolve or bootstrap backend test root
**Before any test class code**, locate the PHPUnit project or create minimal structure.
### 0.1 — Detect existing tests (brownfield)
Search the repo in this order:
1. `backend/phpunit.xml`
2. `phpunit.xml` at repo root
3. `tests/Unit/` or `tests/Feature/` under the directory that contains `composer.json` with PHPUnit
Record the directory containing `phpunit.xml` as **`{backend_root}`**. All paths below are relative to `{backend_root}`.
### 0.2 — Bootstrap when nothing exists (greenfield)
If backend application code exists (`app/`, `src/`, or equivalent) but no `phpunit.xml` and no `tests/`:
| Rule | Detail |
| ---- | ------ |
| Location | `backend/` when that package exists; else repo root |
| Tree | Per `references/backend-testing-architecture.md` — `phpunit.xml`, `tests/TestCase.php`, `tests/Unit/`, `tests/Feature/` |
| Dependencies | PHPUnit via existing `composer.json` — never add to frontend or unrelated packages |
Then set `{backend_root}` to that directory.
**Forbidden on greenfield:** assuming tests exist, running PHPUnit on the host, or scaffolding tests outside the backend package.
### 0.3 — Post-bootstrap documentation
When `docs/context/stack-confirmed.md` or `architecture-rules.md` exists, add or update the backend test row: `{backend_root}`, docker test container, and the PHPUnit run command from Phase 5.
Do not proceed to Phase 1 until `{backend_root}` is confirmed and `phpunit.xml` is readable.
## Phase 1 — Discovery (before feature code)
1. **Code under test** — read implementation files (Service, FormRequest, Controller, etc.)
2. **Existing tests** — read matching files under `tests/Unit/` and `tests/Feature/`; extend, do not duplicate
3. **Project patterns** — factories, `RefreshDatabase`, response envelope, multitenancy helpers from harness rules
4. **Task contract** — when implementing a unit-test planning task, follow its scenario checklist
## Phase 2 — Write tests
- Unit/feature **default tier:** no HTTP/network to live third parties — fake/fixtures only (see Test tiers in `../../ns-harness/references/docker-and-testing.md`)
- Unit: mock dependencies — no real DB/queue/cache I/O
- Feature: HTTP tests with auth, 401/403, cross-tenant P0 when applicable
- Real external service or real LLM required → PHPUnit **live** group (e.g. `#[Group('live')]`); exclude that group in `phpunit.xml` from default run; record marker + on-demand command in `architecture-rules.md`
- Naming: `{Component}Test.php`, descriptive snake_case method names
- Match module paths: `tests/Unit/Modules/{Domain}/`, `tests/Feature/Modules/{Domain}/`
- **Never** edit assertions to match broken behavior
## Phase 3 — Run (mandatory contract)
See also `../../ns-harness/references/docker-and-testing.md`.
1. Run `docker ps` — confirm the documented **test** container (ask once if undocumented)
2. Execute **inside the test container** at `{backend_root}` workdir — **default suite only** (live group excluded). Never include the live group unless the human asks this run:
```bash
timeout 120 docker exec -w {workdir} {test_container} \
vendor/bin/phpunit --testdox --stop-on-failure --stop-on-error {optional_filter}
```
3. **Timeout:** if the command is killed at 120s (e.g. exit 124), treat the run as **dead/hung** — abort, report blocker, do not silently retry
4. **Never** run `vendor/bin/phpunit` or `phpunit.sh` on the host
Filtered runs (single class or method) use the same flags and timeout.
## Phase 4 — Report
- Pass: list files added/changed
- Fail: first failing test name + assertion from `--testdox` output
- Hung/timeout: state 120s limit exceeded; invoke `ns-investigator` if root cause unclear
## References
| File | When |
| ---- | ---- |
| `references/backend-testing-architecture.md` | Layout, bootstrap, run contract |
| `../ns-spec-driven/references/unit-test-task-generator.md` | Task contract source |
## Related skills
- `ns-spec-driven` `references/unit-test-task-generator.md` — planning tasks
- `ns-investigator` — failing or hung test debugging
- `ns-coder` — ad-hoc fixes outside planned unit-test tasks
© nextstage-brasil · Apache-2.0 · nextstage-brasil/skills