unity-test

**调用此模块中的任何 skill 前：**如果你打算根据 skill 的名称或描述猜测参数后调用它，请停下——先阅读此文件（或通过 GET /skills/recommend?includeSchema=true 获取其 schema）。如果你已通过 recommend/schema 获取参数定义，则可以直接执行 dryRun。

触发条件

• 运行 EditMode/PlayMode 测试
• 发现或列出测试
• 轮询异步测试结果
• 创建测试文件
• 运行 EditMode/PlayMode 测试、发现或列出测试、轮询异步测试结果、生成测试文件

测试 Skills

运行和管理 Unity 测试。

操作模式

• 审批：只读 skill（test_get_result / test_list / test_discover_get_result / test_get_last_result / test_list_categories / test_smoke_skills / test_get_summary，标记为 SkillMode.SemiAuto）直接执行；执行/发现/创建类 skill（test_run / test_run_by_name / test_discover_start / test_cancel / test_create_editmode / test_create_playmode，默认 SkillMode.FullAuto）需要用户授权，授权后由服务端一步执行并返回结果（job 会立即进入队列）。

• 自动 / 绕过：直接执行。

• 本模块有 4 个 NeverInSemi skill（由 IsForbiddenInSemi 自动判定）：

  • MayEnterPlayMode = true：test_run、test_run_by_name
  • MayTriggerReload = true：test_create_editmode、test_create_playmode（同时标记 MutatesAssets = true）

  在审批模式下，这 4 个 skill 会返回 MODE_FORBIDDEN，只有 Bypass 或命中 Allowlist 才能绕过。注意：test_run(testMode="PlayMode") / test_run_by_name 会让 Unity TestRunner 切换到 PlayMode；test_create_editmode / test_create_playmode 将新的 .cs 文件写入磁盘后会触发 Domain Reload。

• 异步约定：test_run / test_run_by_name / test_discover_start / test_create_* 会立即返回 jobId；使用 test_get_result(jobId) / test_discover_get_result(jobId) 轮询；Unity TestRunner 会串行执行，测试正在运行时不要再启动第二个 test_run。

请勿（常见臆测）：

• 不存在 test_run_all → 使用 test_run 或 test_run_by_name
• 不存在 test_create_template → 使用 test_create_editmode 或 test_create_playmode
• 不存在 test_get_status → 使用测试运行返回的 jobId 调用 test_get_result
• 测试 skills 为异步执行——它们会返回 jobId，请使用 test_get_result(jobId) 轮询
• 此处的 Unity Test Runner 会串行执行：另一个测试 job 尚未结束时，不要启动第二个 test_run
• 请优先使用 unity_skills.get_skills(category="Test") 或 GET /skills/schema 获取准确签名，不要凭记忆猜测

路由：

• 检查编译错误 → 使用 debug 模块的 debug_check_compilation
• 创建测试脚本 → 使用 test_create_editmode / test_create_playmode，然后通过 script 模块修改
• 跨多个 skill 进行广泛回归探测 → 使用 test_smoke_skills，它会使用临时探测，避免污染工作流/批处理持久化数据

Skills

test_list

通过 Unity Test Runner 异步发现功能列出可用测试。首次调用（缓存未命中）会返回 pendingDiscovery=true 和 discoveryJobId——请轮询 test_discover_get_result(jobId)，然后重试 test_list。 参数：

• testMode（string，可选）：EditMode 或 PlayMode。默认值：EditMode。
• limit（int，可选）：列出测试的最大数量。默认值：100。

返回值： { success, testMode, count, total, truncated, tests, pendingDiscovery, discoveryJobId, discoveryStatus }——其中 count 是返回的数量，total 是发现的测试总数，truncated: true 表示应提高 limit。（test_discover_get_result 中的 count 表示总数——请参阅其中的警告。）

test_run

异步运行 Unity 测试。会立即返回 jobId；请使用 test_get_result(jobId) 轮询。 参数：

• testMode（string，可选）：EditMode 或 PlayMode。默认值：EditMode。 返回值： { success, status, jobId, kind, testMode, filter, message }

test_get_result

获取测试运行结果。 参数：

• jobId（string，必填）：来自 test_run / test_run_by_name 的作业 ID。

返回： { success, jobId, status, totalTests, passedTests, failedTests, skippedTests, inconclusiveTests, otherTests, failedTestNames, failedTestDetails, elapsedSeconds, resultSummary, error } — 每条失败详情都包含 name、resultState、message、stackTrace、durationSeconds 和 output。

test_cancel

如果支持，则取消正在运行的测试作业（Unity TestRunner 无法强制取消，因此尽力而为）。 参数：

• jobId（string，必填）：要取消的作业 ID。

返回： { success, jobId, status, cancelled, note, warnings }

