A hands-on checklist for migrating from XCTest to Swift Testing and leveraging the full power of the new API. This guide focuses on what you can do with the framework 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.3+.
• For any projects supporting Linux/Windows, add the swift-testing SPM package. It's not needed for Apple platforms.
• In your primary test plan, flip the switch to “Use parallel execution”.

Replace the entire XCTAssert family with two powerful, expressive macros.

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

// Old XCTest way
let user = try XCTUnwrap(await fetchUser())

// New, safer Swift Testing way
let user = try #require(await fetchUser())

// `user` is now a non-optional User, ready for further assertions.
#expect(user.age == 37)

• Run grep -R "XCTAssert" . on your project to find all legacy assertions.
• Convert XCTUnwrap calls to try #require().
• Convert most XCTAssert calls to #expect(). Use #require() for preconditions that would make the rest of the test invalid.

Swift Testing replaces the setUpWithError and tearDownWithError methods 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.

@Suite struct DatabaseServiceTests {
    let sut: DatabaseService
    let tempDirectory: URL

    init() {
        // ARRANGE: Runs before EACH test in this suite.
        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 {
        // TEARDOWN: Runs after EACH test in this suite.
        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)
    }

    @Test func testDeletingUser() throws {
        // A completely separate, clean instance of the suite runs for this test.
    }
}

• Convert test classes inheriting from XCTestCase to structs or final classes.
• Move logic from setUpWithError into the suite's init().
• Move cleanup logic from tearDownWithError into the suite's deinit.
• Define the SUT and its dependencies as let properties on the suite, initialized inside init().

Go beyond simple do/catch blocks with a dedicated, expressive API for error validation.

Drastically reduce boilerplate by running a single test function with multiple argument sets.

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

A @Suite groups related tests. They can be nested to create a clear structural hierarchy. Traits applied to a suite are inherited by all tests within it.

@Suite("API Services", .tags(.network))
struct APITests {
    @Suite("Authentication")
    struct AuthTests { /* ... */ }
}

Tags associate tests that share common characteristics, regardless of their suite.

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
   }

2. Apply Tags & Filter:

   @Test("Username validation", .tags(.fast, .regression)) // Apply
   // swift test --filter-tag fast // Run from CLI

Simply mark your test function async and use await.

@Test("User profile downloads correctly")
async func testProfileDownload() async throws { /* ... */ }

To test APIs that fire multiple times (like streams or event handlers), use confirmation.

@Test("Data stream sends three packets")
async func testDataStream() async {
    let streamFinished = confirmation("Stream sent 3 packets", expectedCount: 3)
    // ...
}

Apply the .serialized trait to any @Test or @Suite to opt out of concurrent execution for tests that are not thread-safe.

The .timeLimit trait is a safety net to prevent hung tests from stalling your entire CI pipeline, especially those involving async operations.

• How it works: It sets a maximum duration for a single test's execution. If the test exceeds this limit, it immediately fails.
• Behavior: When a suite and a test within it both have a time limit, the more restrictive (shorter) duration wins.
• Units: The duration is highly flexible (e.g., .seconds(5), .milliseconds(500)).

// Suite-level timeout of 10 seconds for all network tests
@Suite("Network Fetcher", .timeLimit(.seconds(10)))
struct NetworkFetcherTests {

    @Test("Fetching a large file has a generous timeout")
    func testLargeFileDownload() async { /* Inherits 10-second limit */ }

    // This specific test must complete in under 1 second, overriding the suite's default.
    @Test("A fast API status check", .timeLimit(.seconds(1)))
    func testFastAPI() async { /* ... */ }
}

• Run All Tests: swift test --enable-swift-testing
• Filter by Tag: swift test --filter-tag regression
• Generate JUnit Report: swift test --enable-swift-testing --format junit > report.xml
• Check Code Coverage: swift test --enable-swift-testing --show-code-coverage
• Xcode Cloud: Natively supports Swift Testing, including test plans and tag-based analytics, with no extra flags needed.

Of course. Here are the requested sections, formatted as distinct blocks with detailed explanations and practical examples, ready to be integrated into the main guide.

Ensuring your code is free of memory leaks and retain cycles is critical. Swift Testing offers modern, pattern-matching ways to validate memory safety, replacing older XCTest techniques.

The #expect macro is more than a simple boolean check. Its specialized overloads allow you to write more expressive and concise tests, eliminating verbose helper code and manual validation logic.

Swift Testing provides powerful traits to conditionally run or skip tests, which is essential for managing tests that depend on feature flags, specific environments, or are temporarily flaky.

Generic boolean checks like #expect(a == b) are good, but purpose-built assertions provide far sharper and more actionable failure messages. They tell you not just that something failed, but why.

These foundational principles pre-date Swift Testing but are 100% applicable. The framework is designed to make adhering to them easier than ever.

• Test the Public API, Not the Implementation Focus on what your code does (its behavior), not how it does it (its internal details). Testing private methods is a sign that a type may have too many responsibilities and should be broken up.

• One "Act" Per Test Each test function should verify a single, specific behavior. While you can have multiple assertions (#expect) to validate the outcome of that one action, avoid a sequence of multiple, unrelated actions in a single test.

• Avoid Logic in Tests If you find yourself writing if, for, or switch statements in a test, it's a "code smell." Your test logic is becoming too complex. Extract helper functions or, better yet, simplify the test's scope.

• Name Tests for Clarity A test's name should describe the behavior it validates. Swift Testing's @Test("...") display name is perfect for this. A good format is: “<Behavior> under <Condition> results in <Expected Outcome>”.

  @Test("Adding an item to an empty cart increases its count to one")
  func testAddItemToEmptyCart() { /* ... */ }

• Use Descriptive Failure Messages The #expect macro can take an optional string message. Use it to provide context when an assertion fails. It will save you debugging time later.

  #expect(cart.itemCount == 1, "Expected item count to be 1 after adding the first item.")

• Eliminate Magic Values Extract repeated literals (strings, numbers) into clearly named constants. This makes tests more readable and easier to maintain.

  Bad: #expect(user.accessLevel == 3) Good:

  let adminAccessLevel = 3
  #expect(user.accessLevel == adminAccessLevel)