/test-setup

name: test-setup
description: "Scaffold the test framework and CI/CD pipeline for the project's engine. Creates the tests/ directory structure, engine-specific test runner configuration, and GitHub Actions workflow. Run once during Technical Setup phase before the first sprint begins."
argument-hint: "[force]"
user-invocable: true
allowed-tools: Read, Glob, Grep, Bash, Write
model: sonnet

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**:

• Read `.claude/docs/technical-preferences.md` and extract the `Engine:` value.
• If engine is not configured (`[TO BE CONFIGURED]`), stop:

"Engine not configured. Run `/setup-engine` first, then re-run `/test-setup`."

2. **Check for existing test infrastructure**:

• 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

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

3. **Report findings**:

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

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

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)
  evidence/       — Screenshot and manual test sign-off records
  README.md       — Test framework documentation

[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."

Do not proceed without approval.

---

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 evidence/ # Screenshot logs and manual test sign-off records

## 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 | `tests/evidence/` |
| UI | Manual walkthrough OR interaction test | `tests/evidence/` |
| Config/Data | Smoke check pass | `production/qa/smoke-*.md` |

## CI

Tests run automatically on every push to `main` and on every pull request.
A failed test suite blocks merging.

### Engine-specific files

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

Create `tests/gdunit4_runner.gd`:

```gdscript
# 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:
        push_error("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/Play