docs(reference): add run_tests and get_test_job examples

website/docs/reference/tools/testing/get_test_job.md

@@ -30,6 +30,45 @@ A `dict` containing the Unity response. The exact shape depends on the action.
 ## Examples
 
 <!-- examples:start -->
-*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": "<job_id from run_tests>",
+  "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": "<job_id from run_tests>"
+}
+```
+
+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.
+
+### Get details for every test
+
+> Show me the result of every test, not just the failures.
+
+```json
+{
+  "job_id": "<job_id from run_tests>",
+  "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.
 <!-- examples:end -->
 

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
 
 <!-- examples:start -->
-*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"]
+}
+```
+
+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
+
+> 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. `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.
 <!-- examples:end -->