* Fix test job state management after domain reload
- TestRunnerService.RunFinished: Always clean up job state even when
_runCompletionSource is null (happens after PlayMode domain reload)
- TestJobManager: Detect and clear stale jobs (5+ min without updates)
on startup to recover from stuck state after domain reload
- refresh_unity.py: Add "could not connect" to retryable errors when
wait_for_ready=True, so connection failures during domain reload
trigger waiting instead of immediate failure
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
* Add focus nudge to handle OS-level throttling during PlayMode tests
When Unity is unfocused, macOS App Nap (and similar OS features) can
throttle the process, causing PlayMode tests to stall even with Unity
No Throttling mode enabled.
Changes:
- Add ApplyNoThrottlingPreemptive() to TestRunnerNoThrottle for early
throttle prevention before PlayMode Execute()
- Add focus_nudge.py utility that temporarily focuses Unity and returns
focus to the original app (supports macOS, Windows, Linux)
- Integrate focus nudge into get_test_job polling - when tests appear
stalled (unfocused + no progress for 10s), automatically nudge Unity
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
* Fix code review issues in focus_nudge.py
- Remove redundant time import (already imported at module level)
- Escape window titles in PowerShell script to prevent injection
- Remove unused Callable import
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
* Improve focus nudge logging and fix skipped tests
- Improve logging in focus_nudge.py: rate limit skip and focus return at INFO level
- Improve logging in run_tests.py: show nudge completion status
- Fix path resolution in test_logging_stdout.py and test_transport_framing.py
- Add PlayMode tests to UnityMCPTests project for testing PlayMode runner
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
* Add troubleshooting note about focus permission requests
When running PlayMode tests with Unity in the background, the focus
nudge feature may trigger OS permission prompts (especially on macOS
for accessibility/automation). Document this expected behavior.
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 4.5 <noreply@anthropic.com>
* refactor: Split ParseColorOrDefault into two overloads and change default to Color.white
* Auto-format Python code
* Remove unused Python module
* Refactored VFX functionality into multiple files
Tested everything, works like a charm
* Rename ManageVfx folder to just Vfx
We know what it's managing
* Clean up whitespace on plugin tools and resources
* Make ManageGameObject less of a monolith by splitting it out into different files
* Remove obsolete FindObjectByInstruction method
We also update the namespace for ManageVFX
* refactor: Consolidate editor state resources into single canonical implementation
Merged EditorStateV2 into EditorState, making get_editor_state the canonical resource. Updated Unity C# to use EditorStateCache directly. Enhanced Python implementation with advice/staleness enrichment, external changes detection, and instance ID inference. Removed duplicate EditorStateV2 resource and legacy fallback mapping.
* Validate editor state with Pydantic models in both C# and Python
Added strongly-typed Pydantic models for EditorStateV2 schema in Python and corresponding C# classes with JsonProperty attributes. Updated C# to serialize using typed classes instead of anonymous objects. Python now validates the editor state payload before returning it, catching schema mismatches early.
* Consolidate run_tests and run_tests_async into single async implementation
Merged run_tests_async into run_tests, making async job-based execution the default behavior. Removed synchronous blocking test execution. Updated RunTests.cs to start test jobs immediately and return job_id for polling. Changed TestJobManager methods to internal visibility. Updated README to reflect single run_tests_async tool. Python implementation now uses async job pattern exclusively.
* Validate test job responses with Pydantic models in Python
* Change resources URI from unity:// to mcpforunity://
It should reduce conflicts with other Unity MCPs that users try, and to comply with Unity's requests regarding use of their company and product name
* Update README with all tools + better listing for resources
* Update other references to resources
* Updated translated doc - unfortunately I cannot verify
* Update the Chinese translation of the dev docks
* Change menu item from Setup Window to Local Setup Window
We now differentiate whether it's HTTP local or remote
* Fix URIs for menu items and tests
* Shouldn't have removed it
* Minor edits from CodeRabbit feedback
* Don't use reflection which takes longer
* Fix failing python tests
* Add serialization helpers for ParticleSystem curves and MinMaxCurve types
Added SerializeAnimationCurve and SerializeMinMaxCurve helper methods to properly serialize Unity's curve types. Updated GetInfo to use these helpers for startLifetime, startSpeed, startSize, gravityModifier, and rateOverTime instead of only reading constant values.
* Use ctx param
* Update Server/src/services/tools/run_tests.py
Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com>
* Minor fixes
* Rename anything EditorStateV2 to just EditorState
It's the default, there's no old version
* Make infer_single_instance_id public by removing underscore prefix
* Fix Python tests, again
* Replace AI generated .meta files with actual Unity ones
* ## Pre-Launch Enhancements: Testing Infrastructure & Tool Improvements (#8)
* Add local test harness for fast developer iteration
Scripts for running the NL/T/GO test suites locally against a GUI Unity
Editor, complementing the CI workflows in .github/workflows/.
Benefits:
- 10-100x faster than CI (no Docker startup)
- Real-time Unity console debugging
- Single test execution for rapid iteration
- Auto-detects HTTP vs stdio transport
Usage:
./scripts/local-test/setup.sh # One-time setup
./scripts/local-test/quick-test.sh NL-0 # Run single test
./scripts/local-test/run-nl-suite-local.sh # Full suite
See scripts/local-test/README.md for details.
Also updated .gitignore to:
- Allow scripts/local-test/ to be tracked
- Ignore generated artifacts (reports/*.xml, .claude/local/, .unity-mcp/)
* Fix issue #525: Save dirty scenes for all test modes
Move SaveDirtyScenesIfNeeded() call outside the PlayMode conditional
so EditMode tests don't get blocked by Unity's "Save Scene" modal dialog.
This prevents MCP from timing out when running EditMode tests with unsaved
scene changes.
* fix: add missing FAST_FAIL_TIMEOUT constant in PluginHub
The FAST_FAIL_TIMEOUT class attribute was referenced on line 149 but never
defined, causing AttributeError on every ping attempt. This error was silently
caught by the broad 'except Exception' handler, causing all fast-fail commands
(read_console, get_editor_state, ping) to fail after 6 seconds of retries with
'ping not answered' error.
Added FAST_FAIL_TIMEOUT = 10 to define a 10-second timeout for fast-fail
commands, matching the intent of the existing fast-fail infrastructure.
* feat(ScriptableObject): enhance dry-run validation for AnimationCurve and Quaternion
Dry-run validation now validates value formats, not just property existence:
- AnimationCurve: Validates structure ({keys:[...]} or direct array), checks
each keyframe is an object, validates numeric fields (time, value, inSlope,
outSlope, inWeight, outWeight) and integer fields (weightedMode)
- Quaternion: Validates array length (3 for Euler, 4 for raw) or object
structure ({x,y,z,w} or {euler:[x,y,z]}), ensures all components are numeric
Refactored shared validation helpers into appropriate locations:
- ParamCoercion: IsNumericToken, ValidateNumericField, ValidateIntegerField
- VectorParsing: ValidateAnimationCurveFormat, ValidateQuaternionFormat
Added comprehensive XML documentation clarifying keyframe field defaults
(all default to 0 except as noted).
Added 5 new dry-run validation tests covering valid and invalid formats
for both AnimationCurve and Quaternion properties.
* test: fix integration tests after merge
- test_refresh_unity_retry_recovery: Mock now handles both refresh_unity and
get_editor_state commands (refresh_unity internally calls get_editor_state
when wait_for_ready=True)
- test_run_tests_async_forwards_params: Mock response now includes required
'mode' field for RunTestsStartResponse Pydantic validation
- test_get_test_job_forwards_job_id: Updated to handle GetTestJobResponse as
Pydantic model instead of dict (use model_dump() for assertions)
* Update warning message to apply to all test modes
Follow-up to PR #527: Since SaveDirtyScenesIfNeeded() now runs for all test modes, update the warning message to say 'tests' instead of 'PlayMode tests'.
* feat(run_tests): add wait_timeout to get_test_job to avoid client loop detection
When polling for test completion, MCP clients like Cursor can detect the
repeated get_test_job calls as 'looping' and terminate the agent.
Added wait_timeout parameter that makes the server wait internally for tests
to complete (polling Unity every 2s) before returning. This dramatically
reduces client-side tool calls from 10-20 down to 1-2, avoiding loop detection.
Usage: get_test_job(job_id='xxx', wait_timeout=30)
- Returns immediately if tests complete within timeout
- Returns current status if timeout expires (client can call again)
- Recommended: 30-60 seconds
* fix: use Pydantic attribute access in test_run_tests_async for merge compatibility
* revert: remove local test harness - will be submitted in separate PR
---------
Co-authored-by: Scott Jennings <scott.jennings+CIGINT@cloudimperiumgames.com>
---------
Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com>
Co-authored-by: dsarno <david@lighthaus.us>
Co-authored-by: Scott Jennings <scott.jennings+CIGINT@cloudimperiumgames.com>
* Add editor readiness v2, refresh tool, and preflight guards
* Detect external package changes and harden refresh retry
* feat: add TestRunnerNoThrottle and async test running with background stall prevention
- Add TestRunnerNoThrottle.cs: Sets editor to 'No Throttling' mode during test runs
with SessionState persistence across domain reload
- Add run_tests_async and get_test_job tools for non-blocking test execution
- Add TestJobManager for async test job tracking with progress monitoring
- Add ForceSynchronousImport to all AssetDatabase.Refresh() calls to prevent stalls
- Mark DomainReloadResilienceTests as [Explicit] with documentation explaining
the test infrastructure limitation (internal coroutine waits vs MCP socket polling)
- MCP workflow is unaffected - socket messages provide external stimulus that
keeps Unity responsive even when backgrounded
* refactor: simplify and clean up code
- Remove unused Newtonsoft.Json.Linq import from TestJobManager
- Add throttling to SessionState persistence (once per second) to reduce overhead
- Critical job state changes (start/finish) still persist immediately
- Fix duplicate XML summary tag in DomainReloadResilienceTests
* docs: add async test tools to README, document domain reload limitation
- Add run_tests_async and get_test_job to main README tools list
- Document background stall limitation for domain reload tests in DEV readme
* ci: add separate job for domain reload tests
Run [Explicit] domain_reload tests in their own job using -testCategory
* ci: run domain reload tests in same job as regular tests
Combines into single job with two test steps to reuse cached Library
* fix: address coderabbit review issues
- Fix TOCTOU race in TestJobManager.StartJob (single lock scope for check-and-set)
- Store TestRunnerApi reference with HideAndDontSave to prevent GC/serialization issues
* docs: update tool descriptions to prefer run_tests_async
- run_tests_async is now marked as preferred for long-running suites
- run_tests description notes it blocks and suggests async alternative
* docs: update README screenshot to v8.6 UI
* docs: add v8.6 UI screenshot
* Update README for MCP version and instructions for v8.7
* fix: handle preflight busy signals and derive job status from test results
- manage_asset, manage_gameobject, manage_scene now check preflight return
value and propagate busy/retry signals to clients (fixes Sourcery #1)
- TestJobManager.FinalizeCurrentJobFromRunFinished now sets job status to
Failed when resultPayload.Failed > 0, not always Succeeded (fixes Sourcery #2)
* fix: increase HTTP server startup timeout for dev mode
When 'Force fresh server install' is enabled, uvx uses --no-cache --refresh
which rebuilds the package and takes significantly longer to start.
- Increase timeout from 10s to 45s when dev mode is enabled
- Add informative log message explaining the longer startup time
- Show actual timeout value in warning message
* fix: derive job status from test results in FinalizeFromTask fallback
Apply same logic as FinalizeCurrentJobFromRunFinished: check result.Failed > 0
to correctly mark jobs as Failed when tests fail, even in the fallback path
when RunFinished callback is not delivered.
* Optimize run_tests to return summary by default, reducing token usage by 98%
- Add includeFailedTests parameter: returns only failed/skipped test details
- Add includeDetails parameter: returns all test details (original behavior)
- Default behavior now returns summary only (~150 tokens vs ~13k tokens)
- Make results field optional in Python schema for backward compatibility
Token savings:
- Default: ~13k tokens saved (98.9% reduction)
- With failures: minimal tokens (only non-passing tests)
- Full details: same as before when explicitly requested
This prevents context bloat for typical test runs where you only need
pass/fail counts, while still allowing detailed debugging when needed.
* Add warning when run_tests filters match no tests; fix test organization
TDD Feature:
- Add warning message when filter criteria match zero tests
- New RunTestsTests.cs validates message formatting logic
- Modified RunTests.cs to append "(No tests matched the specified filters)" when total=0
Test Organization Fixes:
- Move MCPToolParameterTests.cs from EditMode/ to EditMode/Tools/ (matches folder hierarchy)
- Fix inconsistent namespaces to MCPForUnityTests.Editor.{Subfolder}:
- MCPToolParameterTests: Tests.EditMode → MCPForUnityTests.Editor.Tools
- DomainReloadResilienceTests: Tests.EditMode.Tools → MCPForUnityTests.Editor.Tools
- Matrix4x4ConverterTests: MCPForUnityTests.EditMode.Helpers → MCPForUnityTests.Editor.Helpers
* Refactor test result message formatting
* Simplify RunTests warning assertions
* Tests: de-flake cold-start EditMode runs
- Make ManageScriptableObjectTests setup yield-based with longer Unity-ready timeout
- Mark DomainReloadResilienceTests explicit to avoid triggering domain reload during Run All
* Harden PlayMode test runs
- Guard against starting tests while already in Play Mode.
- Pre-save dirty scenes before PlayMode runs to avoid SaveModifiedSceneTask failures.
- Temporarily disable domain reload during PlayMode tests to keep the MCP bridge alive; restore settings afterward.
- Avoid runSynchronously because it can freeze Unity
* Handle the not too uncommon case where we have an empty scene
* deps: add tomli>=2.3.0 dependency to UnityMcpServer package
* feat: dynamically fetch package version from pyproject.toml for telemetry
* Add pydantic
* feat: add resource registry for MCP resource auto-discovery
* feat: add telemetry decorator for tracking MCP resource usage
* feat: add auto-discovery and registration system for MCP resources
* feat: add resource registration to MCP server initialization
* feat: add MCPResponse model class for standardized API responses
* refactor: replace Debug.Log calls with McpLog wrapper for consistent logging
* feat: add test discovery endpoints for Unity Test Framework integration
We haven't connected them as yet, still thinking about how to do this neatly
* Fix server setup
* refactor: reduce log verbosity by changing individual resource/tool registration logs to debug level
* chore: bump mcp[cli] dependency from 1.15.0 to 1.17.0
* refactor: remove Context parameter and add uri keyword argument in resource decorator
The Context parameter doesn't work on our version of FastMCP
* chore: upgrade Python base image to 3.13 and simplify Dockerfile setup
* fix: apply telemetry decorator before mcp.tool to ensure proper wrapping order
* fix: swap order of telemetry and resource decorators to properly wrap handlers
* fix: update log prefixes for consistency in logging methods
* Fix compile errors
* feat: extend command registry to support both tools and resources
* Run get tests as a coroutine because it doesn't return results immediately
This works but it spams logs like crazy, maybe there's a better/simpler way
* refactor: migrate from coroutines to async/await for test retrieval and command execution
* feat: add optional error field to MCPResponse model
* Increased timeout because loading tests can take some time
* Make message optional so error responses that only have success and error don't cause Pydantic errors
* Set max_retries to 5
This connection module needs a lookover. The retries should be an exponential backoff and we could structure why it's failing so much
* Use pydantic model to structure the error output
* fix: initialize data field in GetTestsResponse to avoid potential errors
* Don't return path parameter
* feat: add Unity test runner execution with structured results and Python bindings
* refactor: simplify GetTests by removing mode filtering and related parsing logic
* refactor: move test runner functionality into dedicated service interface
* feat: add resource retrieval telemetry tracking with new record type and helper function
* fix: convert tool functions to async and await ctx.info calls
* refactor: reorganize menu item functionality into separate execute and get commands
An MCP resource for retrieval, and a simple command to execute. Because it's a resource, it's easier for the user to see what's in the menu items
* refactor: rename manage_menu_item to execute_menu_item and update tool examples to use async/await
We'll eventually put a section for resources
* Revert "fix: convert tool functions to async and await ctx.info calls"
This reverts commit 012ea6b7439bd1f2593864d98d03d9d95d7bdd03.
* fix: replace tomllib with tomli for Python 3.10 compatibility in telemetry module
* Remove confusing comment
* refactor: improve error handling and simplify test retrieval logic in GetTests commands
* No cache by default
* docs: remove redundant comment for HandleCommand method in ExecuteMenuItem
dsarno
Marcus Sanatan
Voon Foo