itsnex1sitsnex1s/awesome-claude-skills/skills/xcode-mcp-app-testing/SKILL.md

xcode-mcp-app-testing

Skill5 starsChanged 10 months agoMITView on GitHub

MCP-first testing workflow for Xcode apps (iOS, iPadOS, macOS). Use when the user asks to build, test, run, or verify an Xcode project — including UI checks, smoke tests, regression tests, or simulator launches. Prefers Xcode MCP tools via mcpbridge; falls back to xcodebuild/simctl CLI when MCP is unavailable.

In this repository11 other files it gives its agents.
- agent-browserSkill
- apple-docsSkill
- changelog-generatorSkill
- code-reviewSkill
- database-cliSkill
- docker-cliSkill
- github-actionsSkill
- git-workflowSkill
- lighthouse-auditSkill
- testingSkill
- vercel-cliSkill

The file

We split this skill into the rules it gives an agent

4 rules. About 0 are common, 2 are distinctive, and 2 are very specific to this project.

≈0
Common · estimate
Many files like this have a rule of this kind.
≈2
Distinctive · estimate
This author's own choices. Worth a look.
2
Very specific
Tied to their project's names, files or tools. Probably skip.

Common
Distinctive
Very specific

Very specific:
If xcode does not appear: re-run the add command, confirm the Xcode Tools toggle is enabled, and restart Claude Code.
line 27
Distinctive:
Stop and report immediately on build failure with the shortest actionable error summary.
line 97
Distinctive:
When no explicit test plan is provided, verify:
line 142
Very specific:
When the project builds a simulator executable instead of .app, use simctl spawn for process-level checks
line 189

≈ “Common” is an estimate: at least 1 in 5 of the 350,495 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.

Files

SKILL.md

Xcode MCP App Testing

Build, test, and validate Xcode apps using the native Xcode MCP server (Xcode 26.3+). Falls back to xcodebuild/simctl CLI when MCP is not connected.

Installation

Enable Xcode MCP server

Open Xcode → Settings (⌘,) → Intelligence
Under Model Context Protocol, toggle Xcode Tools to ON

Register with Claude Code

claude mcp add --transport stdio xcode -- xcrun mcpbridge
claude mcp list  # verify "xcode" appears

If xcode does not appear: re-run the add command, confirm the Xcode Tools toggle is enabled, and restart Claude Code.

Xcode MCP Tools Reference

Build & Testing

Tool	Purpose
`BuildProject`	Compile the project for a scheme and destination
`GetBuildLog`	Retrieve build output (errors, warnings, notes)
`RunAllTests`	Execute the full test suite
`RunSomeTests`	Run specific test targets or test methods
`GetTestList`	Enumerate all available test cases

Diagnostics

Tool	Purpose
`XcodeListNavigatorIssues`	List all current warnings and errors
`XcodeRefreshCodeIssuesInFile`	Re-scan a specific file for issues

File Operations

Tool	Purpose
`XcodeRead`	Read file contents
`XcodeWrite`	Create a new file
`XcodeUpdate`	Modify an existing file
`XcodeGlob`	Find files by pattern
`XcodeGrep`	Search text across the project
`XcodeLS`	List directory contents
`XcodeMakeDir`	Create directories
`XcodeRM`	Delete files or directories
`XcodeMV`	Move or rename items

Intelligence & Preview

Tool	Purpose
`ExecuteSnippet`	Run Swift code in a REPL environment
`RenderPreview`	Capture SwiftUI preview screenshots
`DocumentationSearch`	Search Apple docs and WWDC transcripts

Workspace

Tool	Purpose
`XcodeListWindows`	List open Xcode project windows

Execution Workflow

1. Detect project context

MCP: XcodeListWindows → XcodeLS → XcodeGlob for .xcodeproj, .xcworkspace, Package.swift

CLI fallback:

find . -maxdepth 2 \( -name "*.xcodeproj" -o -name "*.xcworkspace" -o -name "Package.swift" \) | head -10
xcodebuild -list

2. Build

MCP: BuildProject with scheme and destination → on failure, GetBuildLog for diagnostics

CLI fallback:

xcodebuild -scheme <SCHEME> -destination 'platform=iOS Simulator,name=<DEVICE>' build 2>&1

Stop and report immediately on build failure with the shortest actionable error summary.

3. Run tests

MCP: GetTestList to discover tests → RunAllTests or RunSomeTests for targeted runs

CLI fallback:

xcodebuild -scheme <SCHEME> -destination 'platform=iOS Simulator,name=<DEVICE>' test 2>&1

Capture failing test names, file references, and failure messages.

4. UI / functional validation

MCP: RenderPreview for SwiftUI screenshot capture. For runtime validation, combine with simulator launch.

CLI fallback:

xcrun simctl boot <UDID>
xcrun simctl bootstatus <UDID> -b
xcrun simctl install <UDID> <APP_PATH>
xcrun simctl launch <UDID> <BUNDLE_ID>
xcrun simctl io <UDID> screenshot /tmp/screen.png

5. Diagnostics

MCP: XcodeListNavigatorIssues → XcodeRefreshCodeIssuesInFile for specific files → GetBuildLog for crash details

CLI fallback:

xcrun simctl diagnose <UDID>

6. Quick code verification

MCP: ExecuteSnippet — run Swift snippets in REPL to verify logic without a full build cycle

7. Documentation lookup

MCP: DocumentationSearch — search Apple docs and WWDC transcripts with semantic search

Minimum Smoke Checklist

When no explicit test plan is provided, verify:

App launches without crash
Main navigation loads and is interactive
Primary user flow completes (create / save / send / main CTA)
Permission-gated paths handled (granted + denied states)
Error and empty states render without UI breakage

Reporting Format

Structure the final output as:

Environment — scheme, destination, build config, MCP status (connected / fallback)
Executed — build result, test results, UI flows, artifacts collected
Findings — ordered by severity (P0 critical → P3 cosmetic) with exact repro steps
Evidence — screenshot paths, log excerpts
Next actions — minimal fix plan, prioritized

Common Destinations

# List available simulators
xcrun simctl list devices available

# Common destinations for xcodebuild
'platform=iOS Simulator,name=iPhone 16 Pro'
'platform=iOS Simulator,name=iPhone SE (3rd generation)'
'platform=iOS Simulator,name=iPad Pro 13-inch (M4)'
'platform=macOS'

Troubleshooting

Problem	Fix
`xcode` not in `claude mcp list`	Re-run `claude mcp add`, confirm Xcode Tools toggle, restart Claude Code
MCP connects but cannot access project	Open the project in Xcode first; mcpbridge auto-detects the Xcode process
Build succeeds in Xcode but fails via CLI	Check scheme sharing: Xcode → Manage Schemes → mark scheme as Shared
`simctl` cannot find device	Run `xcrun simctl list devices available` to get correct UDID/name
Tests time out	Add `-test-timeouts-enabled YES -default-test-execution-time-allowance 300`

Notes

Xcode must be running with the project open for MCP tools to work
mcpbridge communicates with Xcode via XPC — no network required
RenderPreview returns actual screenshot images of SwiftUI previews
ExecuteSnippet runs in an isolated Swift REPL, useful for quick logic checks
When the project builds a simulator executable instead of .app, use simctl spawn for process-level checks

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

It worked
Partly
It didn't

What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

Check your setup, free