/test-helpers

name: test-helpers
description: "Generate engine-specific test helper libraries — assertion utilities, factory functions, mocks in the engine's test folder. Reduces boilerplate."
argument-hint: "[system-name | all | scaffold]"
user-invocable: true
allowed-tools: Read, Glob, Grep, Write, Bash(bash "*/.claude/skills/test-helpers/../../hooks/yaml-helper.sh" resolve_config *)
model: sonnet

!`bash "${CLAUDE_SKILL_DIR}/../../hooks/yaml-helper.sh" resolve_config --keys automation`

**Automation mode**: Resolve `modes.automation` (`project.local.yaml` → `project.yaml` → default `collaborative`). Every `AskUserQuestion` call and every file write follows `.claude/docs/automation-modes.md` (collaborative asks always · guided major-only · autonomous logs and proceeds; `automation_always_ask` categories always prompt).

Test Helpers

Writing test cases is faster and more consistent when common setup, teardown, and assertion patterns are abstracted into helpers. This skill generates a `tests/helpers/` library tailored to the project's actual engine, language, and systems — so every developer writes less boilerplate and more assertions.

**Output:** engine-specific helper files in the engine's **helper root** — the only place its test runner compiles them (`.claude/docs/directory-structure.md`):

| Engine | Helper root | |---|---| | Godot | `tests/helpers/` | | Unity | `Assets/Tests/EditMode/Helpers/` — inside the `EditModeTests` assembly `/test-setup` creates. If PlayMode tests need the same helpers, ask before creating `Assets/Tests/Helpers/TestHelpers.asmdef` and referencing it from both test assemblies. | | Unreal | `Source/<Module>/Private/Tests/Helpers/` |

`tests/helpers/` below means the helper root for the project's engine.

**When to run:**

• After `/test-setup` scaffolds the framework (first time)
• When multiple test files repeat the same setup boilerplate
• When starting to write tests for a new system

---

Assertions: use the project's test framework, never bare `assert()`

**Generated helpers must assert through the configured test framework's assertion API**, resolved from `testing.framework` — not through GDScript's built-in `assert()`.

Two things go wrong with a bare `assert()` in a helper, and both are silent:

1. **It aborts the run instead of failing the test.** A framework assertion records a failure and continues, so one broken expectation yields one red test. A bare `assert()` halts execution, so the first failure hides every result after it. 2. **It is stripped in release builds.** A helper library built on `assert()` stops asserting entirely in exactly the build you most want checked, and does so without any error — the tests still "pass".

**Look up the assertion form for the configured framework before generating code.** Do not copy the forms in this file or in other skills' examples as authoritative — they are illustrative and have drifted (`assert_eq`, `assert_true` and `assert_that` all appear across the repo). If you cannot confirm the correct API for the project's framework, say so and generate no helper rather than guessing.

**Helpers must not extend the framework's test-suite base class.** A file in `tests/helpers/` that extends the suite type is discovered by the runner as a test suite containing zero tests. Helpers are plain classes; only real test files extend the suite.

---

1. Parse Arguments

**Modes:**

• `/test-helpers [system-name]` — generate helpers for a specific system

(e.g., `/test-helpers combat`)

• `/test-helpers all` — generate helpers for all systems with test files
• `/test-helpers scaffold` — generate only the base helper library (no

system-specific helpers); use this on first run

• No argument — run `scaffold` if no helpers exist, else `all`

---

2. Detect Engine and Language

Read from `project.yaml` first, falling back to `.claude/docs/technical-preferences.md` for any key that is absent or empty:

• `engine.name` (else the `Engine:` value)
• `engine.language` (else the `Language:` value)
• `testing.framework` (else `Framework:` from the Testing section)

If the engine is not configured in either source: "Engine not configured. Run `/setup-engine` first."

---

3. Load Existing Test Patterns

Scan the engine's test root for patterns already in use (Godot `tests/`, Unity `Assets/Tests/`, Unreal `Source/<Module>/Private/Tests/`):

Glob pattern="tests/**/*_test.*"                  (Godot)
Glob pattern="Assets/Tests/**/*Tests.cs"          (Unity)
Glob pattern="Source/*/Private/Tests/**/*.cpp"    (Unreal)

For a representative sample (up to 5 files), read the test files and extract:

• Setup patterns (how `before_each` / `setUp` / fixtures are written)
• Common assertion patterns (what is being asserted most often)
• Object creation patterns (how game objects or scenes are instantiated in tests)
• Mock/stub patterns (how dependencies are replaced)

This ensures generated helpers match the project's existing style, not a generic template.

Also read:

• `design/gdd/systems-index.md` — to know which systems exist
• In-scope GDD(s) — to understand what data types and values need testing. Read

them by section: find the headings you need with the Grep tool (pattern `^#`, content mode) and Read those ranges with offset and limit.

• `docs/architecture/tr-registry.yaml` — to map requirements to tested systems

---

4. Generate Engine-Specific Helpers

Godot 4 (GDUnit4 / GDScript)

> **`FAIL_IF(...)` in the example below is a PLACEHOLDER, not an API.** It marks > the one line you must resolve from the project's actual test framework before > emitting any of this, per the rule in §2. Substitute the framework's real > failure call — the form that **registers a failure with the runner and lets the > suite continue** — and delete the marker comment. > > **It is deliberately not spelled `assert_that`, `assert_eq` or `assert_true`.** > All three appear somewhere in this repo, they disagree, and **GdUnit4