From 990f4462a67843fddb76d9ebb22a3f92e0259fc1 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?R=C4=B1zgar=20Ozan?= Date: Mon, 14 Sep 2026 00:30:09 +0300 Subject: [PATCH 1/4] docs(reference): add run_tests and get_test_job examples --- .../reference/tools/testing/get_test_job.md | 39 ++++++++++- .../docs/reference/tools/testing/run_tests.md | 66 ++++++++++++++++++- 2 files changed, 103 insertions(+), 2 deletions(-) diff --git a/website/docs/reference/tools/testing/get_test_job.md b/website/docs/reference/tools/testing/get_test_job.md index d16fdfaa4..a14f99f2a 100644 --- a/website/docs/reference/tools/testing/get_test_job.md +++ b/website/docs/reference/tools/testing/get_test_job.md @@ -30,6 +30,43 @@ A `dict` containing the Unity response. The exact shape depends on the action. ## Examples -*No examples yet. Add usage examples here — they will be preserved across regenerations.* +### Wait for a run to finish + +> Wait for the test job I just started and show the failures. + +```json +{ + "job_id": "", + "wait_timeout": 60, + "include_failed_tests": true +} +``` + +With `wait_timeout`, the server polls Unity every 2 seconds and returns as soon as `status` is `succeeded`, `failed` or `cancelled` — or after 60 s with the current progress, in which case call it again. This avoids a tight client-side polling loop. + +### Check progress without waiting + +> How far along is the test run? + +```json +{ + "job_id": "" +} +``` + +Returns straight away. `data.progress` has `completed` / `total`, the test currently running, and `failures_so_far`; `data.result.summary` appears once the job has finished. + +### Get details for every test + +> Show me the result of every test, not just the failures. + +```json +{ + "job_id": "", + "include_details": true +} +``` + +`include_details` returns all tests; `include_failed_tests` returns only failed and skipped ones, which keeps the response small on large suites. diff --git a/website/docs/reference/tools/testing/run_tests.md b/website/docs/reference/tools/testing/run_tests.md index 1fcf8a1e3..95e28e7b9 100644 --- a/website/docs/reference/tools/testing/run_tests.md +++ b/website/docs/reference/tools/testing/run_tests.md @@ -35,6 +35,70 @@ A `dict` containing the Unity response. The exact shape depends on the action. ## Examples -*No examples yet. Add usage examples here — they will be preserved across regenerations.* +### Run every EditMode test + +> Run all EditMode tests and tell me what failed. + +```json +{ + "mode": "EditMode", + "include_failed_tests": true +} +``` + +Returns immediately with a `job_id` and `status: "running"`. Poll it with [`get_test_job`](./get_test_job.md) — the results are not in this response. + +### Run specific tests by full name + +> Re-run only `InventoryTests.AddItem_IncreasesCount`. + +```json +{ + "mode": "EditMode", + "test_names": ["MyGame.Tests.InventoryTests.AddItem_IncreasesCount"], + "include_failed_tests": true +} +``` + +`test_names` must be full names (namespace, class, method). A single string is accepted as well as a list. + +### Run a whole namespace with a regex + +> Run every test under `MyGame.Tests.Inventory`. + +```json +{ + "mode": "EditMode", + "group_names": ["^MyGame\\.Tests\\.Inventory"] +} +``` + +`group_names` takes the same full names as `test_names`, but each entry is a regular expression. Filters can be combined with `category_names` and `assembly_names`. + +### Run PlayMode tests from one assembly + +> Run the PlayMode tests in `MyGame.PlayModeTests`. + +```json +{ + "mode": "PlayMode", + "assembly_names": ["MyGame.PlayModeTests"], + "init_timeout": 120000 +} +``` + +PlayMode runs start with a domain reload, so the default 15 s `init_timeout` is often too short. 120000 ms is the recommended value. + +### Unblock a run lost to a domain reload + +> Every `run_tests` call fails because an old job is still marked as running. + +```json +{ + "clear_stuck": true +} +``` + +Only clears the orphaned job; it does not start a run. The response says `Stuck job cleared.` or `No running job to clear.` Start the run again afterwards. (While a job really is running, `run_tests` answers `tests_running` with `retry_after_ms` instead — wait for it rather than clearing it.) From fe33c98c5b6a9c1eb5c5f6c6107ff72a9aba5b05 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?R=C4=B1zgar=20Ozan?= Date: Sun, 27 Sep 2026 10:50:39 +0300 Subject: [PATCH 2/4] docs(reference): correct get_test_job result and clear_stuck notes --- website/docs/reference/tools/testing/get_test_job.md | 4 +++- website/docs/reference/tools/testing/run_tests.md | 4 ++-- 2 files changed, 5 insertions(+), 3 deletions(-) diff --git a/website/docs/reference/tools/testing/get_test_job.md b/website/docs/reference/tools/testing/get_test_job.md index a14f99f2a..52764ea85 100644 --- a/website/docs/reference/tools/testing/get_test_job.md +++ b/website/docs/reference/tools/testing/get_test_job.md @@ -54,7 +54,9 @@ With `wait_timeout`, the server polls Unity every 2 seconds and returns as soon } ``` -Returns straight away. `data.progress` has `completed` / `total`, the test currently running, and `failures_so_far`; `data.result.summary` appears once the job has finished. +Returns straight away. `data.progress` has `completed` / `total`, the test currently running, and `failures_so_far`. `data.result` (with `summary` and the `include_*` test lists) is only filled when the job succeeded: a run with failing tests ends as `failed` with `result: null`, so read the failures from `data.progress.failures_so_far` (at most 25; `failures_capped` is `true` when more failed) and `data.error`. + +If Unity is in the background and the job has not moved for 3 s, both this call and the `wait_timeout` form start a focus nudge that brings the Unity window to the front for a few seconds and then switches back. This form runs it in the background, so the response is not delayed. ### Get details for every test diff --git a/website/docs/reference/tools/testing/run_tests.md b/website/docs/reference/tools/testing/run_tests.md index 95e28e7b9..3a6f9876d 100644 --- a/website/docs/reference/tools/testing/run_tests.md +++ b/website/docs/reference/tools/testing/run_tests.md @@ -73,7 +73,7 @@ Returns immediately with a `job_id` and `status: "running"`. Poll it with [`get_ } ``` -`group_names` takes the same full names as `test_names`, but each entry is a regular expression. Filters can be combined with `category_names` and `assembly_names`. +Each `group_names` entry is a regular expression matched against the full test name, not a name that has to match exactly. Filters can be combined with `category_names` and `assembly_names`. ### Run PlayMode tests from one assembly @@ -99,6 +99,6 @@ PlayMode runs start with a domain reload, so the default 15 s `init_timeout` is } ``` -Only clears the orphaned job; it does not start a run. The response says `Stuck job cleared.` or `No running job to clear.` Start the run again afterwards. (While a job really is running, `run_tests` answers `tests_running` with `retry_after_ms` instead — wait for it rather than clearing it.) +Only clears the orphaned job; it does not start a run. The response says `Stuck job cleared.` or `No running job to clear.` Start the run again afterwards. `clear_stuck` does not check whether the job is still alive: it marks any job in the `running` state as failed. If a run is really in progress, `run_tests` answers `tests_running` with `retry_after_ms`; wait for it instead, because clearing it does not stop the tests already running in Unity. From 8e34e756bc74c87653d6a167d9f901c14f59aab5 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?R=C4=B1zgar=20Ozan?= Date: Sun, 27 Sep 2026 17:56:51 +0300 Subject: [PATCH 3/4] docs(reference): say when get_test_job sets error and failures_capped --- website/docs/reference/tools/testing/get_test_job.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website/docs/reference/tools/testing/get_test_job.md b/website/docs/reference/tools/testing/get_test_job.md index 52764ea85..8a2127dce 100644 --- a/website/docs/reference/tools/testing/get_test_job.md +++ b/website/docs/reference/tools/testing/get_test_job.md @@ -54,7 +54,7 @@ With `wait_timeout`, the server polls Unity every 2 seconds and returns as soon } ``` -Returns straight away. `data.progress` has `completed` / `total`, the test currently running, and `failures_so_far`. `data.result` (with `summary` and the `include_*` test lists) is only filled when the job succeeded: a run with failing tests ends as `failed` with `result: null`, so read the failures from `data.progress.failures_so_far` (at most 25; `failures_capped` is `true` when more failed) and `data.error`. +Returns straight away. `data.progress` has `completed` / `total`, the test currently running, and `failures_so_far`. `data.result` (with `summary` and the `include_*` test lists) is only filled when the job succeeded: a run with failing tests ends as `failed` with `result: null`, so read the failures from `data.progress.failures_so_far` (at most 25; `failures_capped` turns `true` once 25 are recorded, so there may be more). `data.error` stays `null` for failing tests; it is only set when the job itself broke (did not start in time, threw, or was orphaned by a domain reload). If Unity is in the background and the job has not moved for 3 s, both this call and the `wait_timeout` form start a focus nudge that brings the Unity window to the front for a few seconds and then switches back. This form runs it in the background, so the response is not delayed. From 474286036efc5e3ea3ac945417fcd2c0ba7bfdfd Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?R=C4=B1zgar=20Ozan?= Date: Sun, 27 Sep 2026 20:14:17 +0300 Subject: [PATCH 4/4] docs(reference): list result fields and all get_test_job error cases --- website/docs/reference/tools/testing/get_test_job.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website/docs/reference/tools/testing/get_test_job.md b/website/docs/reference/tools/testing/get_test_job.md index 8a2127dce..c98ceb064 100644 --- a/website/docs/reference/tools/testing/get_test_job.md +++ b/website/docs/reference/tools/testing/get_test_job.md @@ -54,7 +54,7 @@ With `wait_timeout`, the server polls Unity every 2 seconds and returns as soon } ``` -Returns straight away. `data.progress` has `completed` / `total`, the test currently running, and `failures_so_far`. `data.result` (with `summary` and the `include_*` test lists) is only filled when the job succeeded: a run with failing tests ends as `failed` with `result: null`, so read the failures from `data.progress.failures_so_far` (at most 25; `failures_capped` turns `true` once 25 are recorded, so there may be more). `data.error` stays `null` for failing tests; it is only set when the job itself broke (did not start in time, threw, or was orphaned by a domain reload). +Returns straight away. `data.progress` has `completed` / `total`, the test currently running, and `failures_so_far`. `data.result` (`summary`, plus a `results` list when `include_details` or `include_failed_tests` is set) is only filled when the job succeeded: a run with failing tests ends as `failed` with `result: null`, so read the failures from `data.progress.failures_so_far` (at most 25; `failures_capped` turns `true` once 25 are recorded, so there may be more). `data.error` stays `null` for failing tests; it is only set when the job itself did not finish normally (did not start in time, threw, was canceled, was cleared with `clear_stuck`, or was orphaned by a domain reload). If Unity is in the background and the job has not moved for 3 s, both this call and the `wait_timeout` form start a focus nudge that brings the Unity window to the front for a few seconds and then switches back. This form runs it in the background, so the response is not delayed.