A hands-on, comprehensive guide for migrating from XCTest to Swift Testing and mastering the new framework. This playbook integrates the latest patterns and best practices from WWDC 2024 and official Apple documentation to make your tests more powerful, expressive, and maintainable.

Ensure your environment is set up for a smooth, gradual migration.

• Ensure all developer machines and CI runners are on macOS 15+ and Xcode 16+.
• For projects supporting Linux/Windows, add the swift-testing SPM package. It's not needed for Apple platforms.
• In your primary test plan, confirm that “Use parallel execution” is enabled.

Replace the entire XCTAssert family with two powerful, expressive macros. They accept regular Swift expressions, eliminating the need for dozens of specialized XCTAssert functions.

#require is the new, safer replacement for XCTUnwrap. It not only checks for nil but also unwraps the value for subsequent use.

// XCTest
let user = try XCTUnwrap(await fetchUser())
XCTAssertEqual(user.age, 37)

// Swift Testing
let user = try #require(await fetchUser())
#expect(user.age == 37)

• Run grep -R "XCTAssert" . to find all legacy assertions.
• Convert XCTUnwrap calls to try #require().
• Convert most XCTAssert calls to #expect(). Use #require() only for preconditions.
• Group related checks with #expectAll { ... } to ensure all are evaluated and reported together.

Swift Testing replaces setUpWithError and tearDownWithError with a more natural, type-safe lifecycle using init() and deinit.

The Core Concept: A fresh, new instance of the test suite (struct or class) is created for each test function it contains. This is the cornerstone of test isolation, guaranteeing that state from one test cannot leak into another.

// XCTest
final class DatabaseServiceXCTests: XCTestCase {
    var sut: DatabaseService!
    var tempDirectory: URL!

    override func setUpWithError() throws {
        try super.setUpWithError()
        self.tempDirectory = FileManager.default.temporaryDirectory.appendingPathComponent(UUID().uuidString)
        try FileManager.default.createDirectory(at: tempDirectory, withIntermediateDirectories: true)
        let testDatabase = TestDatabase(storageURL: tempDirectory)
        self.sut = DatabaseService(database: testDatabase)
    }

    override func tearDownWithError() throws {
        try FileManager.default.removeItem(at: tempDirectory)
        self.sut = nil
        self.tempDirectory = nil
        try super.tearDownWithError()
    }
    
    func testSavingUser() throws {
        let user = User(id: "user-1", name: "Alex")
        try sut.save(user)
        let loadedUser = try sut.loadUser(id: "user-1")
        XCTAssertNotNil(loadedUser)
    }
}

// Swift Testing (using a class to get deinit behavior)
@Suite final class DatabaseServiceTests {
    let sut: DatabaseService
    let tempDirectory: URL

    init() throws {
        self.tempDirectory = FileManager.default.temporaryDirectory.appendingPathComponent(UUID().uuidString)
        try FileManager.default.createDirectory(at: tempDirectory, withIntermediateDirectories: true)
        
        let testDatabase = TestDatabase(storageURL: tempDirectory)
        self.sut = DatabaseService(database: testDatabase)
    }

    deinit {
        try? FileManager.default.removeItem(at: tempDirectory)
    }

    @Test func testSavingUser() throws {
        let user = User(id: "user-1", name: "Alex")
        try sut.save(user)
        #expect(try sut.loadUser(id: "user-1") != nil)
    }
}

• Convert test classes from XCTestCase to structs (preferred) or final classes if deinit is needed.
• Move setUpWithError logic into the suite's init().
• Move tearDownWithError logic into the suite's deinit.
• Define the SUT and its dependencies as non-optional let properties, initialized in init().

Go beyond do/catch with a dedicated, expressive API for validating thrown errors.

// XCTest
func testBrewingThrows() {
    XCTAssertThrowsError(try coffeeMaker.brew(), "Expected brewing to fail") { error in
        XCTAssertEqual(error as? BrewingError, .outOfBeans)
    }
}

// Swift Testing
@Test func brewingThrowsExpectedError() {
    #expect(throws: BrewingError.outOfBeans) {
        try coffeeMaker.brew()
    }
}

