run-tests

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 in 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 whose result is not Passed, do not analyze — report it as a failure instead (the screenshot, if any, may be from a partial run).

If no TestResults.xml is found (exit code 3)

Whether TestResults.xml is written under persistentDataPath depends on the project (e.g., the com.unity.test-framework.performance package's RunFinished callback writes it). If it is absent, fall back:

• Screenshot paths: [TakeScreenshot]/ScreenshotHelper log Save screenshot to <absolute path> on every capture. Find the current log file (compare mtimes of Editor.log and Editor-prev.log — see resources/troubleshooting-run-unity-tests.md → "Editor.log vs Editor-prev.log"), then take the Save screenshot to lines that appear after the last - Finished resetting the current domain line (the lifecycle marker for the run you just triggered — same resource, "Tests launched but timed out" table).
• Verification aspects: read the [Description(...)] attribute directly from the test's source file.

Helper script

${CLAUDE_SKILL_DIR}/scripts/get-persistent-data-path.sh <unity-project-root> prints the Editor's Application.persistentDataPath for the current OS (from companyName/productName in ProjectSettings/ProjectSettings.asset, per Unity's docs). extract-visual-verification.py calls it automatically; use it directly only when you need the raw directory.

Rules for Test Failures

If the same test(s) fail on two or more consecutive runs, stop and consult the user rather than continuing to fix.

When consulting, clarify:

• Current failure status: what is failing and the likely cause
• Fix history: what was changed, how many times, and the scope of impact
• Planned approach: what options are being considered next

Troubleshooting

Read the appropriate resource file based on the situation:

• Any Unity MCP tool (run_unity_tests, unity_play_control, get_unity_compilation_result) is not available or fails with a connection error: Read ${CLAUDE_SKILL_DIR}/resources/troubleshooting-run-unity-tests.md
• A test fails due to an assertion, constraint, or comparer in the TestHelper namespace (excluding TestHelper.UI): Read ${CLAUDE_SKILL_DIR}/resources/troubleshooting-test-helper.md
• A test fails due to an exception thrown from the TestHelper.UI namespace: Read ${CLAUDE_SKILL_DIR}/resources/troubleshooting-test-helper-ui.md