test-setup skill

!bash "${CLAUDESKILLDIR}/../../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; automationalwaysask categories always prompt).

Test Setup

This skill scaffolds the automated testing infrastructure for the project. It detects the configured engine, generates the appropriate test runner configuration, creates the standard directory layout, and wires up CI/CD so tests run on every push.

Run this once during the Technical Setup phase, before any implementation begins. A test framework installed at sprint start costs 30 minutes. A test framework installed at sprint four costs 3 sprints.

Output: tests/ directory structure + .github/workflows/tests.yml

Phase 1: Detect Engine and Existing State

1. Read engine config:

(including when project.yaml has no engine: block), fall back to the Engine: value in .claude/docs/technical-preferences.md.

• Read engine.name from project.yaml; if that key is absent or empty

absent/empty and technical-preferences.md shows [TO BE CONFIGURED] or is missing), stop: "Engine not configured. Run /setup-engine first, then re-run /test-setup."

• If neither source yields a configured engine (project.yaml engine.name

1. Check for existing test infrastructure:

Source/Tests/ (Unreal) for engine-specific artifacts.

• Glob tests/ — does the directory exist?
• Glob tests/unit/ and tests/integration/ — do subdirectories exist?
• Glob .github/workflows/ — does a CI workflow file exist?
• Glob tests/gdunit4_runner.gd (Godot) or tests/EditMode/ (Unity) or

1. Report findings:

"Test infrastructure appears to be in place. Re-run with /test-setup force to regenerate. Proceeding will not overwrite existing test files."

• "Engine: [engine]. Test directory: [found / not found]. CI workflow: [found / not found]."
• If everything already exists AND force argument was not passed:

If the force argument is passed, skip the "already exists" early-exit and proceed — but still do not overwrite files that already exist at a given path. Only create files that are missing.

Phase 2: Present Plan

Based on the engine detected and the existing state, present a plan:

## Test Setup Plan — [Engine]

I will create the following (skipping any that already exist):

tests/
  unit/           — Isolated unit tests for formulas, state, and logic
  integration/    — Cross-system tests and save/load round-trips
  smoke/          — Critical path test list (15-minute manual gate)
  README.md       — Test framework documentation

production/qa/
  evidence/       — Screenshot and manual test sign-off records

[Engine-specific files — see per-engine details below]

.github/workflows/tests.yml  — CI: run tests on every push to main

Estimated time: ~5 minutes to create all files.

Ask: "May I create these files? I will not overwrite any test files that already exist at these paths."

At collaborative and guided — do not proceed without approval. These are new files, and automation-modes.md:81 gates new-file writes in guided too, so the answer is the same in both modes. At autonomous — create them and log the decision; do not block. An unconditional gate here would read as "block even in autonomous" and contradict this skill's own header.

Phase 3: Create Directory Structure

After approval, create the following files:

tests/README.md

# Test Infrastructure

**Engine**: [engine name + version]
**Test Framework**: [GdUnit4 | Unity Test Framework | UE Automation]
**CI**: `.github/workflows/tests.yml`
**Setup date**: [date]

## Directory Layout

tests/ unit/ # Isolated unit tests (formulas, state machines, logic) integration/ # Cross-system and save/load tests smoke/ # Critical path test list for /smoke-check gate

production/qa/ evidence/ # Screenshot logs and manual test sign-off records

> **Manual evidence lives under `production/qa/evidence/`, not `tests/`.** That is
> where every consumer reads it — `/smoke-check`, `/test-evidence-review`,
> `/qa-plan`, and the evidence table in `.claude/docs/coding-standards.md`. This
> scaffold and this skill's completion summary must name the same path: listing
> `tests/evidence/` here while the summary reports `production/qa/evidence/`
> creates a directory nothing reads and skips the one everything does.

## Running Tests

[Engine-specific command — see below]

## Test Naming

- **Files**: `[system]_[feature]_test.[ext]`
- **Functions**: `test_[scenario]_[expected]`
- **Example**: `combat_damage_test.gd` → `test_base_attack_returns_expected_damage()`

## Story Type → Test Evidence

| Story Type | Required Evidence | Location |
|---|---|---|
| Logic | Automated unit test — must pass | `tests/unit/[system]/` |
| Integration | Integration test OR playtest doc | `tests/integration/[system]/` |
| Visual/Feel | Screenshot + lead sign-off | `production/qa/evidence/` |
| UI | Manual walkthrough OR interaction test | `production/qa/evidence/` |
| Config/Data | Smoke check pass | `production/qa/smoke-*.md` |

## CI

Tests run automat

### Engine-specific files

#### Godot 4 (`Engine: Godot`)

Create `tests/gdunit4_runner.gd`:

GdUnit4 test runner — invoked by CI and /smoke-check

Usage: godot --headless --script tests/gdunit4_runner.gd

extends SceneTree

func init() -> void: var runner := load("res://addons/gdunit4/GdUnitRunner.gd") if runner == null: pusherror("GdUnit4 not found. Install via AssetLib or addons/.") quit(1) return var instance = runner.new() instance.run_tests() quit(0)

Create `tests/unit/.gdignore_placeholder` with content:
`# Unit tests go here — one subdirectory per system (e.g., tests/unit/combat/)`

Create `tests/integration/.gdignore_placeholder` with content:
`# Integration tests go here — one subdirectory per system`

Note in the README: **Installing GdUnit4**

1. Open Godot → AssetLib → search "GdUnit4" → Download & Install
2. Enable the plugin: Project → Project Settings → Plugins → GdUnit4 ✓
3. Restart the editor
4. Verify: res://addons/gdunit4/ exists

#### Unity (`Engine: Unity`)

Create `tests/EditMode/` placeholder file `tests/EditMode/README.md`:

Edit Mode Tests

Unit tests that run without entering Play Mode. Use for pure logic: formulas, state machines, data validation. Assembly definition required: tests/EditMode/EditModeTests.asmdef

Create `tests/PlayMode/README.md`:

Play Mode Tests

Integration tests that run in a real game scene. Use for cross-system interactions, physics, and coroutines. Assembly definition required: tests/PlayMode/PlayModeTests.asmdef

Note in the README: **Enabling Unity Test Framework**

Window → General → Test Runner (Unity Test Framework is included by default in Unity 2019+)

#### Unreal Engine (`Engine: Unreal` or `Engine: UE5`)

Create `Source/Tests/README.md`:

Unreal Automation Tests

Tests use the UE Automation Testing Framework. Run via: Session Frontend → Automation → select "MyGame." tests Or headlessly: UnrealEditor -nullrhi -ExecCmds="Automation RunTests MyGame.; Quit"

Test class naming: F[SystemName]Test Test category naming: "MyGame.[System].[Feature]"

---

## Phase 4: Create CI/CD Workflow

### Godot 4

Create `.github/workflows/tests.yml`:

name: Automated Tests

on: push: branches: [main] pull_request: branches: [main]

jobs: test: name: Run GdUnit4 Tests runs-on: ubuntu-latest

steps:

uses: actions/checkout@v4 with: lfs: true

• name: Checkout

uses: MikeSchulze/gdUnit4-action@v1 with: godot-version: '[VERSION FROM docs/engine-reference/godot/VERSION.md]' paths: | tests/unit tests/integration report-name: test-results

• name: Run GdUnit4 Tests

if: always() uses: actions/upload-artifact@v4 with: name: test-results path: reports/