test_discover_start

启动异步 Unity Test Runner 发现，并返回发现任务的 jobId。如果需要显式控制发现过程，请直接使用此工具；否则，test_list / test_list_categories 会在缓存未命中时触发发现。

参数	类型	必填	默认值	描述
testMode	string	否	EditMode	EditMode 或 PlayMode

返回： { success, status, jobId, kind, testMode, message }

test_discover_get_result

获取异步 Unity Test Runner 发现任务的结果。

参数	类型	必填	默认值	描述
jobId	string	是	-	发现任务 ID
limit	int	否	100	响应中的最大测试数；默认值会静默截断较大的测试套件

返回： { success, jobId, status, testMode, discoveryMode, count, returned, truncated, tests, error }

此处的 count 是总数，returned 是实际返回数。 count 是发现的测试数，returned 是应用 limit 后 tests 中的测试数；truncated: true 表示两者不同——提高 limit 即可查看其余测试。包含 300 个测试的项目在使用默认值时会返回 count: 300, returned: 100, truncated: true。切勿根据 len(tests) 推断测试套件大小。

⚠️ test_list 中的 count 含义正好相反。 在 test_list 中，count 是返回的数量，total 是发现的数量；而此处 count 是发现的数量，returned 是返回的数量。这两个工具的设计如此，且各自的 count 为兼容线协议而固定，因此不要假定两者对称——请查看两者都有的 truncated，判断列表是否不完整；总数则从 test_list 的 total 和此处的 count 获取。

test_run_by_name

按类名或方法名运行指定测试。

参数	类型	必填	默认值	描述
testName	string	是	-	要运行的测试类名或方法名
testMode	string	否	EditMode	EditMode 或 PlayMode

返回： { success, jobId, testName, testMode }

test_get_last_result

获取最近一次测试运行结果。

无参数。

返回： { jobId, status, total, passed, failed, skipped, inconclusive, other, failedNames }

test_list_categories

通过 Unity Test Runner 异步发现列出测试类别。缓存未命中时的处理方式和轮询模式与 test_list 相同。

参数	类型	必填	默认值	描述
testMode	string	否	EditMode	EditMode 或 PlayMode

返回： { success, count, categories, pendingDiscovery, discoveryJobId, discoveryStatus }

test_smoke_skills

对已注册的技能运行可复用的冒烟测试。

参数	类型	必填	默认值	描述
category	string	否	-	仅测试一个技能类别（SkillCategory 名称；如果名称未知，则拒绝执行，而不是测试所有技能）
nameContains	string	否	-	按部分名称筛选技能
excludeNamesCsv	string	否	-	要排除的技能名称，以逗号分隔
executeReadOnly	bool	否	true	直接执行安全的只读技能
includeMutating	bool	否	true	通过 dryRun 冒烟测试包含会修改内容的技能
limit	int	否	0	要检查的技能数量上限；0 表示全部

返回： { success, totalSkills, executedCount, dryRunCount, failureCount, results }

test_create_editmode

创建 EditMode 测试脚本模板。同步写入 .cs 文件并返回编译监控 jobId；创建脚本将触发 Domain Reload，因此服务可能会暂时不可用——serverAvailability 会提示这一暂时不可用情况。

参数	类型	必填	默认值	描述
testName	string	是	-	要创建的测试类名称
folder	string	否	Assets/Tests/Editor	测试脚本的文件夹路径

返回： { success, status, path, testName, jobId, serverAvailability }

test_create_playmode

创建 PlayMode 测试脚本模板。同步写入 .cs 文件并返回编译监控 jobId；Domain Reload 和暂时不可用提示与 test_create_editmode 相同。

参数	类型	必填	默认值	描述
testName	string	是	-	要创建的测试类名称
folder	string	否	Assets/Tests/Runtime	测试脚本的文件夹路径

返回： { success, status, path, testName, jobId, serverAvailability }

test_get_summary

获取所有运行的聚合测试摘要。

无参数。

返回： { success, totalRuns, completedRuns, totalPassed, totalFailed, totalSkipped, totalInconclusive, totalOther, allFailedTests }

---

最简示例

import unity_skills, time

# Run tests and poll for result (async pattern required)
result = unity_skills.call_skill("test_run", testMode="EditMode")
job_id = result["jobId"]

# Poll until done (test_* skills are async)
for _ in range(30):
    status = unity_skills.call_skill("test_get_result", jobId=job_id)
    if status.get("status") == "Completed":
        print(f"Passed: {status['totalPassed']}, Failed: {status['totalFailed']}")
        break
    time.sleep(2)

完整签名

准确的名称、参数、默认值和返回值由 GET /skills/schema 或 unity_skills.get_skill_schema() 定义，而非此文件。