From e8eeeeee56ad16328a152ea92e9db01637568d2c Mon Sep 17 00:00:00 2001 From: Cameron Cooke Date: Tue, 28 Apr 2026 11:31:52 +0100 Subject: [PATCH] docs: document XCODEBUILDMCP_CWD, showTestTiming, and per-test results Three new pieces of public surface coming in XcodeBuildMCP 2.4: - XCODEBUILDMCP_CWD env var for working directory override (env-vars.mdx). Most useful when launching XcodeBuildMCP from a host that can configure env vars but not the spawn directory (e.g. MCP Inspector). - showTestTiming config option / XCODEBUILDMCP_SHOW_TEST_TIMING env var (configuration.mdx, env-vars.mdx). Toggles the per-test "Test Results:" block in text output. - testCases array on the structured xcodebuildmcp.output.test-result response (output-formats.mdx). Always emitted in JSON / structured content; the showTestTiming flag only controls text rendering. Tracks getsentry/XcodeBuildMCP#374. --- app/docs/_content/configuration.mdx | 4 +++ app/docs/_content/env-vars.mdx | 27 ++++++++++++++++++ app/docs/_content/output-formats.mdx | 42 ++++++++++++++++++++++++++++ 3 files changed, 73 insertions(+) diff --git a/app/docs/_content/configuration.mdx b/app/docs/_content/configuration.mdx index 16c111a..5f3c6c5 100644 --- a/app/docs/_content/configuration.mdx +++ b/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"` | diff --git a/app/docs/_content/env-vars.mdx b/app/docs/_content/env-vars.mdx index d9c3c35..a2cb8ab 100644 --- a/app/docs/_content/env-vars.mdx +++ b/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 diff --git a/app/docs/_content/output-formats.mdx b/app/docs/_content/output-formats.mdx index e2232de..d37838d 100644 --- a/app/docs/_content/output-formats.mdx +++ b/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: