Skip to main content
skill CX Codex

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

Install into Claude Code · Plugin marketplace All methods and platforms ↓
/plugin marketplace add johnrogers/claude-swift-engineering
/plugin install swift-engineering@claude-swift-engineering
Open on GitHub

What 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 XCTest assertions 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-engineering

This 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-code

3Manually: put the files in place

~/.claude/skills/swift-testing/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/swift-testing/

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.

swift-testing dpearson2699 Writes Swift Testing unit tests and converts existing XCTest assertions, flagging which checks belong in XCTest or XCUITest. CX Codex +1 4,700installs swift-testing Prisma-Labs-Dev Hands your agent a local Swift Testing reference: @Test, @Suite, #expect, #require, parameterized tests, XCTest migration. CX Codex +1 746installs swift-testing-expert AvdLee swift-testing-expert coaches your agent through Swift Testing: #expect and #require macros, tags, parameterized tests, and moving a suite off XCTest. CX Codex +1 5,700installs swift-testing-pro Paul Hudson swift-testing-pro — a skill for Claude Code, Codex, Cursor and other agents that writes, audits, and fixes Swift Testing code against Swift 6.2 APIs. Covers async tests, actor isolation, XCTest migration, and new framework features. CX Codex +1 10,900installs guide-swift-testing Prisma-Labs-Dev guide-swift-testing provides patterns and review rules for Swift Testing. Helps write and audit test suites targeting Swift 6.2 concurrency. CX Codex +1 534installs cmux-testing manaflow-ai cmux-testing — a skill for choosing verification scopes, adding tests, and validating Swift test targets in the cmux project. Decides what local and CI evidence a change needs. CX Codex +1 5,100installs write-swift emilkowalski write-swift — a Swift skill for Claude Code guides code writing and review. It activates for Swift changes, migrations, and fixes involving concurrency, hangs, memory, or performance. CX Codex +1 169,400installs swift-concurrency AvdLee swift-concurrency is a Claude Code skill that diagnoses Swift Concurrency issues and suggests safe fixes. It activates for Swift 6 migration and work involving tasks, actors, or Sendable. CX Codex +1 17,700installs

From the same set33

The whole set →
sqlite-data Guides database modeling in Swift with the SQLiteData library, macro queries, migrations, and private CloudKit database sync. CX Codex +1 ★ 233repo stars composable-architecture This skill guides feature work with The Composable Architecture (TCA), from reducer structure and effects to navigation and tests. Use it while building or checking TCA features. CX Codex +1 ★ 233repo stars modern-swift modern-swift — a Claude skill that steers the agent through Swift 6.2 concurrency: async/await, actors, Sendable and task cancellation. CX Codex +1 ★ 233repo stars swiftui-patterns swiftui-patterns guides Claude Code through iOS 17+ SwiftUI conventions: the @Observable macro, NavigationStack, and clean UIKit interop. CX Codex +1 ★ 233repo stars tca-architect tca-architect designs feature architectures for The Composable Architecture: State structure, Action taxonomy, dependencies, navigation. Operates in read-only mode. CX Codex ★ 233repo stars swift-architect swift-architect designs Swift feature architecture, file layout, and persistence plans before implementation begins. CX Codex ★ 233repo stars swift-search The swift-search subagent locates Swift definitions and implementations, then checks the matching files. Use it when you know what to find but not where it lives. CX Codex ★ 233repo stars swift-engineering swift-engineering — a set of subagents and skills for Claude covering planning, Swift and TCA implementation, testing and review of iOS and macOS apps. ★ 233repo stars

Project sponsors

Companies that keep this analytics open