swift-testing

---

name: swift-testing description: "Writes and migrates Swift Testing framework tests with @Test, @Suite, #expect, #require, confirmation, traits, withKnownIssue, Attachment.record, processExitsWith exit tests and capture lists, Test.cancel, Issue.record warnings/manual failures, XCTest-to-Swift Testing migration, Xcode 27 interoperability modes, XCUITest UI-test boundaries, performance/snapshot boundaries, mocking, async patterns, and test organization. Use when writing tests, converting XCTest assertions such as XCTUnwrap or XCTFail, reviewing advanced Swift Testing API availability, or deciding when to keep XCTest/XCUITest."

Swift Testing

Swift Testing is the modern testing framework for Swift (Xcode 16+, Swift 6+). Prefer it for new unit tests. Keep XCTest where migration is still in progress, and use XCTest for UI automation, performance APIs, Objective-C exception tests, and common snapshot-test tooling.

Contents

• Basic Tests
• @Test Traits
• #expect and #require
• @Suite and Test Organization
• Execution Model
• XCTest Migration Boundaries
• Known Issues
• Additional Patterns
• Common Mistakes
• Test Attachments
• Exit Testing
• Version-Gated APIs
• Advanced API Review Checklist
• 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, known-issue handling, and execution-model details.

Execution Model

Swift Testing runs tests in parallel by default. Do not assume test order, shared suite instances, or exclusive access to mutable state unless you explicitly design for it.

@Suite(.serialized)
struct KeychainTests {
    @Test func storesToken() throws { /* ... */ }
    @Test func deletesToken() throws { /* ... */ }
}

Use .serialized when a test or suite must run one-at-a-time because it touches shared external state. It does not make unrelated tests outside that scope run serially.

Rules:

• Each test must set up its own state.
• Shared mutable globals are a bug unless protected or intentionally serialized.
• @Suite(.serialized) is for exclusive execution, not for expressing logical ordering between tests.
• If tests depend on sequence, combine them into one test or move the sequence into shared helper code.

XCTest Migration Boundaries

Swift Testing unit tests do not inherit from XCTestCase. Declare @Test on free functions, global functions, or methods on suite types such as struct, class, or actor; use static or class methods when instance fixtures are not needed.

When reviewing migration code or plans, do not collapse every XCTest construct into #expect. Include a compact assertion-mapping note or table in the answer so required unwraps and unconditional manual failures are not lost, even when the user only says "replace every XCTAssert with #expect."

State coexistence explicitly: XCTest and Swift Testing can coexist during migration. Keep UI automation, performance benchmarks, and common snapshot-test flows on XCTest/XCUITest or snapshot tooling, and separate files or targets when that makes runner expectations clearer.

For Xcode 27-era migrations, mention test framework interoperability when reviewing mixed helpers. Frame what changed: test plans created before Xcode 27 inherit limited mode, where cross-framework XCTest issues are warnings; new Xcode 27 projects use complete mode, where those issues remain errors. Xcode and SwiftPM can surface XCTest failures from Swift Testing tests and Swift Testing issues from XCTest tests depending on the configured interop mode (limited, complete, strict, or none). Prefer complete or strict while migrating helpers, use SWIFT_TESTING_XCTEST_INTEROP_MODE for SwiftPM when needed, and do not claim cross-framework APIs are categorically forbidden. Still prefer native Swift Testing APIs in new Swift Testing tests and convert helper failures to Issue.record, #expect, #require, or Test.cancel over time.

Migration defaults:

• XCTAssert* -> #expect(...)
• XCTUnwrap or any value required by later checks -> try #require(...)
• XCTFail("...") or manual unconditional issues -> Issue.record("...")
• UI tests, performance benchmarks, and common snapshot-test flows stay on XCTest/XCUITest or snapshot tooling.
• Put @available on individual @Test functions, not on suite types or their containing types.

let user = try #require(optionalUser)
#expect(user.isActive)

guard featureFlag.isEnabled else {
    Issue.record("Expected feature flag to be enabled")
    return
}

See references/testing-patterns.md for migration examples and references/testing-advanced.md for Swift/Xcode version gates.

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 parameterized tests, tags and suites, async testing, traits, and execution-model details.

Test Attachments

Attach diagnostic data to test results for debugging failures. See references/testing-patterns.md for full examples.

@Test func generateReport() async throws {
    let report = try generateReport()
    Attachment.record(report.data, named: "report.json")
    #expect(report.isValid)
}

Image attachments require Swift 6.3 / Xcode 26.4 or newer. Import Testing plus the relevant UI framework, then record the platform image value directly:

import Testing
import UIKit

@Test func renderedChart() async throws {
    let image = renderer.image { ctx in chartView.drawHierarchy(in: bounds, afterScreenUpdates: true) }
    Attachment.record(image, named: "chart", as: .png)
}

