Claude-Code-Game-Studios/CCGS Skill Testing Framework/skills/utility/test-helpers.md

# Skill Test Spec: /test-helpers

## Skill Summary

`/test-helpers [system-name | all | scaffold]` generates test helper files in
the engine's **helper root** — the only place its test runner compiles them:
`tests/helpers/` on Godot, `Assets/Tests/EditMode/Helpers/` on Unity (inside the
`EditModeTests` assembly), `Source/<Module>/Private/Tests/Helpers/` on Unreal. It
writes base assertion and factory helpers (`scaffold`), and a
`[helper root]/[system]_factory.[ext]` per system built from that system's GDD
(`[system-name]` or `all`). No argument runs `scaffold` when no helpers exist,
else `all`. It reads `engine.name`, `engine.language` and `testing.framework`
from `project.yaml` (falling back to `technical-preferences.md`), samples up to
5 existing test files for house style, and section-greps the GDD (Formulas,
Edge Cases, Detailed Rules/Design) rather than reading it whole.

Helpers must assert through the configured framework's API — never bare
`assert()` — and must not extend the framework's test-suite base class. If the
framework's assertion API cannot be confirmed, the skill says so and generates
no helper. It never overwrites an existing helper: it skips it with a message.
After presenting the file list it asks "May I write these helper files to
`[helper root]`?". No director gates apply. Verdict: COMPLETE when helper files
are created.

---

## Static Assertions (Structural)

Checked against the SKILL.md by `/skill-test spec` — no fixture needed.

- [ ] Has required frontmatter fields: `name`, `description`, `argument-hint`, `user-invocable`, `allowed-tools`
- [ ] Has ≥2 phase headings
- [ ] Contains verdict keyword: COMPLETE
- [ ] Contains "May I write" collaborative protocol language before writing helpers
- [ ] Has a next-step handoff (Next Steps: `/test-setup`, `/dev-story`, `/skill-test`)

---

## Director Gate Checks

None. `/test-helpers` is a scaffolding utility. No director gates apply.

---

## Test Cases

### Case 1: Happy Path — Player helper generated for Godot/GDScript

**Fixture:**
- `project.yaml` has `engine.name: Godot`, `engine.language: GDScript`,
  `testing.framework: gdUnit4`; `addons/gdUnit4/` is installed, so its
  assertion API can be confirmed from the project
- `tests/unit/player/player_movement_test.gd` exists
- `design/gdd/player.md` has a Formulas section bounding health to 0–100
- No existing files in `tests/helpers/`; the user approves the write

**Input:** `/test-helpers player`

**Expected behavior:**
1. Skill reads engine, language and framework; samples the existing test file
2. Skill greps `design/gdd/player.md` for the Formulas / Edge Cases / Detailed
   Rules headings instead of reading it whole
3. Skill drafts `tests/helpers/player_factory.gd`: a `class_name` helper that
   `extends RefCounted`, static `make_*` factories with default parameters,
   bound constants commented as coming from the GDD, and a header line
   "Based on: design/gdd/player.md"
4. Every assertion goes through gdUnit4's confirmed API — no bare `assert()`,
   no `FAIL_IF` placeholder
5. Skill presents the file list and asks "May I write these helper files to `tests/helpers/`?"
6. Files written on approval; verdict COMPLETE, followed by the per-engine usage note

**Assertions:**
- [ ] Generated helper is GDScript at `tests/helpers/player_factory.gd`
- [ ] Bound constants trace to the GDD's Formulas section (not invented values)
- [ ] Helper extends `RefCounted`, not the test-suite base class, and uses no Autoload/singleton
- [ ] No bare `assert()` and no unresolved `FAIL_IF` reaches the file
- [ ] Verdict is COMPLETE

---

### Case 2: Engine Not Configured — Stops with /setup-engine

**Fixture:**
- `project.yaml` has no `engine` block; `technical-preferences.md` shows
  `[TO BE CONFIGURED]` for Engine

**Input:** `/test-helpers player`

**Expected behavior:**
1. Skill checks `project.yaml`, then `technical-preferences.md` — no engine in either
2. Skill outputs: "Engine not configured. Run `/setup-engine` first."
3. Skill stops — no test scan, no draft, no write

**Assertions:**
- [ ] The message states the engine is not configured
- [ ] `/setup-engine` is named as the prerequisite
- [ ] No write tool is called
- [ ] Verdict is not COMPLETE (nothing was created)

---

### Case 3: Helper Already Exists — Skipped, never overwritten

**Fixture:**
- Godot/GDScript/gdUnit4 configured as in Case 1
- `tests/helpers/game_assertions.gd` already exists with hand-written additions
- `tests/helpers/game_factory.gd` and `tests/helpers/scene_runner_helper.gd` do
  not exist; the user approves the write

**Input:** `/test-helpers scaffold`

