Skip to content

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

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
cameroncooke wants to merge 1 commit into
base: main
Choose a base branch
from
+73 −0
Open

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

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 4 additions & 0 deletions app/docs/_content/configuration.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -81,6 +81,9 @@ sessionDefaults:
# Build settings
incrementalBuildsEnabled: false

# Test output
showTestTiming: false

# Debugging and telemetry
debug: false
sentryDisabled: false
Expand Down Expand Up @@ -113,6 +116,7 @@ macosTemplateVersion: "v1.2.3"
| `sessionDefaultsProfiles` | object | `{}` |
| `activeSessionDefaultsProfile` | string | `global` |
| `incrementalBuildsEnabled` | boolean | `false` |
| `showTestTiming` | boolean | `false` |
| `debug` | boolean | `false` |
| `sentryDisabled` | boolean | `false` |
| `debuggerBackend` | string | `"dap"` |
Expand Down
27 changes: 27 additions & 0 deletions app/docs/_content/env-vars.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -27,6 +27,7 @@ Set env vars in the `env` field of your MCP client config (for example `mcp_conf
| `disableXcodeAutoSync` | `XCODEBUILDMCP_DISABLE_XCODE_AUTO_SYNC` |
| `incrementalBuildsEnabled` | `INCREMENTAL_BUILDS_ENABLED` |
| `debug` | `XCODEBUILDMCP_DEBUG` |
| `showTestTiming` | `XCODEBUILDMCP_SHOW_TEST_TIMING` |
| `sentryDisabled` | `XCODEBUILDMCP_SENTRY_DISABLED` |
| `debuggerBackend` | `XCODEBUILDMCP_DEBUGGER_BACKEND` |
| `dapRequestTimeoutMs` | `XCODEBUILDMCP_DAP_REQUEST_TIMEOUT_MS` |
Expand Down Expand Up @@ -59,6 +60,32 @@ Set env vars in the `env` field of your MCP client config (for example `mcp_conf
| `preferXcodebuild` | `XCODEBUILDMCP_PREFER_XCODEBUILD` |
| `bundleId` | `XCODEBUILDMCP_BUNDLE_ID` |

## 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
Expand Down
42 changes: 42 additions & 0 deletions app/docs/_content/output-formats.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -180,6 +180,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. Clients can use that schema to validate `structuredContent` or render typed UI.

## 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:
Expand Down
Loading