Swift Testing Agent Skill

April 8, 2026 ยท View on GitHub

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

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:

  1. Add the marketplace:
/plugin marketplace add AvdLee/Swift-Testing-Agent-Skill
  1. 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

  1. Clone this repository.
  2. Install or symlink the swift-testing-expert/ folder following your tool's official skills installation docs (see links below).
  3. 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.

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:

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.