swift-testing · johnrogers — Claude Code skill for Swift Testing
Get guidance for writing Swift Testing tests, migrating from XCTest, and handling async or parameterized cases in Claude Code.
MIT ★ 233 updated 2026-01-18
/plugin marketplace add johnrogers/claude-swift-engineering
/plugin install swift-engineering@claude-swift-engineeringWhat swift-testing does
The skill covers Swift Testing test structure and assertion macros. Use #expect for checks that can report failures together; reserve #require for values that later assertions depend on. It also shows how to test thrown errors, async functions, and callbacks with confirmation.
For XCTest migrations, the skill maps common assertion patterns to their Swift Testing equivalents. Pair input collections with zip: passing multiple collections separately creates a Cartesian product. Tests run in parallel by default, so cases that touch shared files, databases, or singletons can interfere; .serialized is one option for thread-unsafe legacy tests.
What it helps with
- replace XCTest assertions with Swift Testing macros
- check the result of an async operation
- pair test inputs without creating extra combinations
- verify that a callback runs
- prevent tests from interfering through shared state
Example prompts for the agent
- Convert my
XCTestassertions to Swift Testing macros. - Write an async test for
fetchData()and check its result. - Parameterize this test with paired inputs using
zip.
How to install swift-testing
1Plugin marketplace
/plugin marketplace add johnrogers/claude-swift-engineering/plugin install swift-engineering@claude-swift-engineeringThis installs the whole swift-engineering plugin with all its skills
2Skills CLI (Vercel)
npx skills add johnrogers/claude-swift-engineering --skill swift-testing -a claude-code3Manually: put the files in place
~/.claude/skills/swift-testing/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/swift-testing/
1Skills CLI (Vercel)
npx skills add johnrogers/claude-swift-engineering --skill swift-testing -a codex2Manually: put the files in place
.agents/skills/swift-testing/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add johnrogers/claude-swift-engineering --skill swift-testing -a cursor2Manually: put the files in place
.cursor/skills/swift-testing/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install johnrogers/claude-swift-engineering plugins/swift-engineering/skills/swift-testing2Manually: put the files in place
.github/skills/swift-testing/SKILL.md1Skills CLI (Vercel)
npx skills add johnrogers/claude-swift-engineering --skill swift-testing -a gemini-cli2Platform CLI
gemini skills install https://github.com/johnrogers/claude-swift-engineering --path plugins/swift-engineering/skills/swift-testingManually: put the files in place
.devin/skills/swift-testing/SKILL.mdThe legacy .windsurf/skills/ path still works
Claude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about swift-testing
How do I install swift-testing in Claude Code?
Add the marketplace with /plugin marketplace add johnrogers/claude-swift-engineering, then install the plugin with /plugin install swift-engineering@claude-swift-engineering.
What does swift-testing do?
It guides Claude Code in writing tests with Swift Testing and migrating assertions from XCTest. The skill covers async tests, error checks, and parameterized cases.
Why use zip in parameterized tests?
Multiple collections passed without zip generate every possible combination. zip pairs their elements instead.
Source text
SKILL.md · MIT
---
name: swift-testing
description: Use when writing tests with Swift Testing (@Test, #expect, #require), migrating from XCTest, implementing async tests, or parameterizing tests.
---
# Swift Testing Framework
Modern testing with Swift Testing framework. No XCTest.
## Overview
Swift Testing replaces XCTest with a modern macro-based approach that's more concise, has better async support, and runs tests in parallel by default. The core principle: if you learned XCTest, unlearn it—Swift Testing works differently.
## References
- [Apple Documentation](https://developer.apple.com/documentation/testing)
- [Migration Guide](https://steipete.me/posts/2025/migrating-700-tests-to-swift-testing)
## Core Concepts
### Assertions
| Macro | Use Case |
|-------|----------|
| `#expect(expression)` | Soft check — continues on failure. Use for most assertions. |
| `#require(expression)` | Hard check — stops test on failure. Use for preconditions only. |
### Optional Unwrapping
```swift
let user = try #require(await fetchUser(id: "123"))
#expect(user.id == "123")
```
## Test Structure
```swift
import Testing
@testable import YourModule
@Suite
struct FeatureTests {
let sut: FeatureType
init() throws {
sut = FeatureType()
}
@Test("Description of behavior")
func testBehavior() {
#expect(sut.someProperty == expected)
}
}
```
## Assertion Conversions
| XCTest | Swift Testing |
|--------|---------------|
| `XCTAssert(expr)` | `#expect(expr)` |
| `XCTAssertEqual(a, b)` | `#expect(a == b)` |
| `XCTAssertNil(a)` | `#expect(a == nil)` |
| `XCTAssertNotNil(a)` | `#expect(a != nil)` |
| `try XCTUnwrap(a)` | `try #require(a)` |
| `XCTAssertThrowsError` | `#expect(throws: ErrorType.self) { }` |
| `XCTAssertNoThrow` | `#expect(throws: Never.self) { }` |
## Error Testing
```swift
#expect(throws: (any Error).self) { try riskyOperation() }
#expect(throws: NetworkError.self) { try fetch() }
#expect(throws: NetworkError.timeout) { try fetch() }
#expect(throws: Never.self) { try safeOperation() }
```
## Parameterized Tests
```swift
@Test("Validates inputs", arguments: zip(
["a", "b", "c"],
[1, 2, 3]
))
func testInputs(input: String, expected: Int) {
#expect(process(input) == expected)
}
```
**Warning:** Multiple collections WITHOUT zip creates Cartesian product.
## Async Testing
```swift
@Test func testAsync() async throws {
let result = try await fetchData()
#expect(!result.isEmpty)
}
```
### Confirmations
```swift
@Test func testCallback() async {
await confirmation("callback received") { confirm in
let sut = SomeType { confirm() }
sut.triggerCallback()
}
}
```
## Tags
```swift
extension Tag {
@Tag static var fast: Self
@Tag static var networking: Self
}
@Test(.tags(.fast, .networking))
func testNetworkCall() { }
```
## Common Pitfalls
1. **Overusing `#require`** — Use `#expect` for most checks
2. **Forgetting state isolation** — Each test gets a NEW instance
3. **Accidental Cartesian product** — Always use `zip` for paired inputs
4. **Not using `.serialized`** — Apply for thread-unsafe legacy tests
## Common Mistakes
1. **Overusing `#require`** — `#require` is for preconditions only. Using it for normal assertions means the test stops at first failure instead of reporting all failures. Use `#expect` for assertions, `#require` only when subsequent assertions depend on the value.
2. **Cartesian product bugs** — `@Test(arguments: [a, b], [c, d])` creates 4 combinations, not 2. Always use `zip` to pair arguments correctly: `arguments: zip([a, b], [c, d])`.
3. **Forgetting state isolation** — Swift Testing creates a new test instance per test method. BUT shared state between tests (static variables, singletons) still leak. Use dependency injection or clean up singletons between tests.
4. **Parallel test conflicts** — Swift Testing runs tests in parallel by default. Tests touching shared files, databases, or singletons will interfere. Use `.serialized` or isolation strategies.
5. **Not using `async` naturally** — Wrapping async operations in `Task { }` defeats the purpose. Use `async/await` directly in test function signature: `@Test func testAsync() async throws { }`.
6. **Confirmation misuse** — `confirmation` is for verifying callbacks were called. Using it for assertions is wrong. Use `#expect` for assertions, `confirmation` for callback counts.
© John Rogers (@johnrogers) · MIT · johnrogers/claude-swift-engineering
Similar skills
All skills for Testing and QA →swift-testing by other authors comes first.