Swift Testing

Swift Testing is the modern testing framework for Swift (Xcode 16+, Swift 6+). Prefer it over XCTest for all new unit tests. Use XCTest only for UI tests, performance benchmarks, and snapshot tests.

Contents

• Basic Tests
• @Test Traits
• #expect and #require
• @Suite and Test Organization
• Known Issues
• Additional Patterns
• Parameterized Tests In Depth
• Tags and Suites In Depth
• Async Testing Patterns
• Traits In Depth
• Common Mistakes
• Test Attachments
• Exit Testing
• Review Checklist
• References

Basic Tests

import Testing

@Test("User can update their display name")
func updateDisplayName() {
    var user = User(name: "Alice")
    user.name = "Bob"
    #expect(user.name == "Bob")
}

@Test Traits

@Test("Validates email format")                                    // display name
@Test(.tags(.validation, .email))                                  // tags
@Test(.disabled("Server migration in progress"))                   // disabled
@Test(.enabled(if: ProcessInfo.processInfo.environment["CI"] != nil)) // conditional
@Test(.bug("https://github.com/org/repo/issues/42"))               // bug reference
@Test(.timeLimit(.minutes(1)))                                     // time limit
@Test("Timeout handling", .tags(.networking), .timeLimit(.seconds(30))) // combined

#expect and #require

// #expect records failure but continues execution
#expect(result == 42)
#expect(name.isEmpty == false)
#expect(items.count > 0, "Items should not be empty")

// #expect with error type checking
#expect(throws: ValidationError.self) {
    try validate(email: "not-an-email")
}

// #expect with specific error value
#expect {
    try validate(email: "")
} throws: { error in
    guard let err = error as? ValidationError else { return false }
    return err == .empty
}

// #require records failure AND stops test (like XCTUnwrap)
let user = try #require(await fetchUser(id: 1))
#expect(user.name == "Alice")

// #require for optionals -- unwraps or fails
let first = try #require(items.first)
#expect(first.isValid)

Rule: Use #require when subsequent assertions depend on the value. Use #expect for independent checks.

@Suite and Test Organization

See references/testing-patterns.md for suite organization, confirmation patterns, and known-issue handling.

Known Issues

Mark expected failures so they do not cause test failure:

withKnownIssue("Propane tank is empty") {
    #expect(truck.grill.isHeating)
}

// Intermittent / flaky failures
withKnownIssue(isIntermittent: true) {
    #expect(service.isReachable)
}

// Conditional known issue
withKnownIssue {
    #expect(foodTruck.grill.isHeating)
} when: {
    !hasPropane
}

If no known issues are recorded, Swift Testing records a distinct issue notifying you the problem may be resolved.

Additional Patterns

See references/testing-patterns.md for complete examples of:

• TestScoping -- custom test lifecycle with setup/teardown consolidation
• Mocking and Test Doubles -- protocol-based doubles and testable architecture
• View Model Testing -- environment injection and dependency isolation
• Async Patterns -- clock injection and error path testing
• XCUITest -- page objects, performance testing, snapshot testing, and test file organization

Parameterized Tests In Depth

@Test with Arguments

Pass any Sendable & Collection to arguments:. Each element runs as an independent test case.

// Enum-based: runs one case per enum value
enum Environment: String, CaseIterable, Sendable {
    case development, staging, production
}

@Test("Base URL is valid for all environments", arguments: Environment.allCases)
func baseURLIsValid(env: Environment) throws {
    let url = try #require(URL(string: Config.baseURL(for: env)))
    #expect(url.scheme == "https")
}

Ranges as Arguments

@Test("Fibonacci is positive for small inputs", arguments: 1...20)
func fibonacciPositive(n: Int) {
    #expect(fibonacci(n) > 0)
}

Multiple Parameter Sources

Two argument collections produce a cartesian product (every combination):

@Test(arguments: ["light", "dark"], ["iPhone", "iPad"])
func snapshotTest(colorScheme: String, device: String) {
    // Runs 4 combinations: light+iPhone, light+iPad, dark+iPhone, dark+iPad
    let config = SnapshotConfig(colorScheme: colorScheme, device: device)
    #expect(config