К основному содержанию
скилл CX Codex

ns-backend-tests — скилл для Claude Code: PHPUnit тесты в Docker

Скилл ns-backend-tests для написания и запуска unit- и интеграционных тестов PHPUnit прямо в IDE. Работает только в Docker-контейнере, помогает быстро покрыть тестами новый Laravel-проект или переписать существующие тесты.

Apache-2.0 151 установок обновлён 2026-10-24

Установить в Claude Code · Через Skills CLI (Vercel) Все способы и платформы ↓
npx skills add nextstage-brasil/skills --skill ns-backend-tests -a claude-code
Открыть на GitHub

Что делает 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-code

2Вручную: положить файлы

~/.claude/skills/ns-backend-tests/SKILL.md

Папка скилла целиком; для одного проекта — .claude/skills/ns-backend-tests/

По шагам, с командами для каждой платформы: Как установить скилл в 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

Похожие скиллы

Все скиллы по теме «Тесты и QA» →
laravel-testing Laravel Community Скилл laravel-testing учит ассистента писать тесты для Laravel 13 на Pest 4 или PHPUnit 12 с учётом фабрик моделей и моков сервисов. CX Codex +1 1 000установок functional-tests dev-toolings Скилл functional-tests помогает писать функциональные тесты контроллеров и сервисов Symfony на базе WebTestCase, KernelTestCase и DAMA rollback. CX Codex +1 ★ 234звёзд репо backend-development mrgoonie Скилл backend-development для Claude Code направляет агента по проектированию API, схем БД, аутентификации и CI/CD с нуля до продакшена. CX Codex +1 2 400установок wp-env WordPress Скилл wp-env для Claude Code настраивает и запускает локальную среду WordPress через Docker. Он включается и при отладке уже существующей конфигурации .wp-env.json. CX Codex +1 1 200установок php-pro https://github.com/Jeffallan Скилл php-pro задаёт правила разработки на PHP 8.3+ для Laravel и Symfony: включает strict_types, анализ в PHPStan на уровне 9 и тесты PHPUnit или Pest. CX Codex +1 16 400установок laravel-tdd affaan-m Скилл laravel-tdd помогает писать тесты для Laravel через TDD на PHPUnit или Pest. Скилл даёт шаблоны фабрик моделей, проверок Eloquent и HTTP-тестов. CX Codex +1 6 800установок

Из того же набора20

Весь набор →
ns-investigator Скилл ns-investigator для Claude Code анализирует стек-трейсы, логи и упавшие тесты, находит корневую причину и предлагает минимальный фикс без реализации. CX Codex +1 153установок ns-frontend-design Скилл ns-frontend-design для Claude Code, Codex, Cursor и других агентов — строит production-интерфейсы с типографикой, иерархией и анимацией. Срабатывает на страницах, компонентах, дашбордах, формах и KPI-аналитике. CX Codex +1 153установок ns-autonomous Скилл ns-autonomous для Claude Code, Codex, Cursor, Copilot и Gemini CLI, который берёт локальный план или произвольный текст и выполняет его автономно в изолированном worktree. CX Codex +1 152установок ns-e2e-tests Скилл ns-e2e-tests задаёт структуру Cypress E2E-тестов, команд и сценариев для разных устройств. Нужен при создании и рефакторинге тестов. CX Codex +1 151установок ns-docs-writer Скилл ns-docs-writer для Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI и OpenCode, который пишет человекочитаемую документацию проекта: README, руководства в docs/, ранбуки и инструкции для контрибьюторов. CX Codex +1 151установок ns-coder Скилл ns-coder реализует небольшие изменения в коде: исправления, рефакторинг, скрипты и миграции. Он пригодится для разовой задачи вне многоэтапной разработки по SDD. CX Codex +1 151установок ns-reviewer Скилл ns-reviewer проверяет качество кода перед PR: оценивает SOLID, чистоту кода, производительность, безопасность и тестируемость. Одобрит только при оценке 10, оценка 9 означает отклонение. CX Codex +1 140установок ns-living-spec Скилл ns-living-spec синхронизирует спецификации проекта в каталоге docs/specs/ с кодом. Обновляет доменные требования после закрытия версий или подтверждённых ревью. CX Codex +1 140установок

Спонсоры проекта

Компании, которые помогают держать аналитику открытой