/run-tests

name: run-tests
description: >-
  Provides guidelines for running Unity tests using the run_unity_tests tool.
  Make sure to use this skill whenever running, executing, or re-running tests on the Unity editor.
  This includes verifying implementations, debugging test failures, running specific test assemblies, or any task that involves the run_unity_tests tool.
  Also covers running Play Mode tests on the player for verifying player-only behavior (e.g., #if directives and code stripping).
  Also covers verifying `[Category("VisualVerification")]` tests after a run by analyzing the saved screenshots.
  Even if the user just says "run the tests" or "check if it passes", use this skill.
license: Unlicense
metadata:
  author: Koji Hasegawa

Gotchas

• **Never call two Unity Editor tools in parallel.** `unity_play_control`, `get_unity_compilation_result`, `run_unity_tests`, and `run_method_in_unity` must be called strictly one at a time — always wait for each call to return before making the next one. Calling them concurrently causes domain-reload conflicts that result in "canceled" or "did not connect within 30 seconds" errors.
• **When a Unity Editor tool returns `error` or `canceled`, wait 10 seconds before retrying.** Domain reload typically takes several seconds; immediate retry hits the same in-flight reload and fails again. Do not switch tools in the meantime (e.g., calling `unity_play_control` to verify state) — that just compounds the multiplexed calls. If the same tool returns `error` or `canceled` on two consecutive attempts (with the 10-second wait between them), stop and consult the user instead of retrying further.

Run Tests

Before running tests, complete the following steps in order:

1. If any code was modified, confirm compilation success using the `get_unity_compilation_result` tool before proceeding. 2. To determine `assemblyNames` and `testMode` for a specific test class, run `${CLAUDE_SKILL_DIR}/scripts/resolve-test-target.sh <test-class-cs-path>`. The script prints `<assemblyName>\t<testMode>` (e.g. `MyGame.Tests\tPlayMode`). Skip this step when running an already-known assembly.

Then use the `run_unity_tests` tool to run the tests on the Unity editor.

Test execution can take several minutes. Do not re-run while a test is in progress — always wait for it to complete or time out. If a timeout occurs, narrow down the tests using filter settings and re-run.

Performance Test Results

When `com.unity.test-framework.performance` is installed, each run writes its measurements to `Application.persistentDataPath/PerformanceTestResults.json` (alongside the `TestResults.xml` they are parsed from). Resolve that directory with `${CLAUDE_SKILL_DIR}/scripts/get-persistent-data-path.sh <unity-project-root>`.

For the package's measurement pitfalls, see the `test-writing-guide` skill's `resources/unity-test-framework-performance.md`.

Run Tests on the Player

`run_unity_tests` runs tests only inside the Unity Editor. Run tests on a player instead when the user asks for it (e.g., "run on player", "standalone", "実機で実行"), or when player-only behavior must be verified (code inside `#if !UNITY_EDITOR`, `Resources`-based loading, IL2CPP, player-build hooks such as `ITestPlayerBuildModifier`). Pick the section below by target platform.

Standalone Player

For a standalone player running on the host OS (macOS, Windows, or Linux): Read `${CLAUDE_SKILL_DIR}/resources/run-on-standalone-player.md`. It covers the build-and-run procedure and troubleshooting including `Player.log` locations.

Other Players

TBD

Visual Verification

A test method carrying `[Category("VisualVerification")]` has no `Assert` statements (see `test-writing-guide` skill), so `Passed` only means the test ran without throwing — it says nothing about whether the screen actually looks right. That judgment has to come from analyzing the screenshot the test captured.

**Only analyze when the run was to confirm a change made in this session** — production code, test code, a scene, a prefab, or another asset. Skip the analysis when nothing is under verification: a regression run over unchanged code, or when the user only asked whether the tests pass. When in doubt, skip.

This applies to Editor runs (`run_unity_tests`) only. A standalone-player run writes `Temp/PlayerTestResult.txt`, not an XML result file, and on macOS the Player's `persistentDataPath` differs from the Editor's — see `resources/run-on-standalone-player.md`. `[TakeScreenshot]` itself is Play Mode only.

Procedure

1. Run: `python3 ${CLAUDE_SKILL_DIR}/scripts/extract-visual-verification.py <unity-project-root>` This prints, per `[Category("VisualVerification")]` test found in `Application.persistentDataPath/TestResults.xml`, its NUnit `result`, its `Description` property (the verification aspects), and its `Screenshot` propert(y/ies) (absolute path(s)). See the script's own comments for why an XML library is used instead of grep/awk (class-scoped `[Category]` lands on the ancestor `<test-suite>`, not the `<test-case>`; a test can record more than one `Screenshot`). 2. Check freshness before trusting the output: compare the printed list of "All N test(s) in this result file" against the tests you actually just ran. A filtered run's XML contains only the test-cases that were executed, so a mismatch (extra tests you didn't run, or missing ones you did) means this file is from an earlier run — `TestResults.xml` is overwritten on each run, not appended. Treat the printed age (`— N seconds ago`) as a secondary signal only; it can't discriminate a stale file from a few minutes ago from a run that legitimately took a few minutes. On either signal of staleness, stop and report it instead of analyzing. 3. For each test whose `result` is `Passed`, read the image(s) at its `Screenshot` path(s) and judge them against the aspects listed in `Description`. Report each aspect's verdict with what you actually saw in the image. 4. For a test