/xcode-testing-workflow

name: xcode-testing-workflow
description: Guide Swift Testing, XCTest, XCUITest, XCUIAutomation-oriented mechanics, code coverage, xctestplan matrices, accessibility-verification follow-through, test filtering, retries, diagnostics, and test-specific fallback work in existing Xcode-managed projects and workspaces. Use when Xcode-aware execution is needed and the task is primarily about testing rather than build or run work.

Xcode Testing Workflow

Purpose

Use this skill as the primary execution workflow for test-focused work in or around Xcode-managed projects and workspaces. Keep it focused on Swift Testing, XCTest, XCUITest, XCUIAutomation-oriented mechanics, code coverage, `.xctestplan`, destinations, launch arguments, interruption handling, attachments, accessibility-verification follow-through, Instruments profiling, `xctrace` trace capture, filters, retries, diagnostics, and test-specific Debug/Release validation instead of broad build/run or toolchain work. `scripts/run-workflow.fsx` is the runtime entrypoint for MCP-first test execution, official CLI fallback planning, and the remaining `.pbxproj` warning boundary when mutation enters project-file territory.

When To Use

• Use this skill for Xcode test execution, test diagnosis, test filtering, retries, destination selection, and test-plan work.
• Use this skill for Swift Testing, XCTest, XCUITest, XCUIAutomation-oriented mechanics, `.xctestplan`, flaky-test diagnosis, accessibility-verification follow-through, and test-only configuration validation.
• Use this skill for Instruments and `xctrace` follow-through when performance-sensitive tests need Time Profiler, Metal System Trace, Allocations, VM Tracker, Points of Interest, signpost-aligned traces, or `.trace` artifact interpretation.
• Use this skill for Xcode MCP operations and official Apple CLI fallback when the work is primarily about tests rather than build/run.
• Use this skill when direct filesystem mutation around tests or test plans may be required.
• Recommend `xcode-coding-intelligence-workflow` when the request is primarily about Xcode Intelligence setup, Xcode-hosted agents, external-agent access through `xcrun mcpbridge`, command/tool permissions, or Xcode-only agent configuration homes.
• Do not use this skill as the default path for ordinary build, run, preview, archive, or general project-integrity work.
• Recommend `xcode-build-run-workflow` when the task is primarily about build, run, previews, file membership, archives, toolchains, or guarded non-test mutation work.
• Recommend `explore-apple-swift-docs` when the user needs Apple or Swift documentation lookup rather than execution work.
• Recommend `swift-package-testing-workflow` when the task is package-first testing outside Xcode-managed execution.
• Recommend `bootstrap-xcode-workspace --operation align` when an existing Apple product workspace needs managed guidance alignment rather than active engineering work.

Single-Path Workflow

1. Classify the request into one operation type:

• read, search, or diagnostics
• test
• mutation

2. Apply the Apple docs gate before any Apple design, architecture, implementation, or refactor guidance:

• use `explore-apple-swift-docs` to gather the relevant Apple documentation first
• state the documented API behavior, lifecycle rule, or workflow requirement being relied on before proposing changes
• do not rely on memory as the primary source when Apple docs exist
• if the docs and the current code conflict, stop and report that conflict
• if no relevant Apple docs can be found, say that explicitly before proceeding

3. Apply the shared Swift policy before giving implementation guidance:

• apply the detailed local policy in `references/snippets/apple-xcode-project-core.md`
• preserve its simplicity-first, shape-preserving, and anti-ceremony Swift guidance
• preserve its project-appropriate logging, telemetry, and SwiftUI architecture guidance

4. Run `scripts/run-workflow.fsx` to apply runtime configuration, `.pbxproj` warning safeguards, and CLI fallback planning. 5. Use the focused references for the right testing surface:

• `references/code-coverage.md` for Xcode coverage collection, `.xcresult` artifacts, `xccov` reporting, comparison, and the Xcode 27 MCP boundary
• `references/xctestplan-configurations-and-matrix.md` for `.xctestplan`, launch-argument matrices, named configurations, and Debug/Release test coverage
• `references/xcuitest-and-xcuiautomation.md` for UI automation mechanics, waits, interruption handling, activities, and attachments
• `references/ios-ui-automation-destinations.md` for iOS simulator-versus-physical-device XCUITest decisions, destination evidence, and physical-device debugging handoffs
• `references/ui-accessibility-verification.md` for accessibility-specific runtime verification expectations and coordination with `apple-ui-accessibility-workflow`
• `references/macos-ui-test-permission-ownership.md` for macOS prompt attribution, test-host ownership, app launch/restore boundaries, and opt-in prompt-heavy test plans
• `references/instruments-performance-profiling.md` for Instruments, `xctrace`, Time Profiler, Metal System Trace, Allocations, VM Tracker, Points of Interest, and signpost-aligned trace evidence
• `references/testing-plans-file-membership-and-configurations.md` for the condensed cross-cutting summary and file-membership reminder

6. Use `references/xcodegen-project-maintenance.md` when the repo is XcodeGen-backed and the task touches generated test targets, scheme test actions, test-plan references, launch arguments, environment variables, or test bundle membership. 7. If MCP fails, use the structured fallback output from `scripts/run-workflow.fsx` together with `references/cli-fallback-matrix.md`. 8. Report which parts were agent-executed, which parts were locally enforced by script, the Apple docs relied on, any tracked `.pbxproj` diff that must be