/test-designing-guide

name: test-designing-guide
description: >-
  Provides test design methodology for Unity projects. Use this skill whenever
  designing test cases from requirements or specifications, including selecting
  test techniques, deriving test cases, and formatting them. Even for small
  features, load this skill to ensure test design rigor.
user-invocable: false
license: Unlicense
metadata:
  author: Koji Hasegawa

Guide for designing test cases for Unity projects.

Inputs

This skill requires the following inputs in its prompt:

| Input | Required | Description | |---------------------------|----------|------------------------------------------------------------------------------------| | **Requirements** | Required | The feature requirements to test against | | **Implementation design** | Required | Class names, public method signatures, dependency interfaces, and design rationale | | **Existing code context** | Optional | File paths and class summaries of relevant existing code | | **Language convention** | Optional | Project language for test names and prose output (from `CLAUDE.md`). |

For bug-fix tasks, the **Requirements** input is the bug report (Condition / Expected / Actual), and the **Implementation design** input is the existing class/method structure of the affected production code — there is no new design.

The table above is the complete set of recognized inputs. Ignore anything else in the prompt — in particular test cases or manual test lists from a Plan agent (test design is this skill's sole responsibility) and output format overrides (the template in Section 6 is fixed).

1. Analyze Specifications

Read the requirements and identify testable specifications. If the specifications are unclear, use the AskUserQuestion tool to request clarification before proceeding. If the test target has low testability, flag it in the Testability Assessment (Section 7).

2. Assign Test Targets to Layers

For each test target, determine which layer it belongs to based on its nature and integration level:

1. **Editor tests** — for Editor extension code (paths containing `/Editor/`), asset file validation, and cross-asset consistency checks. 2. **Unit tests** — test runtime code whose execution is **initiated by a direct method call**. This includes tests that verify behavior driven by Unity's lifecycle (Awake, Start, Update, etc.) or UI events. Prioritize **least integrated** targets, testing them comprehensively; for highly integrated targets (where the SUT collaborates with dependent objects), keep test density low and focus on interactions between objects. 3. **Integration tests** — test targets that are a **scene or prefab** (or an equivalent GameObject hierarchy assembled in test code), together with the interplay among its placed components (MonoBehaviour subclasses) and the assets they reference. Unit tests cover targets whose execution is initiated by a direct method call; integration tests cover behavior that only emerges from Unity's component wiring and asset linkage.

• Add the integration test method to the test class of the **primary class** involved; OR
• Create a new dedicated test class if there is no clear primary class (e.g., when the subject is a prefab or scene).
• Explicitly design integration tests **before** falling back to visual verification tests or manual tests; only drop to those layers when the behavior cannot be expressed as a functional assertion.
• When the **asset itself** is the SUT (file validation, cross-asset consistency), classify it as an **Editor test**, not an integration test; integration tests assert the runtime behavior that emerges from a scene/prefab's linkage to its assets.

4. **Visual verification tests** — verify that actual on-screen rendering conforms to the intended design: positional relationships between elements, typography (font size, font style, and font family), text/background contrast and legibility, visual state representation (e.g., a disabled button looks grayed out), and rendering quality (no sprite distortion, ghosting, or unintended clipping). Take screenshots in the test code, and image analysis (see Section 4). A deterministic mid-point of an animation (e.g., an attack lunge at its peak, a fade-out at half time) can also be captured and verified here; only subjective motion feel belongs to manual tests. Design these **before** falling back to manual tests. 5. **Manual tests** — reserved for items that **neither automated tests nor image analysis can verify** — i.e., items requiring human sensory judgment with no objective pass/fail criterion (e.g., game feel, animation polish, audio balance). Do NOT add manual tests for scenarios already covered by integration tests or visual verification tests, even if they seem "worth confirming by eye."

**Note:** Never use Edit Mode tests for runtime code logic. Edit Mode and Play Mode test runners cannot execute simultaneously — splitting coverage for a single SUT between the two modes prevents running all tests at once. Play Mode tests can run on actual devices (player builds), which Editor tests cannot.

3. Select Testing Techniques

**Prefer specification-based tests over structural (implementation-coupled) tests.** Structural tests break under refactoring and lose value fast. It's fine to write a structural test temporarily when you're unsure about an implementation, but plan to delete it once specification tests cover the same behavior.

For each test target, select appropriate techniques:

• **Equivalence partitioning** — group inputs into valid/invalid partitions; one representative per partition. When an **invalid** equivalence partition exists but the spec does not define its behavior (e.g., what happens for negative input, out-of-range values, null), use the `AskUser