Swift Testing Agent Skill
Expert guidance for any AI coding tool that supports the Agent Skills open format - modern Swift Testing APIs, XCTest migration, parameterized tests, traits/tags, async testing, and parallel execution patterns.
This repository distills practical Swift Testing best practices into actionable, concise references for agents and code review workflows.
Who this is for
- Teams adopting Swift Testing who want quick, correct defaults
- Developers migrating existing XCTest suites incrementally
- Anyone debugging flaky tests, parallel test behavior, or async test reliability
See also my other skills:
How to Use This Skill
Option A: Using skills.sh (recommended)
Install this skill with a single command:
npx skills add https://github.com/avdlee/swift-testing-agent-skill --skill swift-testing-expert
For more information, visit the skills.sh platform page.
Then use the skill in your AI agent, for example:
Use the swift testing skill and review this test target for migration opportunities and flaky parallel behavior.
Option B: Claude Code Plugin
Personal Usage
To install this Skill for your personal use in Claude Code:
- Add the marketplace:
/plugin marketplace add AvdLee/Swift-Testing-Agent-Skill
- Install the Skill:
/plugin install swift-testing-expert@swift-testing-agent-skill
Project Configuration
To automatically provide this Skill to everyone working in a repository, configure the repository's .claude/settings.json:
{
"enabledPlugins": {
"swift-testing-expert@swift-testing-agent-skill": true
},
"extraKnownMarketplaces": {
"swift-testing-agent-skill": {
"source": {
"source": "github",
"repo": "AvdLee/Swift-Testing-Agent-Skill"
}
}
}
}
When team members open the project, Claude Code will prompt them to install the Skill.
Option C: Manual install
- Clone this repository.
- Install or symlink the
swift-testing-expert/ folder following your tool's official skills installation docs (see links below).
- Use your AI tool as usual and ask it to use the "swift-testing-expert" skill for Swift Testing tasks.
Where to Save Skills
Follow your tool's official documentation, here are a few popular ones:
How to verify:
Your agent should reference the routing/playbook in swift-testing-expert/SKILL.md and jump into the relevant file in swift-testing-expert/references/.
What This Skill Offers
This skill gives your AI coding tool practical Swift Testing guidance. It can:
Guide Your Test Architecture Decisions
- Choose when to use suites, traits, tags, and display names
- Convert repetitive tests into parameterized tests with clean argument design
- Apply parallel-safe patterns and know when
.serialized is a temporary compromise
- Set up tag-driven test plan filtering and report analysis workflows
Write Better Swift Tests
- Use
#expect effectively with rich diagnostics
- Use
#require for prerequisite flow and safer unwrapping
- Model thrown-error expectations clearly
- Improve output readability with test-specific descriptions
Migrate from XCTest Pragmatically
- Coexist Swift Testing and XCTest in one target during migration
- Map common
XCTAssert* patterns to Swift Testing macros
- Keep XCTest where still required (
XCUIApplication, XCTMetric, Objective-C tests)
- Convert duplicated XCTest methods into parameterized Swift Testing coverage
Improve Reliability and Performance
- Remove hidden inter-test dependencies surfaced by randomized, parallel execution
- Stabilize server-side tests with repository isolation and in-memory implementations
- Bridge callback APIs to async/await for deterministic tests
- Reduce CI noise with known-issue handling and actionable trait metadata
What Makes This Skill Different
Source-grounded: Built from SwiftLee's complete Swift Testing article set plus WWDC 2024 sessions "Meet Swift Testing" and "Go further with Swift Testing."
Non-Opinionated: Focuses on test correctness, readability, and maintainability without forcing a project architecture.
Modern-first: Prioritizes Swift Testing primitives, parallel defaults, and macro-based diagnostics over legacy assertion styles.
AvdLee