Skip to main content
skill CX Codex

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

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add nextstage-brasil/skills --skill ns-backend-tests -a claude-code
Open on GitHub

What 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/users endpoint 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-code

2Manually: put the files in place

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

Copy the whole skill folder; for one project use .claude/skills/ns-backend-tests/

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

Similar skills

All skills for Testing and QA →

From the same set20

The whole set →
ns-investigator The ns-investigator skill for Claude Code reads stack traces, logs and failing tests, identifies the root cause and proposes a minimal fix without implementing it. CX Codex +1 153installs ns-frontend-design ns-frontend-design — a skill for Claude Code, Codex, Cursor and other agents that builds production UI with deliberate typography, hierarchy and motion. Activates on pages, components, dashboards, forms and analytics views. CX Codex +1 153installs ns-autonomous ns-autonomous — a skill for Claude Code, Codex, Cursor, Copilot and Gemini CLI that takes a local plan or pasted text and runs it autonomously inside an isolated worktree. CX Codex +1 152installs ns-e2e-tests The ns-e2e-tests skill structures Cypress end-to-end work across devices and keeps tests in a separate project. Use it when adding or refactoring specs. CX Codex +1 151installs ns-docs-writer ns-docs-writer — a skill for Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, and OpenCode that produces human-facing project docs: README files, docs/ guides, runbooks, and contributor markdown. CX Codex +1 151installs ns-coder ns-coder handles focused code changes such as fixes, small refactors, scripts, and migrations. Use it for ad-hoc work outside a multi-stage SDD handoff. CX Codex +1 151installs ns-reviewer ns-reviewer grades code changes against SOLID principles, clean code patterns, performance, security, and testability. Approves only at score 10; score 9 triggers rejection. CX Codex +1 140installs ns-living-spec ns-living-spec maintains domain specifications in docs/specs/ after version releases or approved reviews. Turns diffs and release artifacts into functional truth. CX Codex +1 140installs

Project sponsors

Companies that keep this analytics open