/swift-package-testing-workflow

name: swift-package-testing-workflow
description: Guide Swift Testing, XCTest holdouts, code coverage, xctestplan handoff conditions, async test design, semantic accessibility-test boundaries, test-fixture organization, and package test-diagnosis work in existing Swift Package Manager repositories. Use when Package.swift is the source of truth and the task is primarily about testing rather than package build or run work.

Swift Package Testing Workflow

Purpose

Use this skill as the primary execution workflow for test-focused work in existing Swift package components. Keep it focused on Swift Testing, XCTest holdouts, code coverage, `.xctestplan` handoff conditions, async-test guidance, semantic accessibility-test boundaries, performance-sensitive package workload profiling, filters, retries, fixtures, and package-level test diagnosis. `scripts/run-workflow.fsx` resolves the nearest package root and plans the test surface without classifying the containing repository.

When To Use

• Use this skill for running, diagnosing, organizing, or evolving tests in an existing Swift package repo.
• Use this skill for Swift Testing-first package work, XCTest holdouts, async-test design, semantic accessibility-test boundaries, and test-fixture organization.
• Use this skill for package-level `.xctestplan` execution when the package surface needs Xcode test-plan follow-through.
• Use this skill when the request is about test selection, filtering, retries, failures, flaky tests, or test-only Debug/Release validation.
• Use this skill when the request is about package-first performance-sensitive testing, signpost placement, Release workload harnesses, or profiling-ready package test design for Audio, Metal, MLX, local AI, streaming, or other Apple silicon-sensitive workloads.
• Do not use this skill for broad manifest edits, dependency work, package resources, package-extension design, or ordinary build and run work.
• Do not use this skill for brand-new package bootstrap from nothing.
• Do not use this skill for repo-guidance alignment in an existing package repo.
• Do not use this skill as the default path for Xcode workspace, scheme, preview, simulator, or navigator-driven work.
• Recommend `swift-package-build-run-workflow` when the request is primarily about ordinary package build/run, manifest, dependency, resource, or Metal-distribution work.
• Recommend `swift-package-extension-workflow` when trait matrices, macro/plugin test shape, or generated-source validation is the primary concern.
• Recommend `bootstrap-xcode-workspace --operation create --component-kind library` when the package repo does not exist yet.
• Recommend root workspace `just align` when product guidance needs to be refreshed.
• Recommend `xcode-testing-workflow` when test work depends on active Xcode workspace state, navigator diagnostics, simulator or device flows, XCUITest, runtime accessibility verification, or Xcode-native test plans and test execution.
• Recommend `apple-ui-accessibility-workflow` when the request is primarily about accessibility semantics or review rather than package-side testing strategy.
• Recommend `xcode-build-run-workflow` when package test work crosses into guarded mutation, file membership, or other Xcode-managed project-integrity work.
• Recommend `explore-apple-swift-docs` when the user needs Apple or Swift docs exploration before implementation or test changes.

Single-Path Workflow

1. Classify the request into one operation type:

• package inspection
• read or search
• test
• mutation

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

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

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

• apply the detailed local policy in `references/snippets/apple-swift-package-core.md` when package-policy wording is needed
• preserve its simplicity-first, shape-preserving, and anti-ceremony Swift guidance
• preserve its explicit `swiftLanguageModes: [.v6]` package-manifest default and prefer that spelling over the legacy `swiftLanguageVersions` alias on current manifest surfaces
• preserve its package-appropriate logging, telemetry, structured-concurrency, and Swift Testing guidance

4. Run `scripts/run-workflow.fsx` to resolve the nearest package root, confirm the request stays on the testing surface, and plan the package-testing command path. 5. Use `references/code-coverage.md` when the request needs SwiftPM collection, exported-JSON discovery, coverage reporting, comparison, or an explicit coverage-gate boundary. 6. Use `references/package-resources-testing-and-builds.md` when the request touches Swift Testing, XCTest, `.xctestplan`, accessibility-related semantic tests, fixtures, async test discipline, or test-related Debug/Release validation. 7. Use `references/performance-sensitive-testing-and-profiling.md` when the request touches package-first instrumentation, `OSSignposter`, `xctrace`, Time Profiler, Metal System Trace, Allocations, VM Tracker, Audio, MLX, local AI, streaming, or other performance-sensitive Apple silicon workloads. 8. Apply `../../shared/execution-surface-routing.md`; use `xcode-testing-workflow` only for `.xctestplan`, XCUITest, scheme, or destination work. 9. Report which parts were agent-executed, the docs relied on, the resolved package context, and any required next step or handoff.

Inputs

• `operation_type`: one of the operation types listed above.
• `request`: optional short natural-language request text u