Tool: run-tests
Relevant source files
The following files were used as context for generating this wiki page:
- Packages/src/Editor/Api/McpTools/RunTests/RunTestsTool.cs
- Packages/src/Editor/Core/CoreTools/TestRunner/PlayModeTestExecuter.cs
- Packages/src/Editor/Api/McpTools/RunTests/SKILL.md
- Packages/src/README.md
- Packages/src/TOOL_REFERENCE.md
- Packages/src/Cli~/src/tests/cli-e2e.test.ts
- Packages/src/TypeScriptServer~/README.md
- Packages/src/ARCHITECTURE.md
The run-tests tool is a core component of the uLoopMCP autonomous development loop, enabling AI agents to execute Unity Test Runner tests programmatically. It allows for the verification of code changes, bug fixes, and refactoring by running both EditMode and PlayMode tests and retrieving detailed results. This tool is essential for creating a self-sustaining cycle of compiling, testing, analyzing results, and fixing code.
This tool is exposed to LLM clients via the uloop CLI and the /uloop-run-tests skill, allowing natural language instructions like "Run the tests and tell me why they failed" to be automatically handled. Execution is subject to security settings and must be explicitly enabled in the uLoopMCP window.
Sources: Packages/src/README.md, Packages/src/Editor/Api/McpTools/RunTests/SKILL.md
Architecture and Execution Flow
The run-tests tool is initiated by an MCP client (like an LLM tool) or the uloop CLI. The request is processed by the TypeScript server, which then sends a JSON-RPC command to the Unity TCP server. Inside Unity, the RunTestsTool class handles the request, executes the tests using Unity's Test Runner API, and returns the results.
Sources: Packages/src/ARCHITECTURE.md, Packages/src/Editor/Api/McpTools/RunTests/RunTestsTool.cs
This diagram illustrates the high-level sequence of a run-tests command.
Security
For the run-tests tool to function, the Allow Tests Execution setting must be enabled in the "Security Settings" section of the uLoopMCP window in Unity. If disabled, any attempt to run the tool will fail.
Sources: Packages/src/README.md
Parameters
The run-tests tool accepts several parameters to control which tests are run and how the results are handled.
| Parameter | Type | Description | Default |
|---|---|---|---|
FilterType | enum | The type of test filter to apply. Options are all, exact, regex, assembly. | all |
FilterValue | string | The value for the filter. Required for exact, regex, and assembly filter types. | "" |
TestMode | enum | The mode in which to run the tests. Options are EditMode (0) and PlayMode (1). | EditMode |
SaveXml | boolean | If true, saves the test results as an NUnit-compatible XML file in the {project_root}/.uloop/outputs/TestResults/ directory. | false |
Sources: Packages/src/TOOL_REFERENCE.md
Filter Types
all: Runs all available tests.exact: Runs a single test method matching theFilterValue(e.g.,io.github.hatayama.uLoopMCP.MyTests.MyTestMethod).regex: Runs tests in classes or namespaces matching theFilterValueregex pattern.assembly: Runs all tests within the assembly specified byFilterValue(e.g.,uLoopMCP.Tests.Editor).
Sources: Packages/src/TOOL_REFERENCE.md
Response
The tool returns a JSON object summarizing the test run.
| Property | Type | Description |
|---|---|---|
Success | boolean | true if the test execution process completed without errors. |
Message | string | A summary message of the test execution. |
CompletedAt | string | The timestamp (ISO format) when the test run finished. |
TestCount | number | The total number of tests that were executed. |
PassedCount | number | The number of tests that passed. |
FailedCount | number | The number of tests that failed. |
SkippedCount | number | The number of tests that were skipped. |
XmlPath | string | If SaveXml was true, this contains the path to the generated XML results file. |
Sources: Packages/src/TOOL_REFERENCE.md
PlayMode Execution
When TestMode is set to PlayMode, the tool uses a specialized PlayModeTestExecuter. A critical aspect of this process is that Domain Reload is forcibly turned OFF during the test run to ensure stability and speed. The original Domain Reload setting is restored after the tests are complete.
Warning: Because Domain Reload is disabled, static variables will not be reset between test runs within the same PlayMode session. This is a crucial consideration when writing PlayMode tests intended to be run by this tool.
Sources: Packages/src/README.md, Packages/src/Editor/Core/CoreTools/TestRunner/PlayModeTestExecuter.cs:28-32
The flow for PlayMode test execution is as follows:
Usage Examples
CLI Usage
The uloop command-line tool provides a direct way to execute tests.
# Run all tests in EditMode
uloop run-tests --filter-type all
# Run tests in a specific assembly and save the results to XML
uloop run-tests --filter-type assembly --filter-value "uLoopMCP.Tests.Editor" --save-xml
# Run a single exact test in PlayMode
uloop run-tests --filter-type exact --filter-value "MyPlayModeTests.SpecificTest" --test-mode PlayMode
Sources: Packages/src/README.md, Packages/src/Cli~/src/tests/cli-e2e.test.ts
Direct JSON-RPC Call
You can also communicate with the Unity TCP server directly using a JSON-RPC payload.
echo '{"jsonrpc":"2.0","id":1,"method":"runtests","params":{"filterType":"all","filterValue":"","saveXml":false}}' | nc localhost 7400
Sources: Packages/src/TypeScriptServer~/README.md
Skill for LLM
The run-tests tool is packaged as a skill for LLM tools like Claude Code. The SKILL.md file provides the necessary context for the AI to understand when and how to use the tool.
The skill definition prompts the AI to use this tool for verifying code changes, running test suites, and debugging test failures.