Run a single test function with multiple argument sets to maximize coverage with minimal code. This is a direct replacement for repetitive test functions and is superior to a for-in loop because each argument set runs as an independent, parallelizable test.

// XCTest
final class MathXCTests: XCTestCase {
    func testIsEven() {
        XCTAssertTrue(isEven(2))
    }
    func testIsOdd() {
        XCTAssertFalse(isEven(3))
    }
    func testIsZeroEven() {
        XCTAssertTrue(isEven(0))
    }
}

// Swift Testing
@Suite struct MathTests {
    @Test("Number evenness check", arguments: [
        (2, true),
        (3, false),
        (0, true),
        (-4, true)
    ])
    func isEven(number: Int, expected: Bool) {
        #expect(isEven(number) == expected)
    }
}

Dynamically control which tests run based on feature flags, environment, or known issues. This replaces XCTest's XCTSkipUnless and manual commenting-out of tests.

// XCTest
func testNewFeature() throws {
    try XCTSkipUnless(FeatureFlags.isNewAPIEnabled, "New API feature flag is not enabled.")
    // ... test code
}

// Swift Testing
@Test("New feature test", .enabled(if: FeatureFlags.isNewAPIEnabled, "New API feature flag not enabled"))
func testNewFeature() {
    // ... test code
}

While #expect(a == b) works, purpose-built assertions provide sharper, more actionable failure messages by explaining why something failed, not just that it failed.

Use suites and tags to manage large and complex test bases.

A @Suite groups related tests and can be nested for a clear hierarchy. Traits applied to a suite are inherited by all tests and nested suites within it.

Tags associate tests with common characteristics (e.g., .network, .ui, .regression) regardless of their suite. This is invaluable for filtering.

1. Define Tags in a Central File:

   // /Tests/Support/TestTags.swift
   import Testing
   
   extension Tag {
       @Tag static var fast: Self
       @Tag static var regression: Self
       @Tag static var flaky: Self
   }

2. Apply Tags & Filter:

   // Apply to a test or suite
   @Test("Username validation", .tags(.fast, .regression))
   func testUsername() { /* ... */ }
   
   // Run from CLI
   // swift test --filter-tag fast
   
   // Filter in Xcode Test Plan
   // Add "fast" to the "Include" field or "flaky" to the "Exclude" field.

Swift Testing's native async/await support simplifies asynchronous code significantly compared to XCTestExpectation.

• Async Tests: Simply mark your test function async and use await.
• confirmation: Replaces XCTestExpectation for testing callbacks, notifications, or delegate methods.
• fulfillment(of:timeout:): Replaces wait(for:timeout:). This is the global function you await to pause the test until your confirmations are fulfilled or a timeout is reached.

// XCTest
func testDataDownload() {
    let expectation = self.expectation(description: "Download should complete")
    
    let downloader = Downloader()
    downloader.onComplete = { data in
        XCTAssertFalse(data.isEmpty)
        expectation.fulfill()
    }
    
    downloader.start()
    
    waitForExpectations(timeout: 5.0)
}


// Swift Testing
@Test("Data downloads successfully")
async func testDataDownload() async throws {
    let downloadCompleted = confirmation("Download should complete")

    let downloader = Downloader()
    downloader.onComplete = { data in
        #expect(!data.isEmpty)
        await downloadCompleted()
    }
    
    downloader.start()
    
    try await fulfillment(of: [downloadCompleted], timeout: .seconds(5))
}

• .serialized: Apply this trait to a @Test or @Suite to force its contents to run serially. Use this as a temporary measure for legacy tests that are not thread-safe or have hidden state dependencies.
• .timeLimit: A safety net to prevent hung tests from stalling CI.

Swift Testing and XCTest can coexist in the same target, enabling an incremental migration.

Continue using XCTest for the following, as they are not currently supported by Swift Testing:

• UI Automation Tests (using XCUIApplication)
• Performance Tests (using XCTMetric and measure { ... })
• Tests written in Objective-C

These foundational principles are framework-agnostic, and Swift Testing is designed to make adhering to them easier than ever.