docs: document XCODEBUILDMCP_CWD, showTestTiming, and per-test results

app/docs/_content/configuration.mdx

@@ -84,6 +84,9 @@ incrementalBuildsEnabled: false
 # Text output
 filePathRenderStyle: "list" # "list" or "tree"
 
+# Test output
+showTestTiming: false
+
 # Debugging and telemetry
 debug: false
 sentryDisabled: false
@@ -117,6 +120,7 @@ macosTemplateVersion: "v1.2.3"
 | `activeSessionDefaultsProfile` | string | `global` |
 | `incrementalBuildsEnabled` | boolean | `false` |
 | `filePathRenderStyle` | `"list" \| "tree"` | CLI text: `"list"`, MCP text: `"tree"` |
+| `showTestTiming` | boolean | `false` |
 | `debug` | boolean | `false` |
 | `sentryDisabled` | boolean | `false` |
 | `debuggerBackend` | string | `"dap"` |

app/docs/_content/env-vars.mdx

@@ -28,6 +28,7 @@ Set env vars in the `env` field of your MCP client config (for example `mcp_conf
 | `incrementalBuildsEnabled` | `INCREMENTAL_BUILDS_ENABLED` |
 | `filePathRenderStyle` | `XCODEBUILDMCP_FILE_PATH_RENDER_STYLE` (`list` or `tree`) |
 | `debug` | `XCODEBUILDMCP_DEBUG` |
+| `showTestTiming` | `XCODEBUILDMCP_SHOW_TEST_TIMING` |
 | `sentryDisabled` | `XCODEBUILDMCP_SENTRY_DISABLED` |
 | `debuggerBackend` | `XCODEBUILDMCP_DEBUGGER_BACKEND` |
 | `dapRequestTimeoutMs` | `XCODEBUILDMCP_DAP_REQUEST_TIMEOUT_MS` |
@@ -67,6 +68,32 @@ Set env vars in the `env` field of your MCP client config (for example `mcp_conf
 
 The server only exits when the timeout has elapsed, no MCP request is in flight, and no registered runtime operation is active.
 
+## Working directory override
+
+`XCODEBUILDMCP_CWD` overrides the directory XcodeBuildMCP uses to discover `.xcodebuildmcp/config.yaml` and resolve relative paths. Set this when the host that launches XcodeBuildMCP can configure environment variables but not the spawn directory (the most common case is **MCP Inspector**).
+
+| Variable | Behavior |
+|----------|----------|
+| `XCODEBUILDMCP_CWD` | Absolute path; supports a leading `~/`. Falls back to the original cwd with a warning if the directory cannot be entered. |
+
+Example: launch XcodeBuildMCP from anywhere and have it read `~/Projects/MyApp/.xcodebuildmcp/config.yaml`:
+
+```json
+{
+  "mcpServers": {
+    "XcodeBuildMCP": {
+      "command": "npx",
+      "args": ["-y", "xcodebuildmcp@latest", "mcp"],
+      "env": {
+        "XCODEBUILDMCP_CWD": "~/Projects/MyApp"
+      }
+    }
+  }
+}
+```
+
+If you have not set `XCODEBUILDMCP_CWD`, the working directory is whatever the host process spawned XcodeBuildMCP in.
+
 ## Example
 
 ```json

app/docs/_content/output-formats.mdx

@@ -227,6 +227,48 @@ MCP mode always returns the normal `content` array. When a tool sets structured
 
 Tools that declare an [output schema](https://modelcontextprotocol.io/specification/2025-11-25/server/tools#output-schema) also advertise it during MCP registration. For tools with structured output, the advertised schema is a union of the tool's domain envelope and the generic `xcodebuildmcp.output.error` envelope. Clients can use that schema to validate `structuredContent` or render typed UI, but should still branch on the returned `schema` value at runtime.
 
+## Per-test results
+
+Test tools (`test_sim`, `test_device`, `test_macos`, `swift_package_test`) include a `testCases` array on the structured `test-result` response. Each entry has `suite` (optional), `test`, `status` (`passed`, `failed`, or `skipped`), and `durationMs` (optional).
+
+The array is always present in JSON output and MCP `structuredContent` when the run produced any per-case results. The `showTestTiming` config option (or `XCODEBUILDMCP_SHOW_TEST_TIMING=1`) is purely a text-rendering toggle: with it on, `--output text` and MCP `content[]` text include a `Test Results:` block before the summary; with it off, the structured data is still there for programmatic consumers.
+
+```json
+{
+  "schema": "xcodebuildmcp.output.test-result",
+  "schemaVersion": "1",
+  "didError": false,
+  "error": null,
+  "data": {
+    "summary": {
+      "status": "FAILED",
+      "durationMs": 22100,
+      "counts": { "passed": 21, "failed": 2, "skipped": 0 },
+      "target": "simulator"
+    },
+    "testCases": [
+      { "suite": "CalculatorAppTests", "test": "testAddition", "status": "passed", "durationMs": 1 },
+      { "suite": "CalculatorAppTests", "test": "testCalculatorServiceFailure", "status": "failed", "durationMs": 4 },
+      { "suite": "IntentionalFailureTests", "test": "test", "status": "failed", "durationMs": 3 }
+    ],
+    "diagnostics": {
+      "warnings": [],
+      "errors": [],
+      "testFailures": [
+        {
+          "suite": "CalculatorAppTests",
+          "test": "testCalculatorServiceFailure",
+          "message": "XCTAssertEqual failed: (\"0\") is not equal to (\"999\")",
+          "location": "CalculatorAppTests/CalculatorAppTests.swift:52"
+        }
+      ]
+    }
+  }
+}
+```
+
+Parameterized Swift Testing groups currently surface as a single aggregate entry because `xcodebuild` does not emit per-case names or durations for them. Counts in `summary.counts` may exceed the `testCases` array length when parameterization is in use.
+
 ## Response schema reference
 
 Canonical JSON schemas live in the source repository under [`schemas/structured-output/`](https://github.com/getsentry/XcodeBuildMCP/tree/main/schemas/structured-output). Concrete examples: