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

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

Updating After a Release

If Claude Code still shows an older version after a new GitHub release, refresh the marketplace before reinstalling or updating the Skill:

/plugin marketplace update swift-testing-agent-skill

Claude Code reads available plugin versions from your local marketplace copy, so updating the marketplace is what pulls the latest .claude-plugin/marketplace.json.

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:

Codex: Where to save skills
Claude: Using Skills
Cursor: Enabling Skills

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.

Practical and concise: Emphasizes playbooks and decision points teams actually use during migrations and ongoing test maintenance.

Skill Structure

swift-testing-expert/
  SKILL.md
  references/
    _index.md
    async-testing-and-waiting.md - Async waiting, continuations, and callback-event testing
    expectations.md - #expect, #require, throw checks, and known issues
    fundamentals.md - @Test, suites, structure, and naming patterns
    migration-from-xctest.md - Incremental XCTest coexistence and migration strategy
    parallelization-and-isolation.md - Parallel defaults, randomized order, and .serialized usage
    parameterized-testing.md - Single/multi-argument tests, zip pairing, and scaling
    performance-and-best-practices.md - High-signal testing defaults for speed, determinism, and flakiness prevention
    traits-and-tags.md - Traits, tags, conditions, bug links, and test-plan filtering
    xcode-workflows.md - Test navigator/report workflows and diagnostics practices

Resources

This skill is based on:

Swift Testing category on SwiftLee - complete article set on modern Swift Testing patterns
WWDC 2024-10179: Meet Swift Testing transcript - foundational APIs and migration context
WWDC 2024-10195: Go further with Swift Testing transcript - advanced workflows for tags, test plans, and parallelism
Defining test functions (Apple Developer Documentation) - canonical guidance on declaring and customizing tests
Organizing test functions with suite types (Apple Developer Documentation) - suite behavior, inheritance, and initializer/availability constraints
Migrating a test from XCTest (Apple Developer Documentation) - official migration mappings and async/testing semantics

Contributing

Contributions are welcome! This repository follows the Agent Skills open format, which has specific structural requirements.

We strongly recommend using AI assistance for contributions:

Use the skill-creator skill to ensure proper formatting
This helps maintain the Agent Skills format and ensures your contribution works correctly with AI agents

Please read CONTRIBUTING.md for:

How to update SKILL.md and references safely
Agent Skills format requirements
Quality standards and review criteria
Pull request process

About the Author

Created by Antoine van der Lee. This skill distills Swift Testing guidance from SwiftLee articles and WWDC material into an implementation-oriented playbook for AI assistants.

License

This skill is open-source and available under the MIT License. See LICENSE for details.

swift-testing-expert