**Expected behavior:**
1. Skill drafts the Godot base helpers only — `game_assertions.gd`,
   `game_factory.gd` and `scene_runner_helper.gd`; no system-specific helpers in
   `scaffold` mode
2. Skill asks "May I write these helper files to `tests/helpers/`?"
3. The two missing files, `tests/helpers/game_factory.gd` and
   `tests/helpers/scene_runner_helper.gd`, are created
4. For the existing file, skill reports: "Skipping `tests/helpers/game_assertions.gd`
   — already exists. Remove the file manually if you want it regenerated."
5. Verdict COMPLETE

**Assertions:**
- [ ] `scaffold` mode generates no `[system]_factory` helper
- [ ] The existing `game_assertions.gd` is left byte-for-byte unchanged
- [ ] The skip message names the existing file and how to regenerate it
- [ ] Only the two missing files are written; Verdict is COMPLETE

---

### Case 4: Framework Assertion API Unconfirmed — No helper generated

**Fixture:**
- `project.yaml` has `engine.name: Godot`, `engine.language: GDScript`;
  `testing.framework` is absent and `technical-preferences.md` shows no Framework
- No `addons/gdUnit4/` and no existing test files to learn the API from

**Input:** `/test-helpers scaffold`

**Expected behavior:**
1. Skill cannot confirm which assertion call registers a failure with the runner
2. Skill says so, and generates no helper rather than guessing a form such as
   `assert_that`, `assert_eq`, `assert_true` or a bare `assert()`
3. No "May I write" is asked and nothing is written

**Assertions:**
- [ ] The skill states it cannot confirm the framework's assertion API
- [ ] No helper file is written
- [ ] No guessed assertion form (and no `FAIL_IF` placeholder) is presented as ready to write
- [ ] Verdict is not COMPLETE

---

### Case 5: Director Gate Check — No gate; test-helpers is a scaffolding utility

**Fixture:**
- Engine and framework configured as in Case 1, no existing helpers

**Input:** `/test-helpers player`

**Expected behavior:**
1. Skill generates and writes the helper file
2. No director agents are spawned
3. No gate IDs appear in output

**Assertions:**
- [ ] No director gate is invoked
- [ ] No gate skip messages appear
- [ ] Verdict is COMPLETE without any gate check

---

### Case 6: Unity — Helpers under the engine's test root

**Fixture:**
- `project.yaml` has `engine.name: Unity`, `engine.language: C#`,
  `testing.framework: NUnit`; `com.unity.test-framework` is in
  `Packages/manifest.json`, so NUnit's assertion API can be confirmed from the
  installed package
- `/test-setup` has created `Assets/Tests/EditMode/EditModeTests.asmdef`
- No helpers exist yet; the user approves the write

**Input:** `/test-helpers scaffold`

**Expected behavior:**
1. The helper root is `Assets/Tests/EditMode/Helpers/` — inside the
   `EditModeTests` assembly, where Unity compiles it
2. Skill drafts `GameAssertions.cs` and `GameFactory.cs` for that folder,
   asserting through NUnit's `Assert`
3. Skill asks "May I write these helper files to `Assets/Tests/EditMode/Helpers/`?"
4. Files written on approval; the usage note says to reference the test assembly;
   verdict COMPLETE

**Assertions:**
- [ ] Helpers are written under `Assets/Tests/EditMode/Helpers/`
- [ ] Nothing is written under `tests/helpers/` — outside `Assets/`, Unity never compiles it
- [ ] The "May I write" ask names the Unity helper root
- [ ] Verdict is COMPLETE

---

## Protocol Compliance

- [ ] Reads engine, language and test framework before generating any helper
- [ ] Writes helpers only to the engine's helper root (`tests/helpers/`, `Assets/Tests/EditMode/Helpers/` or `Source/<Module>/Private/Tests/Helpers/`)
- [ ] Section-greps the GDD for system helpers (numbered headings such as `## 4. Formulas` included); constants trace to its Formulas section
- [ ] Godot signal asserts keep their flag in a Dictionary the lambda mutates and connect a variadic lambda (`func(...args)`) — a captured `bool` never changes in the caller, and a one-argument lambda fails on any other signal
- [ ] Asserts only through the configured framework — never bare `assert()` — and generates nothing when that API cannot be confirmed
- [ ] Helpers never extend the framework's test-suite base class
- [ ] Never overwrites an existing helper; reports the skip instead
- [ ] Asks "May I write" before any file is created
- [ ] Verdict is COMPLETE when helper files are written

---

## Coverage Notes

- `all` mode (one factory per system with test files) follows Case 1 per system;
  not separately tested.
- Unreal helper generation (`Source/<Module>/Private/Tests/Helpers/`) follows
  Case 6's pattern for its own helper root; not separately tested. Nor is a
  Unity project whose PlayMode tests need the helpers too (the skill asks before
  creating a shared `TestHelpers.asmdef`).
- A requested system with no GDD is not tested; the skill does not define that path.