Exit Testing

Test code that calls exit(), fatalError(), or preconditionFailure(). Exit testing requires Swift 6.2 / Xcode 26.0 or newer and is supported on macOS, Linux, FreeBSD, OpenBSD, and Windows runtime targets, not iOS, tvOS, or watchOS. When correcting exit-test code, name both the toolchain floor and runtime support. See references/testing-patterns.md for details.

@Test func invalidInputCausesExit() async {
    await #expect(processExitsWith: .failure) {
        processInvalidInput()  // calls fatalError()
    }
}

Version-Gated APIs

For advanced Swift Testing APIs, check the toolchain before recommending them. When reviewing user code that mentions one of these APIs, name the gate for each API you correct:

• Exit testing requires Swift 6.2 / Xcode 26.0 and does not support iOS, tvOS, or watchOS runtime targets.
• Exit-test capture lists require the Swift 6.3 compiler. If an exit-test closure reads parent-process values, use an explicit capture list and state that captured values must be Sendable and Codable.
• Test.cancel(_:), Issue.record(_:severity:), and image attachment recording require Swift 6.3 / Xcode 26.4-era support as noted in references/testing-advanced.md.
• When fixing a Test.cancel(_:) sample, state both shape and gate: the test must be throws or async throws, and Test.cancel(_:) requires Swift 6.3 / Xcode 26.4-era support.

@Test func exitsWithCapturedCode() async {
    let expectedCode: Int32 = 42
    await #expect(processExitsWith: .failure) { [expectedCode] in
        exit(expectedCode)
    }
}

Advanced API Review Checklist

When reviewing stale or beta-era Swift Testing samples, include the exact correction and the gate for every API the prompt mentions:

User code to correct	Current guidance
#expect(exitsWith:)	Use await #expect(processExitsWith: .failure) { ... }. Exit testing requires Swift 6.2 / Xcode 26.0 or newer and is supported on macOS, Linux, FreeBSD, OpenBSD, and Windows runtime targets, not iOS, tvOS, or watchOS. For an iOS app target, test fatal-path logic through a smaller non-exiting API or a supported host/tool target.
Exit-test closure reads outer values	Add an explicit capture list, for example { [expectedCode] in ... }. Exit-test capture lists require the Swift 6.3 compiler; captured values must be Sendable and Codable.
Test.cancel() in a test that awaits work	Make the test async throws and call try Test.cancel("reason"). Test.cancel(_:) requires Swift 6.3 / Xcode 26.4-era support.
Issue.record(..., severity: .warning)	Use Issue.record("message", severity: .warning). Warning severity is reported but does not fail the test, and requires Swift 6.3 / Xcode 26.4-era support.
Attachment(image, named:).record()	Use Attachment.record(image, named: "name", as: .png). Import Testing plus the relevant image framework; Apple-platform image values include UIImage, CGImage, CIImage, and NSImage. Image attachment recording requires Swift 6.3 / Xcode 26.4-era support.

Common Mistakes

1. Testing implementation, not behavior. Test what the code does, not how.
2. No error path tests. If a function can throw, test the throw path.
3. Flaky async tests. Use confirmation with expected counts, not sleep calls.
4. Shared mutable state between tests. Each test sets up its own state via init() in @Suite.
5. Missing accessibility identifiers in UI tests. XCUITest queries rely on them.
6. Using sleep in tests. Use confirmation, clock injection, or withKnownIssue.
7. Not testing cancellation. If code supports Task cancellation, verify it cancels cleanly.
8. Unclear XCTest migration boundaries. Apple allows XCTest and Swift Testing in one file during migration; prefer separate files when it keeps imports, ownership, and runner expectations clearer.
9. Non-Sendable test helpers shared across tests. Ensure test helper types are Sendable when shared across concurrent test cases. Annotate MainActor-dependent test code with @MainActor.
10. Assuming tests run in declaration order. Swift Testing runs in parallel by default; use .serialized only when exclusive execution is required.
11. Using .serialized to express workflow steps. Serialized execution does not make one test feed another; keep dependent steps in one test.

Review Checklist

• All new tests use Swift Testing (@Test, #expect), not XCTest assertions
• Test names describe behavior (fetchUserReturnsNilOnNetworkError not testFetchUser)
• Error paths have dedicated tests
• Async tests use confirmation(), not Task.sleep
• Parameterized tests used for repetitive variations
• Tags applied for filtering (.critical, .slow)
• Mocks conform to protocols, not subclass concrete types
• No shared mutable state between tests
• Tests do not rely on declaration order or shared suite instances
• .serialized used only for truly exclusive state, not to model workflow sequencing
• Cancellation tested for cancellable async operations

References

• Testing patterns: references/testing-patterns.md
• Advanced testing (warnings, cancellation, image attachments): references/testing-advanced.md