ns-backend-tests — Claude Code skill: PHPUnit in Docker
ns-backend-tests — a skill for writing and running PHPUnit unit and integration tests directly in your IDE. Runs only in Docker containers, helping you quickly test a new Laravel project or rewrite existing tests.
Apache-2.0 151 installs updated 2026-10-24
npx skills add nextstage-brasil/skills --skill ns-backend-tests -a claude-codeWhat ns-backend-tests does
ns-backend-tests integrates the full PHPUnit workflow into your IDE: it finds or creates a test structure, reads the code under test, writes unit and feature tests, runs them in a Docker container with a 120-second timeout, and reports results. The skill automatically loads testing rules from .nextstage-harness/rules/ if present and follows your project's layout—searching for phpunit.xml in backend/, the repo root, or alongside composer.json.
On greenfield projects (no existing test structure), the skill creates a minimal setup: phpunit.xml, tests/TestCase.php, and folders for tests/Unit/ and tests/Feature/. Unit tests by default skip the database, make no network calls, and avoid external services—mocks and fixtures only. Feature tests verify HTTP behavior, authentication, and cross-tenant access. Tests requiring real external services or LLMs are marked with the live group and excluded from the default run.
Execution is only inside Docker—the host is not supported. The skill expects the container to be documented in docs/context/stack-confirmed.md or architecture-rules.md; if missing, it asks once. If a test hangs beyond 120 seconds, the skill cancels and reports the blocker.
What it helps with
- write unit tests for a Laravel Service or FormRequest
- run PHPUnit in an isolated environment without touching the host
- bootstrap a test structure on a new project
- extend existing tests without duplication
- track which files test each component
Example prompts for the agent
- Write unit tests for UserService with mocked dependencies
- Create feature tests for the
/api/usersendpoint with 401 and 403 checks - Run PHPUnit in the container, filtering to a single test class
How to install ns-backend-tests
1Skills CLI (Vercel)
npx skills add nextstage-brasil/skills --skill ns-backend-tests -a claude-code2Manually: put the files in place
~/.claude/skills/ns-backend-tests/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/ns-backend-tests/
1Skills CLI (Vercel)
npx skills add nextstage-brasil/skills --skill ns-backend-tests -a codex2Manually: put the files in place
.agents/skills/ns-backend-tests/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add nextstage-brasil/skills --skill ns-backend-tests -a cursor2Manually: put the files in place
.cursor/skills/ns-backend-tests/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install nextstage-brasil/skills skills/ns-backend-tests2Manually: put the files in place
.github/skills/ns-backend-tests/SKILL.md1Skills CLI (Vercel)
npx skills add nextstage-brasil/skills --skill ns-backend-tests -a gemini-cli2Platform CLI
gemini skills install https://github.com/nextstage-brasil/skills --path skills/ns-backend-testsManually: put the files in place
.devin/skills/ns-backend-tests/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add nextstage-brasil/skills --skill ns-backend-tests -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about ns-backend-tests
How do I install ns-backend-tests for Claude Code?
Run npx skills add nextstage-brasil/skills --skill ns-backend-tests -a claude-code, then open ~/.claude/skills/ns-backend-tests/SKILL.md.
What does ns-backend-tests do?
The skill writes and runs PHPUnit tests in a Docker container. It finds or creates a test structure, loads rules from your project, and executes tests with a 120-second timeout, preventing hangs.
Why does ns-backend-tests require Docker?
Docker ensures a clean, isolated environment with no impact on your host, isolates the database and cache, and lets you run tests in the same setup as production. PHPUnit does not run on the host.
Source text
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