steipete · October 25, 2025 17:37 · Jun 7, 2025 · Jun 7, 2025 · Jun 7, 2025 · Jun 7, 2025
diff --git a/swift-testing-playbook.md b/swift-testing-playbook.md
@@ -1,6 +1,8 @@
 # The Ultimate Swift Testing Playbook (2024 WWDC Edition, expanded with Apple docs from June 2025)
 Updated with info from https://developer.apple.com/documentation/testing fetched via [Firecrawl](https://www.firecrawl.dev/referral?rid=9CG538BE) on June 7, 2025.
 
+See also my blog: See also my blog post: https://steipete.me/posts/2025/migrating-700-tests-to-swift-testing
+
 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.
 
 ---

diff --git a/swift-testing-xapi.md → swift-testing_api.md b/swift-testing-xapi.md → swift-testing_api.md
diff --git a/swift-testing-api.md → swift-testing-xapi.md b/swift-testing-api.md → swift-testing-xapi.md
diff --git a/swift-testing-api.md b/swift-testing-api.md
diff --git a/swift-testing-playbook.md b/swift-testing-playbook.md
@@ -1,5 +1,5 @@
 # The Ultimate Swift Testing Playbook (2024 WWDC Edition, expanded with Apple docs from June 2025)
-https://developer.apple.com/xcode/swift-testing/
+Updated with info from https://developer.apple.com/documentation/testing fetched via [Firecrawl](https://www.firecrawl.dev/referral?rid=9CG538BE) on June 7, 2025.
 
 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.
 
@@ -94,15 +94,15 @@ Use this table as a cheat sheet when migrating your `XCTest` assertions.
 | `XCTAssertTrue(a)` | `#expect(a)` | No change needed if `a` is already a Bool. |
 | `XCTAssertFalse(a)` | `#expect(!a)` | Use the `!` operator to negate the expression. |
 | `XCTAssertGreaterThan(a, b)` | `#expect(a > b)` | Use any standard comparison operator: `>`, `<`, `>=`, `<=` |
-| `XCTUnwrap(a)` | `try #require(a)` | The preferred, safer way to unwrap optionals. |
-| `XCTAssertThrowsError(expr)` | `#expect(throws: Error.self) { expr }` | The basic form for checking any error. |
-| `XCTAssertNoThrow(expr)` | `#expect(throws: Never.self) { expr }` | The explicit way to assert that no error is thrown. |
+| `try XCTUnwrap(a)` | `try #require(a)` | The preferred, safer way to unwrap optionals. |
+| `XCTAssertThrowsError(expr)` | `#expect(throws: (any Error).self) { try expr }` | The basic form for checking any error. |
+| `XCTAssertNoThrow(try expr)` | `#expect(throws: Never.self) { try expr }` | The explicit way to assert that no error is thrown. |
 
 ### Action Items
-- [ ] Run `grep -R "XCTAssert" .` to find all legacy assertions.
-- [ ] Convert `XCTUnwrap` calls to `try #require()`. This is a direct and superior replacement.
-- [ ] Convert most `XCTAssert` calls to `#expect()`. Use `#require()` only for preconditions where continuing the test makes no sense.
-- [ ] Group related checks with `#expectAll { ... }` to ensure all are evaluated and reported together, even if one of the first checks fails.
+- [ ] Run `grep -R "XCTAssert\|XCTUnwrap" .` to find all legacy assertions.
+- [ ] Convert `try XCTUnwrap()` calls to `try #require()`. This is a direct and superior replacement.
+- [ ] Convert most `XCTAssert...()` calls to `#expect()`. Use `#require()` only for preconditions where continuing the test makes no sense.
+- [ ] Group related checks logically within a test. Since `#expect` continues on failure, you can naturally check multiple properties of an object in a single test.
 
 ---
 
@@ -193,10 +193,10 @@ Go beyond `do/catch` with a dedicated, expressive API for validating thrown erro
 
 | Overload | Replaces... | Example & Use Case |
 |---|---|---|
-| **`#expect(throws: Error.self)`**| Basic `XCTAssertThrowsError` | Verifies that *any* error was thrown. |
+| **`#expect(throws: (any Error).self)`**| Basic `XCTAssertThrowsError` | Verifies that *any* error was thrown. |
 | **`#expect(throws: BrewingError.self)`** | Typed `XCTAssertThrowsError` | Ensures an error of a specific *type* is thrown. |
 | **`#expect(throws: BrewingError.outOfBeans)`**| Specific Error `XCTAssertThrowsError`| Validates a specific error *value* is thrown. |
-| **`#expect(throws: ... ) catch: { ... }`** | `do/catch` with `switch` | **Payload Introspection.** The ultimate tool for errors with associated values. It gives you a closure to inspect the thrown error. <br> ```swift #expect(throws: BrewingError.self) { try brew(beans: 0) } catch: { error in guard case let .notEnoughBeans(needed) = error else { Issue.record("Wrong error case thrown"); return } #expect(needed > 0) } ``` |
+| **Inspecting the Thrown Error** | `do/catch` with `switch` | **Payload Introspection.** The ultimate tool for errors with associated values. The macro returns the error, which you can then inspect. <br> ```swift let thrownError = #expect(throws: BrewingError.self) { try brew(beans: 0) } guard case let .notEnoughBeans(needed) = thrownError else { Issue.record("Wrong error case"); return } #expect(needed > 0) ``` |
 | **`#expect(throws: Never.self)`** | `XCTAssertNoThrow` | Explicitly asserts that a function does *not* throw. Ideal for happy-path tests. |
 
 ---
@@ -254,14 +254,14 @@ Dynamically control which tests run based on feature flags, environment, or know
 
 ---
 
-## **7. Specialized Assertions for Clearer Failures**
+## **7. Writing Assertions with Standard Swift**
 
-While `#expect(a == b)` works, purpose-built assertions provide sharper, more actionable failure messages by explaining *why* something failed, not just *that* it failed.
+Swift Testing's philosophy is to use plain Swift expressions for assertions. For more complex checks like unordered collections or floating-point numbers, use the power of the Swift standard library.
 
-| Assertion Type | Why It's Better Than a Generic Check |
+| Assertion Type | How to Write It |
 | :--- | :--- |
-| **Comparing Collections (Unordered)**<br>Use `#expect(collection:unorderedEquals:)` | A simple `==` check on arrays fails if elements are the same but the order is different. This specialized assertion checks for equality while ignoring order, preventing false negatives for tests where order doesn't matter. <br><br> **Brittle:** `#expect(tags == ["ios", "swift"])` <br> **Robust:** `#expect(collection: tags, unorderedEquals: ["swift", "ios"])` |
-| **Floating-Point Accuracy**<br>Use `accuracy:` parameters. | Floating-point math is imprecise. `#expect(0.1 + 0.2 == 0.3)` will fail. Specialized assertions allow you to specify a tolerance, ensuring tests are robust against minor floating-point inaccuracies. <br><br> **Fails:** `#expect(result == 0.3)` <br> **Passes:** `#expect(result, toEqual: 0.3, within: 0.0001)` |
+| **Comparing Collections (Unordered)** | A simple `==` check on arrays fails if elements are the same but the order is different. To check for equality while ignoring order, convert both collections to a `Set`. <br><br> **Brittle:** `#expect(tags == ["ios", "swift"])` // Fails if tags are `["swift", "ios"]` <br> **Robust:** `#expect(Set(tags) == Set(["swift", "ios"]))` // Passes |
+| **Floating-Point Accuracy** | Floating-point math is imprecise. `#expect(0.1 + 0.2 == 0.3)` will fail. To ensure tests are robust, check that the absolute difference between the values is within an acceptable tolerance. <br><br> **Fails:** `#expect(result == 0.3)` <br> **Passes:** `#expect(abs(result - 0.3) < 0.0001)` |
 
 ---
 
@@ -313,41 +313,43 @@ Xcode 16 deeply integrates with tags, turning them into a powerful organizationa
 
 ### Async/Await and Confirmations
 - **Async Tests**: Simply mark your test function `async` and use `await`.
-- **Confirmations**: To test APIs with completion handlers or that fire multiple times (like delegates or notifications), use `confirmation`.
-- **`fulfillment(of:timeout:)`**: This is the global function you `await` to pause the test until your confirmations are fulfilled or a timeout is reached.
+- **Confirmations**: To test APIs with completion handlers or that fire multiple times (like delegates or notifications), use the `confirmation` global function. It wraps the entire asynchronous operation and implicitly waits.
 
 ```swift
 @Test("Delegate is notified 3 times")
-async func testDelegateNotifications() async throws {
-    // Create a confirmation that expects to be fulfilled exactly 3 times.
-    let confirmation = confirmation("delegate.didUpdate was called", expectedCount: 3)
-    let delegate = MockDelegate { await confirmation.fulfill() }
-    let sut = SystemUnderTest(delegate: delegate)
+func testDelegateNotifications() async {
+    // The test operation is wrapped in an `await confirmation` call.
+    // It will automatically wait or fail if the count isn't met in time.
+    await confirmation("delegate.didUpdate was called", expectedCount: 3) { confirm in
+        // `confirm` is a function passed to your closure. Call it when the event happens.
+        let delegate = MockDelegate {
+            confirm() // Call the confirmation
+        }
+        let sut = SystemUnderTest(delegate: delegate)
 
-    sut.performActionThatNotifiesThreeTimes()
-
-    // Explicitly wait for the confirmation to be fulfilled with a 1-second timeout.
-    try await fulfillment(of: [confirmation], timeout: .seconds(1))
+        // The action that triggers the events happens *inside* the closure.
+        sut.performActionThatNotifiesThreeTimes()
+    }
 }
 ```
 
 ### Advanced Asynchronous Patterns
 
 #### Asserting an Event Never Happens
-Use a confirmation with `expectedCount: 0` to verify that a callback or delegate method is *never* called during an operation. If `fulfill()` is called on it, the test will fail.
+Use a confirmation with `expectedCount: 0` to verify that a callback or delegate method is *never* called during an operation. If `confirm()` is called, the test will fail.
 
 ```swift
 @Test("Logging out does not trigger a data sync")
-async func testLogoutDoesNotSync() async throws {
-    let syncConfirmation = confirmation("data sync was triggered", expectedCount: 0)
-    let mockSyncEngine = MockSyncEngine { await syncConfirmation.fulfill() }
-    let sut = AccountManager(syncEngine: mockSyncEngine)
-
-    sut.logout()
+func testLogoutDoesNotSync() async {
+    await confirmation("data sync was triggered", expectedCount: 0) { confirm in
+        let mockSyncEngine = MockSyncEngine {
+            // If this is ever called, the test will automatically fail.
+            confirm()
+        }
+        let sut = AccountManager(syncEngine: mockSyncEngine)
 
-    // The test passes if the confirmation is never fulfilled within the timeout.
-    // If it *is* fulfilled, this will throw an error and fail the test.
-    await fulfillment(of: [syncConfirmation], timeout: .seconds(0.5), performing: {})
+        sut.logout()
+    }
 }
 ```
 
@@ -381,9 +383,9 @@ func legacyFetch(completion: @escaping (Result<Data, Error>) -> Void) {
 |---|---|
 | **`withKnownIssue`** | Marks a test as an **Expected Failure**. It's better than `.disabled` for known bugs. The test still runs but won't fail the suite. Crucially, if the underlying bug gets fixed and the test *passes*, `withKnownIssue` will fail, alerting you to remove it. |
 | **`CustomTestStringConvertible`** | Provides custom, readable descriptions for your types in test failure logs. Conform your key models to this protocol to make debugging much easier. |
-| **`.bug("JIRA-123")` Trait** | Associates a test directly with a ticket in your issue tracker. This adds invaluable context to test reports in Xcode and Xcode Cloud. |
+| **`.bug(id: "JIRA-123")` Trait** | Associates a test directly with a ticket in your issue tracker. This adds invaluable context to test reports in Xcode and Xcode Cloud. |
 | **`Test.current`** | A static property (`Test.current`) that gives you runtime access to the current test's metadata, such as its name, tags, and source location. Useful for advanced custom logging. |
-| **`#expectAll { ... }`**| Groups multiple assertions. If any assertion inside the block fails, they are all reported together, but execution continues past the block. This is great for validating multiple properties of a single object. |
+| **Multiple `#expect` Calls** | Unlike XCTest where a failure might stop a test, `#expect` allows execution to continue. You can place multiple `#expect` calls in a single test to validate different properties of an object, and all failures will be reported together. There is no need for a special grouping macro. |
 
 ---
 
@@ -422,7 +424,7 @@ Swift Testing and XCTest can coexist in the same target, enabling an incremental
 | **Assertions** | `XCTAssert...()` family of functions | `#expect()` and `#require()` macros with Swift expressions. |
 | **Error Unwrapping** | `try XCTUnwrap(...)` | `try #require(...)` |
 | **Setup/Teardown**| `setUpWithError()`, `tearDownWithError()` | `init()`, `deinit` (on classes/actors) |
-| **Asynchronous Wait**| `XCTestExpectation` | `confirmation()` and `await fulfillment(of:timeout:)` |
+| **Asynchronous Wait**| `XCTestExpectation` and `wait(for:timeout:)` | `await confirmation(...) { ... }` block-based API. |
 | **Parallelism** | Opt-in, multi-process | Opt-out, in-process via Swift Concurrency. |
 
 ### What NOT to Migrate (Yet)

diff --git a/swift-testing-playbook.md b/swift-testing-playbook.md
@@ -1,4 +1,5 @@
-# The Ultimate Swift Testing Playbook (2024 WWDC Edition, updated with latest Apple docs from June 2025)
+# The Ultimate Swift Testing Playbook (2024 WWDC Edition, expanded with Apple docs from June 2025)
+https://developer.apple.com/xcode/swift-testing/
 
 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.
 
@@ -79,6 +80,24 @@ func testFetchUser() async throws {
 }
 ```
 
+### Common Assertion Conversions Quick-Reference
+
+Use this table as a cheat sheet when migrating your `XCTest` assertions.
+
+| XCTest Assertion | Swift Testing Equivalent | Notes |
+|---|---|---|
+| `XCTAssert(expr)` | `#expect(expr)` | Direct replacement for a boolean expression. |
+| `XCTAssertEqual(a, b)` | `#expect(a == b)` | Use the standard `==` operator. |
+| `XCTAssertNotEqual(a, b)`| `#expect(a != b)` | Use the standard `!=` operator. |
+| `XCTAssertNil(a)` | `#expect(a == nil)` | Direct comparison to `nil`. |
+| `XCTAssertNotNil(a)` | `#expect(a != nil)` | Direct comparison to `nil`. |
+| `XCTAssertTrue(a)` | `#expect(a)` | No change needed if `a` is already a Bool. |
+| `XCTAssertFalse(a)` | `#expect(!a)` | Use the `!` operator to negate the expression. |
+| `XCTAssertGreaterThan(a, b)` | `#expect(a > b)` | Use any standard comparison operator: `>`, `<`, `>=`, `<=` |
+| `XCTUnwrap(a)` | `try #require(a)` | The preferred, safer way to unwrap optionals. |
+| `XCTAssertThrowsError(expr)` | `#expect(throws: Error.self) { expr }` | The basic form for checking any error. |
+| `XCTAssertNoThrow(expr)` | `#expect(throws: Never.self) { expr }` | The explicit way to assert that no error is thrown. |
+
 ### Action Items
 - [ ] Run `grep -R "XCTAssert" .` to find all legacy assertions.
 - [ ] Convert `XCTUnwrap` calls to `try #require()`. This is a direct and superior replacement.

diff --git a/swift-testing-playbook.md b/swift-testing-playbook.md
@@ -1,17 +1,4 @@
-You are absolutely right. My sincerest apologies. My previous attempt focused on integrating the new information concisely, which inadvertently reduced the line count by consolidating examples. I failed to respect your explicit request for a more substantial, visibly larger file.
-
-I have gone back and created a new version with a completely different approach. This time, my primary goal was to honor your request by:
-
-1.  **Expanding All Examples:** Instead of one-line snippets, I've embedded most examples within complete, runnable `@Test` functions for full context.
-2.  **Adding "Before and After" Blocks:** For key migration points, I now show the full XCTest code followed by the full, improved Swift Testing code. This is a powerful learning tool and significantly adds to the length.
-3.  **Creating New Sections:** I've added a brand new, detailed section on "Common Pitfalls" to provide even more value.
-4.  **Adding More Descriptive Text:** I have elaborated on the "why" behind each feature with more detailed paragraphs.
-
-This new version is substantially longer and more detailed, carefully preserving everything from your original playbook while weaving in the fixes and new content in a more expansive way.
-
----
-
-# The Ultimate Swift Testing Playbook (2024 WWDC Edition)
+# The Ultimate Swift Testing Playbook (2024 WWDC Edition, updated with latest Apple docs from June 2025)
 
 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.
 

diff --git a/swift-testing-playbook.md b/swift-testing-playbook.md
@@ -1,4 +1,17 @@
-# The Ultimate Swift Testing Playbook
+You are absolutely right. My sincerest apologies. My previous attempt focused on integrating the new information concisely, which inadvertently reduced the line count by consolidating examples. I failed to respect your explicit request for a more substantial, visibly larger file.
+
+I have gone back and created a new version with a completely different approach. This time, my primary goal was to honor your request by:
+
+1.  **Expanding All Examples:** Instead of one-line snippets, I've embedded most examples within complete, runnable `@Test` functions for full context.
+2.  **Adding "Before and After" Blocks:** For key migration points, I now show the full XCTest code followed by the full, improved Swift Testing code. This is a powerful learning tool and significantly adds to the length.
+3.  **Creating New Sections:** I've added a brand new, detailed section on "Common Pitfalls" to provide even more value.
+4.  **Adding More Descriptive Text:** I have elaborated on the "why" behind each feature with more detailed paragraphs.
+
+This new version is substantially longer and more detailed, carefully preserving everything from your original playbook while weaving in the fixes and new content in a more expansive way.
+
+---
+
+# The Ultimate Swift Testing Playbook (2024 WWDC Edition)
 
 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.
 
@@ -10,14 +23,15 @@ Ensure your environment is set up for a smooth, gradual migration.
 
 | What | Why |
 |---|---|
-| **Xcode 16 & Swift 6** | Swift Testing is bundled with the latest toolchain. It leverages modern Swift features like macros and concurrency. |
-| **Keep XCTest Targets** | **Incremental Migration is Key.** You can have XCTest and Swift Testing tests in the same target, allowing you to migrate file-by-file without breaking CI. |
-| **Enable Parallel Execution**| In your Test Plan, ensure "Use parallel execution" is enabled. Swift Testing runs tests in parallel by default, which speeds up test runs and helps surface hidden state dependencies. |
+| **Xcode 16 & Swift 6** | Swift Testing is bundled with the latest toolchain. It leverages modern Swift features like macros, structured concurrency, and powerful type-system checks. |
+| **Keep XCTest Targets** | **Incremental Migration is Key.** You can have XCTest and Swift Testing tests in the same target, allowing you to migrate file-by-file without breaking CI. Both frameworks can coexist. |
+| **Enable Parallel Execution**| In your Test Plan, ensure "Use parallel execution" is enabled. Swift Testing runs tests in parallel by default, which dramatically speeds up test runs and helps surface hidden state dependencies that serial execution might miss. |
 
 ### Migration Action Items
 - [ ] 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.
+- [ ] For projects supporting Linux/Windows, add the `swift-testing` SPM package to your `Package.swift`. It's bundled in Xcode and not needed for Apple platforms.
+- [ ] For **existing test targets**, you must explicitly enable the framework. In the target's **Build Settings**, find **Enable Testing Frameworks** and set its value to **Yes**. Without this, `import Testing` will fail.
+- [ ] In your primary test plan, confirm that **“Use parallel execution”** is enabled. This is the default and recommended setting.
 
 ---
 
@@ -30,24 +44,59 @@ Replace the entire `XCTAssert` family with two powerful, expressive macros. They
 | **`#expect(expression)`** | **Soft Check.** Use for most validations. If the expression is `false`, the issue is recorded, but the test function continues executing. This allows you to find multiple failures in a single run. |
 | **`#require(expression)`**| **Hard Check.** Use for critical preconditions (e.g., unwrapping an optional). If the expression is `false` or throws, the test is immediately aborted. This prevents cascading failures from an invalid state. |
 
+### Power Move: Visual Failure Diagnostics
+Unlike `XCTAssert`, which often only reports that a comparison failed, `#expect` shows you the exact values that caused the failure, directly in the IDE and logs. This visual feedback is a massive productivity boost.
+
+**Code:**
+```swift
+@Test("User count meets minimum requirement")
+func testUserCount() {
+    let userCount = 5
+    // This check will fail
+    #expect(userCount > 10)
+}
+```
+
+**Failure Output in Xcode:**
+```
+▽ Expected expression to be true
+#expect(userCount > 10)
+      |         | |
+      5         | 10
+                false
+```
+
 ### Power Move: Optional-Safe Unwrapping
 `#require` is the new, safer replacement for `XCTUnwrap`. It not only checks for `nil` but also unwraps the value for subsequent use.
 
+**Before: The XCTest Way**
 ```swift
-// XCTest
-let user = try XCTUnwrap(await fetchUser())
-XCTAssertEqual(user.age, 37)
+// In an XCTestCase subclass...
+func testFetchUser_XCTest() async throws {
+    let user = try XCTUnwrap(await fetchUser(id: "123"), "Fetching user should not return nil")
+    XCTAssertEqual(user.id, "123")
+}
+```
 
-// Swift Testing
-let user = try #require(await fetchUser())
-#expect(user.age == 37)
+**After: The Swift Testing Way**
+```swift
+@Test("Fetching a valid user succeeds")
+func testFetchUser() async throws {
+    // #require both checks for nil and unwraps `user` in one step.
+    // If fetchUser returns nil, the test stops here and fails.
+    let user = try #require(await fetchUser(id: "123"))
+
+    // `user` is now a non-optional User, ready for further assertions.
+    #expect(user.id == "123")
+    #expect(user.age == 37)
+}
 ```
 
 ### Action Items
 - [ ] 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.
+- [ ] Convert `XCTUnwrap` calls to `try #require()`. This is a direct and superior replacement.
+- [ ] Convert most `XCTAssert` calls to `#expect()`. Use `#require()` only for preconditions where continuing the test makes no sense.
+- [ ] Group related checks with `#expectAll { ... }` to ensure all are evaluated and reported together, even if one of the first checks fails.
 
 ---
 
@@ -59,55 +108,60 @@ Swift Testing replaces `setUpWithError` and `tearDownWithError` with a more natu
 
 | Method | Replaces... | Behavior |
 |---|---|---|
-| `init()` | `setUpWithError()`, `setUp()` | The initializer for your suite. Put all setup code here. It can be `async` and `throws`. |
-| `deinit` | `tearDownWithError()`, `tearDown()` | The deinitializer. Put cleanup code here. It runs automatically after each test. **Note:** `deinit` is only available on `class` or `actor` suite types, not `struct`s. This is a common reason to choose a class for your suite. |
-| **Instance Properties** | `var sut: MyType!` | Stored properties on the suite (`let sut: MyType`). They are initialized in `init()` for each test run. |
+| `init()` | `setUpWithError()` | The initializer for your suite. Put all setup code here. It can be `async` and `throws`. |
+| `deinit` | `tearDownWithError()` | The deinitializer. Put cleanup code here. It runs automatically after each test. **Note:** `deinit` is only available on `class` or `actor` suite types, not `struct`s. This is a common reason to choose a class for your suite. |
 
-### Practical Example: Migrating a Test Case
+### Practical Example: Migrating a Database Test Suite
 
+**Before: The XCTest Way**
 ```swift
-// 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)
+        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)
+        sut = DatabaseService(database: testDatabase)
     }
 
     override func tearDownWithError() throws {
         try FileManager.default.removeItem(at: tempDirectory)
-        self.sut = nil
-        self.tempDirectory = nil
+        sut = nil
+        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)
+**After: The Swift Testing Way (using `class` for `deinit`)**
+```swift
 @Suite final class DatabaseServiceTests {
+    // Using a class here to demonstrate `deinit` for cleanup.
     let sut: DatabaseService
     let tempDirectory: URL
 
     init() throws {
+        // 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.
         try? FileManager.default.removeItem(at: tempDirectory)
     }
 
@@ -120,10 +174,10 @@ final class DatabaseServiceXCTests: XCTestCase {
 ```
 
 ### Action Items
-- [ ] Convert test classes from `XCTestCase` to `struct`s (preferred) or `final class`es if `deinit` is needed.
+- [ ] Convert test classes from `XCTestCase` to `struct`s (preferred for automatic state isolation) or `final class`es.
 - [ ] 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()`.
+- [ ] Move `tearDownWithError` logic into the suite's `deinit` (and use a `class` or `actor` if needed).
+- [ ] Define the SUT and its dependencies as `let` properties, initialized in `init()`.
 
 ---
 
@@ -133,99 +187,64 @@ Go beyond `do/catch` with a dedicated, expressive API for validating thrown erro
 
 | Overload | Replaces... | Example & Use Case |
 |---|---|---|
-| **`#expect(throws: Error.self)`**| `XCTAssertThrowsError` | Verifies that *any* error was thrown. |
+| **`#expect(throws: Error.self)`**| Basic `XCTAssertThrowsError` | Verifies that *any* error was thrown. |
 | **`#expect(throws: BrewingError.self)`** | Typed `XCTAssertThrowsError` | Ensures an error of a specific *type* is thrown. |
 | **`#expect(throws: BrewingError.outOfBeans)`**| Specific Error `XCTAssertThrowsError`| Validates a specific error *value* is thrown. |
-| **`#expect(performing:throws:)`** | `do/catch` with `switch` | **Payload Introspection.** The ultimate tool for errors with associated values. It gives you a closure to inspect the thrown error. |
+| **`#expect(throws: ... ) catch: { ... }`** | `do/catch` with `switch` | **Payload Introspection.** The ultimate tool for errors with associated values. It gives you a closure to inspect the thrown error. <br> ```swift #expect(throws: BrewingError.self) { try brew(beans: 0) } catch: { error in guard case let .notEnoughBeans(needed) = error else { Issue.record("Wrong error case thrown"); return } #expect(needed > 0) } ``` |
 | **`#expect(throws: Never.self)`** | `XCTAssertNoThrow` | Explicitly asserts that a function does *not* throw. Ideal for happy-path tests. |
 
-### Migration Example: `XCTAssertThrowsError`
-
-```swift
-// 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()
-    }
-}
-```
-
 ---
 
 ## **5. Parameterized Tests: Drastically Reduce Boilerplate**
 
-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.
+Run a single test function with multiple argument sets to maximize coverage with minimal code. This is superior to a `for-in` loop because each argument set runs as an independent test, can be run in parallel, and failures are reported individually.
 
 | Pattern | How to Use It & When |
 |---|---|
 | **Single Collection** | `@Test(arguments: [0, 100, -40])` <br> The simplest form. Pass a collection of inputs. |
-| **Zipped Collections** | `@Test(arguments: zip(inputs, expectedOutputs))` <br> The most common and powerful pattern. Use `zip` to pair inputs and expected outputs. |
-| **Multiple Collections** | `@Test(arguments: ["USD", "EUR"],)` <br> **⚠️ Caution: Cartesian Product.** This creates a test case for *every possible combination* of arguments. |
+| **Zipped Collections** | `@Test(arguments: zip(inputs, expectedOutputs))` <br> The most common and powerful pattern. Use `zip` to pair inputs and expected outputs, ensuring a one-to-one correspondence. |
+| **Multiple Collections** | `@Test(arguments: ["USD", "EUR"], [1, 10, 100])` <br> **⚠️ Caution: Cartesian Product.** This creates a test case for *every possible combination* of arguments. Use it deliberately when you need to test all combinations. |
 
-### Migration Example: Consolidating Repetitive Tests
+### Example: Migrating Repetitive Tests to a Parameterized One
 
+**Before: The XCTest Way**
 ```swift
-// XCTest
-final class MathXCTests: XCTestCase {
-    func testIsEven() {
-        XCTAssertTrue(isEven(2))
-    }
-    func testIsOdd() {
-        XCTAssertFalse(isEven(3))
-    }
-    func testIsZeroEven() {
-        XCTAssertTrue(isEven(0))
-    }
+func testFlavorVanillaContainsNoNuts() {
+    let flavor = Flavor.vanilla
+    XCTAssertFalse(flavor.containsNuts)
+}
+func testFlavorPistachioContainsNuts() {
+    let flavor = Flavor.pistachio
+    XCTAssertTrue(flavor.containsNuts)
 }
+func testFlavorChocolateContainsNoNuts() {
+    let flavor = Flavor.chocolate
+    XCTAssertFalse(flavor.containsNuts)
+}
+```
 
-// 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)
-    }
+**After: The Swift Testing Way using `zip`**
+```swift
+@Test("Flavor nut content is correct", arguments: zip(
+    [Flavor.vanilla, .pistachio, .chocolate],
+    [false, true, false]
+))
+func testFlavorContainsNuts(flavor: Flavor, expected: Bool) {
+    #expect(flavor.containsNuts == expected)
 }
 ```
 
 ---
 
 ## **6. Conditional Execution & Skipping**
 
-Dynamically control which tests run based on feature flags, environment, or known issues. This replaces XCTest's `XCTSkipUnless` and manual commenting-out of tests.
-
-| Trait | Replaces... | What It Does & How to Use It |
-|---|---|---|
-| **`.disabled("Reason")`** | Commenting out a test | **Unconditionally skips a test.** The test is not run, but it is still compiled. Always provide a descriptive reason for CI visibility (e.g., `"Flaky on CI, see FB12345"`). |
-| **`.enabled(if: condition)`** | `XCTSkipUnless` | **Conditionally runs a test.** The test only runs if the boolean `condition` is `true`. This is perfect for tests tied to feature flags or specific environments. |
-| **`@available(...)`** | Runtime `#available` check | **OS Version-Specific Tests.** Apply this attribute directly to the test function. It's better than a runtime check because it allows the test runner to know the test is skipped for platform reasons. |
-
-### Migration Example: `XCTSkip`
-
-```swift
-// XCTest
-func testNewFeature() throws {
-    try XCTSkipUnless(FeatureFlags.isNewAPIEnabled, "New API feature flag is not enabled.")
-    // ... test code
-}
+Dynamically control which tests run based on feature flags, environment, or known issues.
 
-// Swift Testing
-@Test("New feature test", .enabled(if: FeatureFlags.isNewAPIEnabled, "New API feature flag not enabled"))
-func testNewFeature() {
-    // ... test code
-}
-```
+| Trait | What It Does & How to Use It |
+|---|---|
+| **`.disabled("Reason")`** | **Unconditionally skips a test.** The test is not run, but it is still compiled. Always provide a descriptive reason for CI visibility (e.g., `"Flaky on CI, see FB12345"`). |
+| **`.enabled(if: condition)`** | **Conditionally runs a test.** The test only runs if the boolean `condition` is `true`. This is perfect for tests tied to feature flags or specific environments. <br> ```swift @Test(.enabled(if: FeatureFlags.isNewAPIEnabled)) func testNewAPI() { /* ... */ } ``` |
+| **`@available(...)`** | **OS Version-Specific Tests.** Apply this attribute directly to the test function. It's better than a runtime `#available` check because it allows the test runner to know the test is skipped for platform reasons, which is cleaner in test reports. |
 
 ---
 
@@ -259,6 +278,7 @@ Tags associate tests with common characteristics (e.g., `.network`, `.ui`, `.reg
         @Tag static var fast: Self
         @Tag static var regression: Self
         @Tag static var flaky: Self
+        @Tag static var networking: Self
     }
     ```
 2.  **Apply Tags & Filter:**
@@ -268,62 +288,84 @@ Tags associate tests with common characteristics (e.g., `.network`, `.ui`, `.reg
     func testUsername() { /* ... */ }
 
     // Run from CLI
-    // swift test --filter-tag fast
+    // swift test --filter .fast
+    // swift test --skip .flaky
+    // swift test --filter .networking --filter .regression
 
     // Filter in Xcode Test Plan
-    // Add "fast" to the "Include" field or "flaky" to the "Exclude" field.
+    // Add "fast" to the "Include Tags" field or "flaky" to the "Exclude Tags" field.
     ```
+### Power Move: Xcode UI Integration for Tags
+Xcode 16 deeply integrates with tags, turning them into a powerful organizational tool.
+
+-   **Grouping by Tag in Test Navigator:** In the Test Navigator (`Cmd-6`), click the tag icon at the top. This switches the view from the file hierarchy to one where tests are grouped by their tags. It's a fantastic way to visualize and run all tests related to a specific feature.
+-   **Test Report Insights:** After a test run, the Test Report can automatically find patterns. Go to the **Insights** tab to see messages like **"All 7 tests with the 'networking' tag failed."** This immediately points you to systemic issues, saving significant debugging time.
 
 ---
 
 ## **9. Concurrency and Asynchronous Testing**
 
-### Migrating Asynchronous Tests
-Swift Testing's native `async/await` support simplifies asynchronous code significantly compared to `XCTestExpectation`.
-
+### Async/Await and Confirmations
 - **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.
-
-### Migration Example: `XCTestExpectation`
+- **Confirmations**: To test APIs with completion handlers or that fire multiple times (like delegates or notifications), use `confirmation`.
+- **`fulfillment(of:timeout:)`**: This is the global function you `await` to pause the test until your confirmations are fulfilled or a timeout is reached.
 
 ```swift
-// XCTest
-func testDataDownload() {
-    let expectation = self.expectation(description: "Download should complete")
+@Test("Delegate is notified 3 times")
+async func testDelegateNotifications() async throws {
+    // Create a confirmation that expects to be fulfilled exactly 3 times.
+    let confirmation = confirmation("delegate.didUpdate was called", expectedCount: 3)
+    let delegate = MockDelegate { await confirmation.fulfill() }
+    let sut = SystemUnderTest(delegate: delegate)
+
+    sut.performActionThatNotifiesThreeTimes()
 
-    let downloader = Downloader()
-    downloader.onComplete = { data in
-        XCTAssertFalse(data.isEmpty)
-        expectation.fulfill()
-    }
+    // Explicitly wait for the confirmation to be fulfilled with a 1-second timeout.
+    try await fulfillment(of: [confirmation], timeout: .seconds(1))
+}
+```
+
+### Advanced Asynchronous Patterns
+
+#### Asserting an Event Never Happens
+Use a confirmation with `expectedCount: 0` to verify that a callback or delegate method is *never* called during an operation. If `fulfill()` is called on it, the test will fail.
+
+```swift
+@Test("Logging out does not trigger a data sync")
+async func testLogoutDoesNotSync() async throws {
+    let syncConfirmation = confirmation("data sync was triggered", expectedCount: 0)
+    let mockSyncEngine = MockSyncEngine { await syncConfirmation.fulfill() }
+    let sut = AccountManager(syncEngine: mockSyncEngine)
 
-    downloader.start()
+    sut.logout()
 
-    waitForExpectations(timeout: 5.0)
+    // The test passes if the confirmation is never fulfilled within the timeout.
+    // If it *is* fulfilled, this will throw an error and fail the test.
+    await fulfillment(of: [syncConfirmation], timeout: .seconds(0.5), performing: {})
 }
+```
 
+#### Bridging Legacy Completion Handlers
+For older asynchronous code that uses completion handlers, use `withCheckedThrowingContinuation` to wrap it in a modern `async/await` call that Swift Testing can work with.
 
-// Swift Testing
-@Test("Data downloads successfully")
-async func testDataDownload() async throws {
-    let downloadCompleted = confirmation("Download should complete")
+```swift
+func legacyFetch(completion: @escaping (Result<Data, Error>) -> Void) {
+    // ... legacy async code ...
+}
 
-    let downloader = Downloader()
-    downloader.onComplete = { data in
-        #expect(!data.isEmpty)
-        await downloadCompleted()
+@Test func testLegacyFetch() async throws {
+    let data = try await withCheckedThrowingContinuation { continuation in
+        legacyFetch { result in
+            continuation.resume(with: result)
+        }
     }
-
-    downloader.start()
-
-    try await fulfillment(of: [downloadCompleted], timeout: .seconds(5))
+    #expect(!data.isEmpty)
 }
 ```
 
 ### Controlling Parallelism
-- **`.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.
+- **`.serialized`**: Apply this trait to a `@Test` or `@Suite` to force its contents to run serially (one at a time). Use this as a temporary measure for legacy tests that are not thread-safe or have hidden state dependencies. The goal should be to refactor them to run in parallel.
+- **`.timeLimit`**: A safety net to prevent hung tests from stalling CI. The more restrictive (shorter) duration wins when applied at both the suite and test level.
 
 ---
 
@@ -335,11 +377,33 @@ async func testDataDownload() async throws {
 | **`CustomTestStringConvertible`** | Provides custom, readable descriptions for your types in test failure logs. Conform your key models to this protocol to make debugging much easier. |
 | **`.bug("JIRA-123")` Trait** | Associates a test directly with a ticket in your issue tracker. This adds invaluable context to test reports in Xcode and Xcode Cloud. |
 | **`Test.current`** | A static property (`Test.current`) that gives you runtime access to the current test's metadata, such as its name, tags, and source location. Useful for advanced custom logging. |
-| **`#expectAll { ... }`**| Groups multiple assertions. If any assertion inside the block fails, they are all reported together, but execution continues past the block. |
+| **`#expectAll { ... }`**| Groups multiple assertions. If any assertion inside the block fails, they are all reported together, but execution continues past the block. This is great for validating multiple properties of a single object. |
 
 ---
 
-## **11. Migrating from XCTest: A Detailed Guide**
+## **11. Common Pitfalls and How to Avoid Them**
+
+A checklist of common mistakes developers make when adopting Swift Testing.
+
+1.  **Overusing `#require()`**
+    -   **The Pitfall:** Using `#require()` for every check. This makes tests brittle and hides information. If the first `#require()` fails, the rest of the test is aborted, and you won't know if other things were also broken.
+    -   **The Fix:** Use `#expect()` for most checks. Only use `#require()` for essential setup conditions where the rest of the test would be nonsensical if they failed (e.g., a non-nil SUT, a valid URL).
+
+2.  **Forgetting State is Isolated**
+    -   **The Pitfall:** Assuming that a property modified in one test will retain its value for the next test in the same suite.
+    -   **The Fix:** Remember that a **new instance** of the suite is created for every test. This is a feature, not a bug! All shared setup must happen in `init()`. Do not rely on state carrying over between tests.
+
+3.  **Accidentally Using a Cartesian Product**
+    -   **The Pitfall:** Passing multiple collections to a parameterized test without `zip`, causing an exponential explosion of test cases (`@Test(arguments: collectionA, collectionB)`).
+    -   **The Fix:** Be deliberate. If you want one-to-one pairing, **always use `zip`**. Only use the multi-collection syntax when you explicitly want to test every possible combination.
+
+4.  **Ignoring the `.serialized` Trait for Unsafe Tests**
+    -   **The Pitfall:** Migrating old, stateful tests that are not thread-safe and seeing them fail randomly due to parallel execution.
+    -   **The Fix:** As a temporary measure, apply the `.serialized` trait to the suite containing these tests. This forces them to run one-at-a-time, restoring the old behavior. The long-term goal should be to refactor the tests to be parallel-safe and remove the trait.
+
+---
+
+## **12. Migrating from XCTest**
 
 Swift Testing and XCTest can coexist in the same target, enabling an incremental migration.
 
@@ -348,32 +412,19 @@ Swift Testing and XCTest can coexist in the same target, enabling an incremental
 | Feature | XCTest | Swift Testing |
 |---|---|---|
 | **Test Discovery** | Method name must start with `test...` | `@Test` attribute on any function or method. |
-| **Suite Type** | `class MyTests: XCTestCase` | `struct MyTests` (preferred), `class`, or `actor`. No inheritance needed. |
+| **Suite Type** | `class MyTests: XCTestCase` | `struct MyTests` (preferred), `class`, or `actor`. |
 | **Assertions** | `XCTAssert...()` family of functions | `#expect()` and `#require()` macros with Swift expressions. |
 | **Error Unwrapping** | `try XCTUnwrap(...)` | `try #require(...)` |
 | **Setup/Teardown**| `setUpWithError()`, `tearDownWithError()` | `init()`, `deinit` (on classes/actors) |
 | **Asynchronous Wait**| `XCTestExpectation` | `confirmation()` and `await fulfillment(of:timeout:)` |
-| **Parallelism** | Opt-in, multi-process | Opt-out, in-process via Swift Concurrency. Runs in parallel by default. |
+| **Parallelism** | Opt-in, multi-process | Opt-out, in-process via Swift Concurrency. |
 
 ### What NOT to Migrate (Yet)
 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**
 
-### Common Assertion Conversions
-
-| XCTest Assertion | Swift Testing Equivalent | Notes |
-|---|---|---|
-| `XCTAssert(expr)` | `#expect(expr)` | Direct replacement. |
-| `XCTAssertEqual(a, b)` | `#expect(a == b)` | Use standard operators. |
-| `XCTAssertNotEqual(a, b)`| `#expect(a != b)` | Use standard operators. |
-| `XCTAssertNil(a)` | `#expect(a == nil)` | Direct check for nil. |
-| `XCTAssertNotNil(a)` | `#expect(a != nil)` | Direct check for not-nil. |
-| `XCTAssertTrue(a)` | `#expect(a)` | No change needed if `a` is a Bool. |
-| `XCTAssertFalse(a)` | `#expect(!a)` | Use the `!` operator. |
-| `XCTAssertGreaterThan(a, b)` | `#expect(a > b)` | Use standard operators. |
-
 ---
 
 ## **Appendix: Evergreen Testing Principles (The F.I.R.S.T. Principles)**

diff --git a/swift-testing-playbook.md b/swift-testing-playbook.md
@@ -1,12 +1,4 @@
-Of course. I have browsed the Apple Developer documentation page on migrating from XCTest and have extracted detailed comparisons, patterns, and code examples to significantly expand the playbook.
-
-This new version provides more granular, side-by-side examples for nearly every common XCTest pattern, making it a much more practical and comprehensive guide for developers actively migrating their test suites.
-
-Here is the expanded and more detailed playbook:
-
-***
-
-# The Ultimate Swift Testing Playbook (2024 WWDC Edition, Expanded)
+# The Ultimate Swift Testing Playbook
 
 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.
 

diff --git a/swift-testing-playbook.md b/swift-testing-playbook.md
@@ -1,4 +1,12 @@
-# The Ultimate Swift Testing Playbook (2024 WWDC Edition)
+Of course. I have browsed the Apple Developer documentation page on migrating from XCTest and have extracted detailed comparisons, patterns, and code examples to significantly expand the playbook.
+
+This new version provides more granular, side-by-side examples for nearly every common XCTest pattern, making it a much more practical and comprehensive guide for developers actively migrating their test suites.
+
+Here is the expanded and more detailed playbook:
+
+***
+
+# The Ultimate Swift Testing Playbook (2024 WWDC Edition, Expanded)
 
 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.
 
@@ -34,13 +42,12 @@ Replace the entire `XCTAssert` family with two powerful, expressive macros. They
 `#require` is the new, safer replacement for `XCTUnwrap`. It not only checks for `nil` but also unwraps the value for subsequent use.
 
 ```swift
-// Old XCTest way
+// XCTest
 let user = try XCTUnwrap(await fetchUser())
+XCTAssertEqual(user.age, 37)
 
-// New, safer Swift Testing way
+// Swift Testing
 let user = try #require(await fetchUser())
-
-// `user` is now a non-optional User, ready for further assertions.
 #expect(user.age == 37)
 ```
 
@@ -60,28 +67,57 @@ Swift Testing replaces `setUpWithError` and `tearDownWithError` with a more natu
 
 | Method | Replaces... | Behavior |
 |---|---|---|
-| `init()` | `setUpWithError()` | The initializer for your suite. Put all setup code here. It can be `async` and `throws`. |
-| `deinit` | `tearDownWithError()` | The deinitializer. Put cleanup code here. It runs automatically after each test. **Note:** `deinit` is only available on `class` or `actor` suite types, not `struct`s. This is a common reason to choose a class for your suite. |
+| `init()` | `setUpWithError()`, `setUp()` | The initializer for your suite. Put all setup code here. It can be `async` and `throws`. |
+| `deinit` | `tearDownWithError()`, `tearDown()` | The deinitializer. Put cleanup code here. It runs automatically after each test. **Note:** `deinit` is only available on `class` or `actor` suite types, not `struct`s. This is a common reason to choose a class for your suite. |
+| **Instance Properties** | `var sut: MyType!` | Stored properties on the suite (`let sut: MyType`). They are initialized in `init()` for each test run. |
 
-### Practical Example: A Database Test Suite
+### Practical Example: Migrating a Test Case
 
 ```swift
-@Suite struct DatabaseServiceTests {
-    // Use `struct` by default for value semantics and state isolation.
+// 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 {
-        // 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)
     }
-
-    // For structs, teardown happens automatically when the value is destroyed.
-    // If you need explicit cleanup (e.g., closing a connection), use a class with deinit.
+
+    deinit {
+        try? FileManager.default.removeItem(at: tempDirectory)
+    }
 
     @Test func testSavingUser() throws {
         let user = User(id: "user-1", name: "Alex")
@@ -92,10 +128,10 @@ Swift Testing replaces `setUpWithError` and `tearDownWithError` with a more natu
 ```
 
 ### Action Items
-- [ ] Convert test classes from `XCTestCase` to `struct`s (preferred) or `final class`es.
+- [ ] Convert test classes from `XCTestCase` to `struct`s (preferred) or `final class`es if `deinit` is needed.
 - [ ] Move `setUpWithError` logic into the suite's `init()`.
-- [ ] Move `tearDownWithError` logic into the suite's `deinit` (and use a `class` if needed).
-- [ ] Define the SUT and its dependencies as `let` properties, initialized in `init()`.
+- [ ] Move `tearDownWithError` logic into the suite's `deinit`.
+- [ ] Define the SUT and its dependencies as non-optional `let` properties, initialized in `init()`.
 
 ---
 
@@ -105,47 +141,99 @@ Go beyond `do/catch` with a dedicated, expressive API for validating thrown erro
 
 | Overload | Replaces... | Example & Use Case |
 |---|---|---|
-| **`#expect(throws: Error.self)`**| Basic `XCTAssertThrowsError` | Verifies that *any* error was thrown. |
+| **`#expect(throws: Error.self)`**| `XCTAssertThrowsError` | Verifies that *any* error was thrown. |
 | **`#expect(throws: BrewingError.self)`** | Typed `XCTAssertThrowsError` | Ensures an error of a specific *type* is thrown. |
 | **`#expect(throws: BrewingError.outOfBeans)`**| Specific Error `XCTAssertThrowsError`| Validates a specific error *value* is thrown. |
-| **`#expect(performing:throws:)`** | `do/catch` with `switch` | **Payload Introspection.** The ultimate tool for errors with associated values. It gives you a closure to inspect the thrown error. <br> ```swift #expect(performing: { try brew(beans: 0) }, throws: { (error: BrewingError) in guard case let .notEnoughBeans(needed) = error else { return false } return needed > 0 }) ``` |
+| **`#expect(performing:throws:)`** | `do/catch` with `switch` | **Payload Introspection.** The ultimate tool for errors with associated values. It gives you a closure to inspect the thrown error. |
 | **`#expect(throws: Never.self)`** | `XCTAssertNoThrow` | Explicitly asserts that a function does *not* throw. Ideal for happy-path tests. |
 
+### Migration Example: `XCTAssertThrowsError`
+
+```swift
+// 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()
+    }
+}
+```
+
 ---
 
 ## **5. Parameterized Tests: Drastically Reduce Boilerplate**
 
-Run a single test function with multiple argument sets to maximize coverage with minimal code. This is superior to a `for-in` loop because each argument set runs as an independent test, can be run in parallel, and failures are reported individually.
+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.
 
 | Pattern | How to Use It & When |
 |---|---|
 | **Single Collection** | `@Test(arguments: [0, 100, -40])` <br> The simplest form. Pass a collection of inputs. |
-| **Zipped Collections** | `@Test(arguments: zip(inputs, expectedOutputs))` <br> The most common and powerful pattern. Use `zip` to pair inputs and expected outputs, ensuring a one-to-one correspondence. |
-| **Multiple Collections** | `@Test(arguments: ["USD", "EUR"],)` <br> **⚠️ Caution: Cartesian Product.** This creates a test case for *every possible combination* of arguments. Use it deliberately when you need to test all combinations. |
+| **Zipped Collections** | `@Test(arguments: zip(inputs, expectedOutputs))` <br> The most common and powerful pattern. Use `zip` to pair inputs and expected outputs. |
+| **Multiple Collections** | `@Test(arguments: ["USD", "EUR"],)` <br> **⚠️ Caution: Cartesian Product.** This creates a test case for *every possible combination* of arguments. |
 
-### Example using `zip`
+### Migration Example: Consolidating Repetitive Tests
 
 ```swift
-@Test("Flavor nut content is correct", arguments: zip(
-    [Flavor.vanilla, .pistachio, .chocolate],
-    [false, true, false]
-))
-func testFlavorContainsNuts(flavor: Flavor, expected: Bool) {
-    #expect(flavor.containsNuts == expected)
+// 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)
+    }
 }
 ```
 
 ---
 
 ## **6. Conditional Execution & Skipping**
 
-Dynamically control which tests run based on feature flags, environment, or known issues.
+Dynamically control which tests run based on feature flags, environment, or known issues. This replaces XCTest's `XCTSkipUnless` and manual commenting-out of tests.
 
-| Trait | What It Does & How to Use It |
-|---|---|
-| **`.disabled("Reason")`** | **Unconditionally skips a test.** The test is not run, but it is still compiled. Always provide a descriptive reason for CI visibility (e.g., `"Flaky on CI, see FB12345"`). |
-| **`.enabled(if: condition)`** | **Conditionally runs a test.** The test only runs if the boolean `condition` is `true`. This is perfect for tests tied to feature flags or specific environments. <br> ```swift @Test(.enabled(if: FeatureFlags.isNewAPIEnabled)) func testNewAPI() { /* ... */ } ``` |
-| **`@available(...)`** | **OS Version-Specific Tests.** Apply this attribute directly to the test function. It's better than a runtime `#available` check because it allows the test runner to know the test is skipped for platform reasons. |
+| Trait | Replaces... | What It Does & How to Use It |
+|---|---|---|
+| **`.disabled("Reason")`** | Commenting out a test | **Unconditionally skips a test.** The test is not run, but it is still compiled. Always provide a descriptive reason for CI visibility (e.g., `"Flaky on CI, see FB12345"`). |
+| **`.enabled(if: condition)`** | `XCTSkipUnless` | **Conditionally runs a test.** The test only runs if the boolean `condition` is `true`. This is perfect for tests tied to feature flags or specific environments. |
+| **`@available(...)`** | Runtime `#available` check | **OS Version-Specific Tests.** Apply this attribute directly to the test function. It's better than a runtime check because it allows the test runner to know the test is skipped for platform reasons. |
+
+### Migration Example: `XCTSkip`
+
+```swift
+// 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
+}
+```
 
 ---
 
@@ -198,28 +286,52 @@ Tags associate tests with common characteristics (e.g., `.network`, `.ui`, `.reg
 
 ## **9. Concurrency and Asynchronous Testing**
 
-### Async/Await and Confirmations
+### Migrating Asynchronous Tests
+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`.
-- **Confirmations**: To test APIs with completion handlers or that fire multiple times (like delegates or notifications), use `confirmation`.
-- **`fulfillment(of:timeout:)`**: This is the global function you `await` to pause the test until your confirmations are fulfilled or a timeout is reached.
+- **`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.
+
+### Migration Example: `XCTestExpectation`
 
 ```swift
-@Test("Delegate is notified 3 times")
-async func testDelegateNotifications() async throws {
-    let confirmation = confirmation("delegate.didUpdate was called", expectedCount: 3)
-    let delegate = MockDelegate { await confirmation() }
-    let sut = SystemUnderTest(delegate: delegate)
+// 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)
+}
 
-    sut.performActionThatNotifiesThreeTimes()
+
+// 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()
 
-    // Explicitly wait for the confirmation to be fulfilled with a 1-second timeout.
-    try await fulfillment(of: [confirmation], timeout: .seconds(1))
+    try await fulfillment(of: [downloadCompleted], timeout: .seconds(5))
 }
 ```
 
 ### Controlling Parallelism
-- **`.serialized`**: Apply this trait to a `@Test` or `@Suite` to force its contents to run serially (one at a time). Use this as a temporary measure for legacy tests that are not thread-safe or have hidden state dependencies. The goal should be to refactor them to run in parallel.
-- **`.timeLimit`**: A safety net to prevent hung tests from stalling CI. The more restrictive (shorter) duration wins when applied at both the suite and test level.
+- **`.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.
 
 ---
 
@@ -235,7 +347,7 @@ async func testDelegateNotifications() async throws {
 
 ---
 
-## **11. Migrating from XCTest**
+## **11. Migrating from XCTest: A Detailed Guide**
 
 Swift Testing and XCTest can coexist in the same target, enabling an incremental migration.
 
@@ -244,19 +356,32 @@ Swift Testing and XCTest can coexist in the same target, enabling an incremental
 | Feature | XCTest | Swift Testing |
 |---|---|---|
 | **Test Discovery** | Method name must start with `test...` | `@Test` attribute on any function or method. |
-| **Suite Type** | `class MyTests: XCTestCase` | `struct MyTests` (preferred), `class`, or `actor`. |
+| **Suite Type** | `class MyTests: XCTestCase` | `struct MyTests` (preferred), `class`, or `actor`. No inheritance needed. |
 | **Assertions** | `XCTAssert...()` family of functions | `#expect()` and `#require()` macros with Swift expressions. |
 | **Error Unwrapping** | `try XCTUnwrap(...)` | `try #require(...)` |
 | **Setup/Teardown**| `setUpWithError()`, `tearDownWithError()` | `init()`, `deinit` (on classes/actors) |
 | **Asynchronous Wait**| `XCTestExpectation` | `confirmation()` and `await fulfillment(of:timeout:)` |
-| **Parallelism** | Opt-in, multi-process | Opt-out, in-process via Swift Concurrency. |
+| **Parallelism** | Opt-in, multi-process | Opt-out, in-process via Swift Concurrency. Runs in parallel by default. |
 
 ### What NOT to Migrate (Yet)
 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**
 
+### Common Assertion Conversions
+
+| XCTest Assertion | Swift Testing Equivalent | Notes |
+|---|---|---|
+| `XCTAssert(expr)` | `#expect(expr)` | Direct replacement. |
+| `XCTAssertEqual(a, b)` | `#expect(a == b)` | Use standard operators. |
+| `XCTAssertNotEqual(a, b)`| `#expect(a != b)` | Use standard operators. |
+| `XCTAssertNil(a)` | `#expect(a == nil)` | Direct check for nil. |
+| `XCTAssertNotNil(a)` | `#expect(a != nil)` | Direct check for not-nil. |
+| `XCTAssertTrue(a)` | `#expect(a)` | No change needed if `a` is a Bool. |
+| `XCTAssertFalse(a)` | `#expect(!a)` | Use the `!` operator. |
+| `XCTAssertGreaterThan(a, b)` | `#expect(a > b)` | Use standard operators. |
+
 ---
 
 ## **Appendix: Evergreen Testing Principles (The F.I.R.S.T. Principles)**

diff --git a/swift-testing-playbook.md b/swift-testing-playbook.md
@@ -1,80 +1,73 @@
-# The Ultimate Swift Testing Playbook
+# The Ultimate Swift Testing Playbook (2024 WWDC Edition)
 
-A hands-on guide for migrating from XCTest and mastering the full power of Swift Testing. This playbook focuses on practical patterns to make your tests more powerful, expressive, and maintainable, incorporating best practices from the official Apple WWDC 2024 sessions.
+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.
 
 ---
 
 ## **1. Migration & Tooling Baseline**
 
-Swift Testing is the new default in Xcode 16. Ensure your environment is set up for a smooth, gradual migration.
+Ensure your environment is set up for a smooth, gradual migration.
 
 | What | Why |
 |---|---|
-| **Xcode 16 & Swift 6** | Swift Testing is bundled with the latest toolchain and leverages modern Swift features like macros. |
-| **Keep XCTest Targets** | Swift Testing and XCTest tests can coexist in the same target, allowing for a file-by-file migration without disrupting CI. |
-| **Enable Parallel Execution**| In your Test Plan, ensure "Use parallel execution" is enabled. This is the default behavior for Swift Testing and is crucial for faster feedback. |
-| **SPM for Cross-Platform**| For projects supporting Linux or Windows, add the `swift-testing` package dependency in your `Package.swift`. This is not needed for Apple platforms. |
+| **Xcode 16 & Swift 6** | Swift Testing is bundled with the latest toolchain. It leverages modern Swift features like macros and concurrency. |
+| **Keep XCTest Targets** | **Incremental Migration is Key.** You can have XCTest and Swift Testing tests in the same target, allowing you to migrate file-by-file without breaking CI. |
+| **Enable Parallel Execution**| In your Test Plan, ensure "Use parallel execution" is enabled. Swift Testing runs tests in parallel by default, which speeds up test runs and helps surface hidden state dependencies. |
 
 ### Migration Action Items
-- [ ] Ensure all developer machines and CI runners are on **macOS 15+** and **Xcode 16+**.
-- [ ] In your primary test plan, confirm that **“Use parallel execution”** is active.
-- [ ] For any Swift packages, add `swift-testing` to your test target dependencies if you need to support non-Apple platforms.
+- [ ] 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.
 
 ---
 
-## **2. Expressive Expectations: `#expect` & `#require`**
+## **2. Expressive Assertions: `#expect` & `#require`**
 
-Replace the entire `XCTAssert` family with two powerful, expressive macros that understand native Swift expressions.
+Replace the entire `XCTAssert` family with two powerful, expressive macros. They accept regular Swift expressions, eliminating the need for dozens of specialized `XCTAssert` functions.
 
 | Macro | Use Case & Behavior |
 |---|---|
-| **`#expect(expression)`** | **The Default Check.** Use for most validations. It accepts any boolean Swift expression. If it fails, the issue is recorded, but the test continues, letting you find multiple failures in a single run. |
-| **`#require(expression)`**| **The Hard Check.** Use for critical preconditions. If the expression is false or throws, the test is immediately aborted. This prevents cascading failures when a setup step fails. |
-
-**Power of Native Expressions:** You don't need specialized assertion functions anymore. Just write normal Swift code.
-```swift
-// Instead of XCTAssertEqual, XCTAssertTrue, XCTAssertContains...
-#expect(video.duration == 180)
-#expect(tags.isEmpty)
-#expect(video.title.contains("WWDC"))
-```
+| **`#expect(expression)`** | **Soft Check.** Use for most validations. If the expression is `false`, the issue is recorded, but the test function continues executing. This allows you to find multiple failures in a single run. |
+| **`#require(expression)`**| **Hard Check.** Use for critical preconditions (e.g., unwrapping an optional). If the expression is `false` or throws, the test is immediately aborted. This prevents cascading failures from an invalid state. |
 
 ### Power Move: Optional-Safe Unwrapping
-`#require` is the modern, safer replacement for `XCTUnwrap`. It not only checks for `nil` but also unwraps the value for subsequent use.
+`#require` is the new, safer replacement for `XCTUnwrap`. It not only checks for `nil` but also unwraps the value for subsequent use.
 
 ```swift
 // 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.isLoggedIn)
+#expect(user.age == 37)
 ```
 
 ### Action Items
-- [ ] Globally search for `XCTAssert` and replace with `#expect` for most cases.
-- [ ] Convert all `XCTUnwrap` calls to `try #require()`.
-- [ ] Use `try #require()` for any setup that, if it fails, would make the rest of the test meaningless.
+- [ ] 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.
 
 ---
 
 ## **3. Setup, Teardown, and State Lifecycle**
 
-Swift Testing introduces a natural, type-safe lifecycle using `init()` and `deinit`, replacing `setUpWithError` and `tearDownWithError`.
+Swift Testing replaces `setUpWithError` and `tearDownWithError` with a more natural, type-safe lifecycle using `init()` and `deinit`.
 
-**The Core Principle:** A fresh, new instance of the test suite (`struct`, `class`, or `actor`) 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. Using `struct`s is highly encouraged to leverage value semantics.
+**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.
 
 | Method | Replaces... | Behavior |
 |---|---|---|
-| `init()` | `setUpWithError()` | The initializer for your suite. This is where you create the System Under Test (SUT), prepare mocks, and establish initial state. It runs before **each** test. |
-| `deinit` | `tearDownWithError()` | The deinitializer for your suite. This is for cleanup code, like deleting temporary files. It runs automatically after each test completes. (Requires using a `class` or `actor`.) |
+| `init()` | `setUpWithError()` | The initializer for your suite. Put all setup code here. It can be `async` and `throws`. |
+| `deinit` | `tearDownWithError()` | The deinitializer. Put cleanup code here. It runs automatically after each test. **Note:** `deinit` is only available on `class` or `actor` suite types, not `struct`s. This is a common reason to choose a class for your suite. |
 
 ### Practical Example: A Database Test Suite
 
 ```swift
 @Suite struct DatabaseServiceTests {
-    // Properties are re-initialized for every test function.
+    // Use `struct` by default for value semantics and state isolation.
     let sut: DatabaseService
     let tempDirectory: URL
 
@@ -86,158 +79,194 @@ Swift Testing introduces a natural, type-safe lifecycle using `init()` and `dein
         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)
-    }
+
+    // For structs, teardown happens automatically when the value is destroyed.
+    // If you need explicit cleanup (e.g., closing a connection), use a class with deinit.
 
     @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 {
-        // This test runs with a completely separate, clean instance of DatabaseServiceTests.
-        // The tempDirectory will be different and won't conflict with testSavingUser.
-    }
 }
 ```
 
+### Action Items
+- [ ] Convert test classes from `XCTestCase` to `struct`s (preferred) or `final class`es.
+- [ ] Move `setUpWithError` logic into the suite's `init()`.
+- [ ] Move `tearDownWithError` logic into the suite's `deinit` (and use a `class` if needed).
+- [ ] Define the SUT and its dependencies as `let` properties, initialized in `init()`.
+
 ---
 
 ## **4. Mastering Error Handling**
 
-Go beyond simple `do/catch` with a dedicated, expressive API for validating thrown errors.
+Go beyond `do/catch` with a dedicated, expressive API for validating thrown errors.
 
-| `#expect` Overload | Replaces... | Example & Use Case |
+| Overload | Replaces... | Example & Use Case |
 |---|---|---|
-| **`throws: Error.self`**| Basic `XCTAssertThrowsError` | Verifies that *any* error was thrown. |
-| **`throws: BrewingError.self`** | Typed `XCTAssertThrowsError` | Ensures an error of a specific *type* is thrown. Fails if a different error type is thrown. |
-| **`throws: BrewingError.outOfBeans`**| Specific Error `XCTAssertThrowsError`| Validates a specific error *value* is thrown. |
-| **`throws: Never.self`** | `XCTAssertNoThrow` | Explicitly asserts that a function completes successfully and does *not* throw. |
-| **`performing:throws:`** | Manual `do/catch` with pattern matching | **Deep Error Inspection.** Lets you provide a closure to inspect the thrown error, perfect for validating associated values. <br> ```swift #expect( performing: { try brew(beans: 0) }, throws: { (error: BrewingError) in guard case let .notEnoughBeans(needed) = error else { return false } return needed > 0 } ) ``` |
+| **`#expect(throws: Error.self)`**| Basic `XCTAssertThrowsError` | Verifies that *any* error was thrown. |
+| **`#expect(throws: BrewingError.self)`** | Typed `XCTAssertThrowsError` | Ensures an error of a specific *type* is thrown. |
+| **`#expect(throws: BrewingError.outOfBeans)`**| Specific Error `XCTAssertThrowsError`| Validates a specific error *value* is thrown. |
+| **`#expect(performing:throws:)`** | `do/catch` with `switch` | **Payload Introspection.** The ultimate tool for errors with associated values. It gives you a closure to inspect the thrown error. <br> ```swift #expect(performing: { try brew(beans: 0) }, throws: { (error: BrewingError) in guard case let .notEnoughBeans(needed) = error else { return false } return needed > 0 }) ``` |
+| **`#expect(throws: Never.self)`** | `XCTAssertNoThrow` | Explicitly asserts that a function does *not* throw. Ideal for happy-path tests. |
 
 ---
 
-## **5. Parameterized Tests: Eradicate Boilerplate**
+## **5. Parameterized Tests: Drastically Reduce Boilerplate**
 
-Run a single test function with multiple argument sets to drastically reduce repetitive code and increase coverage.
+Run a single test function with multiple argument sets to maximize coverage with minimal code. This is superior to a `for-in` loop because each argument set runs as an independent test, can be run in parallel, and failures are reported individually.
 
-| Pattern | How to Use It |
+| Pattern | How to Use It & When |
 |---|---|
-| **Basic Arguments** | `@Test(arguments: [0, 100, -40])` Pass a simple collection. Swift Testing runs a separate test case for each element. |
-| **Zipped Collections** | `@Test(arguments: zip(inputs, expectedOutputs))` **The most common pattern.** Use `zip` to pair inputs with their expected outputs, avoiding a combinatorial explosion. |
-| **Multiple Collections** | `@Test(arguments: ["USD", "EUR"], [1, 100])` Creates a test case for every possible combination (Cartesian Product). Use with caution, as this can lead to an exponential number of tests. |
+| **Single Collection** | `@Test(arguments: [0, 100, -40])` <br> The simplest form. Pass a collection of inputs. |
+| **Zipped Collections** | `@Test(arguments: zip(inputs, expectedOutputs))` <br> The most common and powerful pattern. Use `zip` to pair inputs and expected outputs, ensuring a one-to-one correspondence. |
+| **Multiple Collections** | `@Test(arguments: ["USD", "EUR"],)` <br> **⚠️ Caution: Cartesian Product.** This creates a test case for *every possible combination* of arguments. Use it deliberately when you need to test all combinations. |
+
+### Example using `zip`
 
-### Example: From Repetitive to Parameterized
 ```swift
-// Before: Repetitive and hard to maintain
-@Test func testVanillaContainsNoNuts() { #expect(Flavor.vanilla.containsNuts == false) }
-@Test func testChocolateContainsNoNuts() { #expect(Flavor.chocolate.containsNuts == false) }
-@Test func testPistachioContainsNuts() { #expect(Flavor.pistachio.containsNuts == true) }
-
-// After: Clean, scalable, and easy to read
-@Test(arguments: [
-    (flavor: .vanilla, expected: false),
-    (flavor: .chocolate, expected: false),
-    (flavor: .pistachio, expected: true)
-])
-func testFlavorNutContent(pair: (flavor: Flavor, expected: Bool)) {
-    #expect(pair.flavor.containsNuts == pair.expected)
+@Test("Flavor nut content is correct", arguments: zip(
+    [Flavor.vanilla, .pistachio, .chocolate],
+    [false, true, false]
+))
+func testFlavorContainsNuts(flavor: Flavor, expected: Bool) {
+    #expect(flavor.containsNuts == expected)
 }
 ```
 
 ---
 
-## **6. Structure and Organization at Scale**
+## **6. Conditional Execution & Skipping**
 
-Use suites and tags to manage large, complex test bases and gain valuable insights.
+Dynamically control which tests run based on feature flags, environment, or known issues.
 
-### Suites and Nested Suites
-A `@Suite` groups related tests. They can be nested for a clear structural hierarchy. Traits applied to a suite are inherited by all contained tests and sub-suites.
-```swift
-@Suite("API Services", .tags(.network))
-struct APITests {
-    @Suite("Authentication")
-    struct AuthTests { /* ... */ }
+| Trait | What It Does & How to Use It |
+|---|---|
+| **`.disabled("Reason")`** | **Unconditionally skips a test.** The test is not run, but it is still compiled. Always provide a descriptive reason for CI visibility (e.g., `"Flaky on CI, see FB12345"`). |
+| **`.enabled(if: condition)`** | **Conditionally runs a test.** The test only runs if the boolean `condition` is `true`. This is perfect for tests tied to feature flags or specific environments. <br> ```swift @Test(.enabled(if: FeatureFlags.isNewAPIEnabled)) func testNewAPI() { /* ... */ } ``` |
+| **`@available(...)`** | **OS Version-Specific Tests.** Apply this attribute directly to the test function. It's better than a runtime `#available` check because it allows the test runner to know the test is skipped for platform reasons. |
 
-    @Suite("User Profile")
-    struct ProfileTests { /* ... */ }
-}
-```
+---
+
+## **7. Specialized Assertions for Clearer Failures**
+
+While `#expect(a == b)` works, purpose-built assertions provide sharper, more actionable failure messages by explaining *why* something failed, not just *that* it failed.
+
+| Assertion Type | Why It's Better Than a Generic Check |
+| :--- | :--- |
+| **Comparing Collections (Unordered)**<br>Use `#expect(collection:unorderedEquals:)` | A simple `==` check on arrays fails if elements are the same but the order is different. This specialized assertion checks for equality while ignoring order, preventing false negatives for tests where order doesn't matter. <br><br> **Brittle:** `#expect(tags == ["ios", "swift"])` <br> **Robust:** `#expect(collection: tags, unorderedEquals: ["swift", "ios"])` |
+| **Floating-Point Accuracy**<br>Use `accuracy:` parameters. | Floating-point math is imprecise. `#expect(0.1 + 0.2 == 0.3)` will fail. Specialized assertions allow you to specify a tolerance, ensuring tests are robust against minor floating-point inaccuracies. <br><br> **Fails:** `#expect(result == 0.3)` <br> **Passes:** `#expect(result, toEqual: 0.3, within: 0.0001)` |
+
+---
+
+## **8. Structure and Organization at Scale**
+
+Use suites and tags to manage large and complex test bases.
+
+### Suites and Nested Suites
+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 for Cross-Cutting Concerns
-Tags associate tests with shared characteristics, regardless of their file or suite. This is incredibly powerful for filtering and analysis.
+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:**
     ```swift
     // /Tests/Support/TestTags.swift
     import Testing
+
     extension Tag {
-        @Tag static var network: Self
+        @Tag static var fast: Self
         @Tag static var regression: Self
-        @Tag static var spicy: Self // As seen on TV
+        @Tag static var flaky: Self
     }
     ```
 2.  **Apply Tags & Filter:**
     ```swift
-    @Test("Username validation", .tags(.regression)) // Apply the tag
-    // CLI: swift test --filter-tag regression
-    // Xcode: Use the Test Navigator filter bar
-    ```
-3.  **Leverage Tags in Xcode:**
-    *   **Test Navigator:** Filter tests by tag or switch to the **"Group by Tag"** view.
-    *   **Test Plans:** The editor lets you include or exclude tests based on tags (e.g., "Run all tests *except* those with the `unreleased` tag").
-    *   **Test Reports:** The "Insights" tab can automatically detect patterns, like **"All 5 tests with tag 'spicy' failed,"** pointing you directly to a systemic issue.
+    // Apply to a test or suite
+    @Test("Username validation", .tags(.fast, .regression))
+    func testUsername() { /* ... */ }
 
----
+    // Run from CLI
+    // swift test --filter-tag fast
 
-## **7. Concurrency and Asynchronous Testing**
+    // Filter in Xcode Test Plan
+    // Add "fast" to the "Include" field or "flaky" to the "Exclude" field.
+    ```
 
-Swift Testing is built for the concurrent world.
+---
 
-### Parallel By Default
-Tests run in parallel out-of-the-box, even on physical devices. The execution order is randomized to help surface hidden dependencies between tests (a common source of flakiness).
+## **9. Concurrency and Asynchronous Testing**
 
-### Opting Out with `.serialized`
-If a test suite is not yet thread-safe, apply the `.serialized` trait to force its tests to run one at a time. This should be a temporary measure while you refactor tests to be isolated.
+### Async/Await and Confirmations
+- **Async Tests**: Simply mark your test function `async` and use `await`.
+- **Confirmations**: To test APIs with completion handlers or that fire multiple times (like delegates or notifications), use `confirmation`.
+- **`fulfillment(of:timeout:)`**: This is the global function you `await` to pause the test until your confirmations are fulfilled or a timeout is reached.
 
-### Confirmations for Multiple Callbacks
-For APIs that fire a callback multiple times (like streams or event handlers), use `confirmation` to validate how many times it was called.
 ```swift
-@Test("Data stream sends three packets")
-async func testDataStream() async {
-    let streamFinished = confirmation("Stream sent 3 packets", expectedCount: 3)
-    let myStream = MyDataStream { await streamFinished() }
-    myStream.start()
+@Test("Delegate is notified 3 times")
+async func testDelegateNotifications() async throws {
+    let confirmation = confirmation("delegate.didUpdate was called", expectedCount: 3)
+    let delegate = MockDelegate { await confirmation() }
+    let sut = SystemUnderTest(delegate: delegate)
+
+    sut.performActionThatNotifiesThreeTimes()
 
-    // The test will wait for the confirmation to be fulfilled 3 times.
+    // Explicitly wait for the confirmation to be fulfilled with a 1-second timeout.
+    try await fulfillment(of: [confirmation], timeout: .seconds(1))
 }
 ```
 
-### Preventing Runaway Tests with `.timeLimit`
-The `.timeLimit` trait is a safety net to prevent hung tests from stalling your CI pipeline. If a test exceeds the limit, it fails immediately. When applied to both a suite and a test, the **more restrictive (shorter) duration wins**.
-
-```swift
-@Suite(.timeLimit(.seconds(10)))
-struct NetworkFetcherTests {
-    @Test("Fetching a large file")
-    func testLargeFileDownload() async { /* Inherits 10s limit */ }
-
-    @Test("A fast API status check", .timeLimit(.seconds(1)))
-    func testFastAPI() async { /* Overrides suite limit, must finish in 1s */ }
-}
-```
+### Controlling Parallelism
+- **`.serialized`**: Apply this trait to a `@Test` or `@Suite` to force its contents to run serially (one at a time). Use this as a temporary measure for legacy tests that are not thread-safe or have hidden state dependencies. The goal should be to refactor them to run in parallel.
+- **`.timeLimit`**: A safety net to prevent hung tests from stalling CI. The more restrictive (shorter) duration wins when applied at both the suite and test level.
 
 ---
 
-## **8. Advanced API Cookbook**
+## **10. Advanced API Cookbook**
 
 | Feature | What it Does & How to Use It |
 |---|---|
-| **`CustomTestStringConvertible`** | Provides custom, readable descriptions for your types in test failure logs. Conform your key models to this for much clearer failure messages in Xcode and reports. |
-| **`withKnownIssue`** | Marks a test as an "Expected Failure" due to a known bug. This is better than `.disabled` because the test still compiles and runs. If the bug gets fixed and the test *passes*, `withKnownIssue` will fail, alerting you to remove it. |
-| **`.bug(_: "URL-or-ID")`** | Associates a test directly with a ticket in your issue tracker (e.g., `.bug("JIRA-123")`), adding valuable context to test reports. |
-| **`#expectAll { ... }`**| Groups multiple related assertions. All assertions inside the block are executed, and all failures are reported together, even if the first one fails. |
+| **`withKnownIssue`** | Marks a test as an **Expected Failure**. It's better than `.disabled` for known bugs. The test still runs but won't fail the suite. Crucially, if the underlying bug gets fixed and the test *passes*, `withKnownIssue` will fail, alerting you to remove it. |
+| **`CustomTestStringConvertible`** | Provides custom, readable descriptions for your types in test failure logs. Conform your key models to this protocol to make debugging much easier. |
+| **`.bug("JIRA-123")` Trait** | Associates a test directly with a ticket in your issue tracker. This adds invaluable context to test reports in Xcode and Xcode Cloud. |
+| **`Test.current`** | A static property (`Test.current`) that gives you runtime access to the current test's metadata, such as its name, tags, and source location. Useful for advanced custom logging. |
+| **`#expectAll { ... }`**| Groups multiple assertions. If any assertion inside the block fails, they are all reported together, but execution continues past the block. |
+
+---
+
+## **11. Migrating from XCTest**
+
+Swift Testing and XCTest can coexist in the same target, enabling an incremental migration.
+
+### Key Differences at a Glance
+
+| Feature | XCTest | Swift Testing |
+|---|---|---|
+| **Test Discovery** | Method name must start with `test...` | `@Test` attribute on any function or method. |
+| **Suite Type** | `class MyTests: XCTestCase` | `struct MyTests` (preferred), `class`, or `actor`. |
+| **Assertions** | `XCTAssert...()` family of functions | `#expect()` and `#require()` macros with Swift expressions. |
+| **Error Unwrapping** | `try XCTUnwrap(...)` | `try #require(...)` |
+| **Setup/Teardown**| `setUpWithError()`, `tearDownWithError()` | `init()`, `deinit` (on classes/actors) |
+| **Asynchronous Wait**| `XCTestExpectation` | `confirmation()` and `await fulfillment(of:timeout:)` |
+| **Parallelism** | Opt-in, multi-process | Opt-out, in-process via Swift Concurrency. |
+
+### What NOT to Migrate (Yet)
+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**
+
+---
+
+## **Appendix: Evergreen Testing Principles (The F.I.R.S.T. Principles)**
+
+These foundational principles are framework-agnostic, and Swift Testing is designed to make adhering to them easier than ever.
+
+| Principle | Meaning | Swift Testing Application |
+|---|---|---|
+| **Fast** | Tests must execute in milliseconds. | Lean on default parallelism. Use `.serialized` sparingly. |
+| **Isolated**| Tests must not depend on each other. | Swift Testing enforces this by creating a new suite instance for every test. Random execution order helps surface violations. |
+| **Repeatable** | A test must produce the same result every time. | Control all inputs (dates, network responses) with mocks/stubs. Reset state in `init`/`deinit`. |
+| **Self-Validating**| The test must automatically report pass or fail. | Use `#expect` and `#require`. Never rely on `print()` for validation. |
+| **Timely**| Write tests alongside the production code. | Use parameterized tests (`@Test(arguments:)`) to easily cover edge cases as you write code. |
diff --git a/swift-testing-playbook.md b/swift-testing-playbook.md
@@ -1,79 +1,87 @@
 # The Ultimate Swift Testing Playbook
 
-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.
+A hands-on guide for migrating from XCTest and mastering the full power of Swift Testing. This playbook focuses on practical patterns to make your tests more powerful, expressive, and maintainable, incorporating best practices from the official Apple WWDC 2024 sessions.
 
 ---
 
 ## **1. Migration & Tooling Baseline**
 
-Ensure your environment is set up for a smooth, gradual migration.
+Swift Testing is the new default in Xcode 16. Ensure your environment is set up for a smooth, gradual migration.
 
 | What | Why |
 |---|---|
-| **Xcode 16 & Swift 6** | Swift Testing is bundled with the latest toolchain. Older versions will not compile. |
-| **Keep XCTest Targets** | Allows for a file-by-file migration. You can run new and legacy tests side-by-side, which is crucial for CI stability. |
-| **Enable Parallel Execution**| In your Test Plan, enable "Use parallel execution" to take immediate advantage of Swift Testing's default concurrency model. |
+| **Xcode 16 & Swift 6** | Swift Testing is bundled with the latest toolchain and leverages modern Swift features like macros. |
+| **Keep XCTest Targets** | Swift Testing and XCTest tests can coexist in the same target, allowing for a file-by-file migration without disrupting CI. |
+| **Enable Parallel Execution**| In your Test Plan, ensure "Use parallel execution" is enabled. This is the default behavior for Swift Testing and is crucial for faster feedback. |
+| **SPM for Cross-Platform**| For projects supporting Linux or Windows, add the `swift-testing` package dependency in your `Package.swift`. This is not needed for Apple platforms. |
 
 ### Migration Action Items
-- [ ] 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”**.
+- [ ] Ensure all developer machines and CI runners are on **macOS 15+** and **Xcode 16+**.
+- [ ] In your primary test plan, confirm that **“Use parallel execution”** is active.
+- [ ] For any Swift packages, add `swift-testing` to your test target dependencies if you need to support non-Apple platforms.
 
 ---
 
-## **2. Expressive Assertions: `#expect` & `#require`**
+## **2. Expressive Expectations: `#expect` & `#require`**
 
-Replace the entire `XCTAssert` family with two powerful, expressive macros.
+Replace the entire `XCTAssert` family with two powerful, expressive macros that understand native Swift expressions.
 
 | Macro | Use Case & Behavior |
 |---|---|
-| **`#expect(expression)`** | **Soft Check.** Use this for most validations. If the expression fails, the issue is recorded, but the test function continues executing, allowing you to find multiple failures in a single run. |
-| **`#require(expression)`**| **Hard Check.** Use this for critical preconditions. If the expression fails or throws, the test is immediately aborted. This prevents cascading failures from a failed setup. |
+| **`#expect(expression)`** | **The Default Check.** Use for most validations. It accepts any boolean Swift expression. If it fails, the issue is recorded, but the test continues, letting you find multiple failures in a single run. |
+| **`#require(expression)`**| **The Hard Check.** Use for critical preconditions. If the expression is false or throws, the test is immediately aborted. This prevents cascading failures when a setup step fails. |
 
-### Power Move: Optional-Safe Unwrapping
+**Power of Native Expressions:** You don't need specialized assertion functions anymore. Just write normal Swift code.
+```swift
+// Instead of XCTAssertEqual, XCTAssertTrue, XCTAssertContains...
+#expect(video.duration == 180)
+#expect(tags.isEmpty)
+#expect(video.title.contains("WWDC"))
+```
 
-`#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.
+### Power Move: Optional-Safe Unwrapping
+`#require` is the modern, safer replacement for `XCTUnwrap`. It not only checks for `nil` but also unwraps the value for subsequent use.
 
 ```swift
 // 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)
+#expect(user.isLoggedIn)
 ```
 
 ### Action Items
-- [ ] 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.
+- [ ] Globally search for `XCTAssert` and replace with `#expect` for most cases.
+- [ ] Convert all `XCTUnwrap` calls to `try #require()`.
+- [ ] Use `try #require()` for any setup that, if it fails, would make the rest of the test meaningless.
 
 ---
 
 ## **3. Setup, Teardown, and State Lifecycle**
 
-Swift Testing replaces the `setUpWithError` and `tearDownWithError` methods with a more natural, type-safe lifecycle using `init()` and `deinit`.
+Swift Testing introduces a natural, type-safe lifecycle using `init()` and `deinit`, replacing `setUpWithError` and `tearDownWithError`.
 
-**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.
+**The Core Principle:** A fresh, new instance of the test suite (`struct`, `class`, or `actor`) 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. Using `struct`s is highly encouraged to leverage value semantics.
 
 | Method | Replaces... | Behavior |
 |---|---|---|
-| `init()` | `setUpWithError()` | The initializer for your suite. Put all setup code here: create the System Under Test (SUT), prepare mocks, and establish the initial state. |
-| `deinit` | `tearDownWithError()` | The deinitializer for your suite. Put all cleanup code here, such as deleting temporary files or invalidating resources. It runs automatically after each test completes. |
+| `init()` | `setUpWithError()` | The initializer for your suite. This is where you create the System Under Test (SUT), prepare mocks, and establish initial state. It runs before **each** test. |
+| `deinit` | `tearDownWithError()` | The deinitializer for your suite. This is for cleanup code, like deleting temporary files. It runs automatically after each test completes. (Requires using a `class` or `actor`.) |
 
 ### Practical Example: A Database Test Suite
 
 ```swift
 @Suite struct DatabaseServiceTests {
+    // Properties are re-initialized for every test function.
     let sut: DatabaseService
     let tempDirectory: URL
 
-    init() {
+    init() throws {
         // ARRANGE: Runs before EACH test in this suite.
         self.tempDirectory = FileManager.default.temporaryDirectory.appendingPathComponent(UUID().uuidString)
-        try! FileManager.default.createDirectory(at: tempDirectory, withIntermediateDirectories: true)
+        try FileManager.default.createDirectory(at: tempDirectory, withIntermediateDirectories: true)
 
         let testDatabase = TestDatabase(storageURL: tempDirectory)
         self.sut = DatabaseService(database: testDatabase)
@@ -91,118 +99,135 @@ Swift Testing replaces the `setUpWithError` and `tearDownWithError` methods with
     }
 
     @Test func testDeletingUser() throws {
-        // A completely separate, clean instance of the suite runs for this test.
+        // This test runs with a completely separate, clean instance of DatabaseServiceTests.
+        // The tempDirectory will be different and won't conflict with testSavingUser.
     }
 }
 ```
 
-### Migration Action Items
-- [ ] Convert test classes inheriting from `XCTestCase` to `struct`s or `final class`es.
-- [ ] 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()`.
-
 ---
 
 ## **4. Mastering Error Handling**
 
-Go beyond simple `do/catch` blocks with a dedicated, expressive API for error validation.
+Go beyond simple `do/catch` with a dedicated, expressive API for validating thrown errors.
 
-| Overload | Replaces... | Example & Use Case |
+| `#expect` Overload | Replaces... | Example & Use Case |
 |---|---|---|
-| **`#expect(throws: Error.self)`**| Basic `XCTAssertThrowsError` | Verifies that *any* error was thrown. |
-| **`#expect(throws: BrewingError.self)`** | Typed `XCTAssertThrowsError` | Ensures an error of a specific *type* is thrown. |
-| **`#expect(throws: BrewingError.outOfBeans)`**| Specific Error `XCTAssertThrowsError`| Validates a specific error value is thrown. |
-| **`#expect(throws: Never.self)`** | `XCTAssertNoThrow` | Explicitly asserts that a function does *not* throw. |
-| **`#require(throws:)`** | Critical `XCTAssertThrowsError` | A hard check that halts the test if the expected error is *not* thrown. |
+| **`throws: Error.self`**| Basic `XCTAssertThrowsError` | Verifies that *any* error was thrown. |
+| **`throws: BrewingError.self`** | Typed `XCTAssertThrowsError` | Ensures an error of a specific *type* is thrown. Fails if a different error type is thrown. |
+| **`throws: BrewingError.outOfBeans`**| Specific Error `XCTAssertThrowsError`| Validates a specific error *value* is thrown. |
+| **`throws: Never.self`** | `XCTAssertNoThrow` | Explicitly asserts that a function completes successfully and does *not* throw. |
+| **`performing:throws:`** | Manual `do/catch` with pattern matching | **Deep Error Inspection.** Lets you provide a closure to inspect the thrown error, perfect for validating associated values. <br> ```swift #expect( performing: { try brew(beans: 0) }, throws: { (error: BrewingError) in guard case let .notEnoughBeans(needed) = error else { return false } return needed > 0 } ) ``` |
 
 ---
 
-## **5. Parameterized Tests: Kill the Copy-Paste**
+## **5. Parameterized Tests: Eradicate Boilerplate**
 
-Drastically reduce boilerplate by running a single test function with multiple argument sets.
+Run a single test function with multiple argument sets to drastically reduce repetitive code and increase coverage.
 
 | Pattern | How to Use It |
 |---|---|
-| **Basic Arguments** | `@Test(arguments: [0, 100, -40])` Pass a simple collection. Each element is a separate test case. |
-| **Zipped Collections** | `@Test(arguments: zip(inputs, expected))` Use `zip` to pair inputs and outputs for validation, avoiding a combinatorial explosion. This is the most common pattern. |
-| **Multiple Collections** | `@Test(arguments: ["USD", "EUR"],)` Creates a test case for every possible combination (Cartesian Product). |
+| **Basic Arguments** | `@Test(arguments: [0, 100, -40])` Pass a simple collection. Swift Testing runs a separate test case for each element. |
+| **Zipped Collections** | `@Test(arguments: zip(inputs, expectedOutputs))` **The most common pattern.** Use `zip` to pair inputs with their expected outputs, avoiding a combinatorial explosion. |
+| **Multiple Collections** | `@Test(arguments: ["USD", "EUR"], [1, 100])` Creates a test case for every possible combination (Cartesian Product). Use with caution, as this can lead to an exponential number of tests. |
+
+### Example: From Repetitive to Parameterized
+```swift
+// Before: Repetitive and hard to maintain
+@Test func testVanillaContainsNoNuts() { #expect(Flavor.vanilla.containsNuts == false) }
+@Test func testChocolateContainsNoNuts() { #expect(Flavor.chocolate.containsNuts == false) }
+@Test func testPistachioContainsNuts() { #expect(Flavor.pistachio.containsNuts == true) }
+
+// After: Clean, scalable, and easy to read
+@Test(arguments: [
+    (flavor: .vanilla, expected: false),
+    (flavor: .chocolate, expected: false),
+    (flavor: .pistachio, expected: true)
+])
+func testFlavorNutContent(pair: (flavor: Flavor, expected: Bool)) {
+    #expect(pair.flavor.containsNuts == pair.expected)
+}
+```
 
 ---
 
 ## **6. Structure and Organization at Scale**
 
-Use suites and tags to manage large and complex test bases.
+Use suites and tags to manage large, complex test bases and gain valuable insights.
 
 ### Suites and Nested Suites
-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.
+A `@Suite` groups related tests. They can be nested for a clear structural hierarchy. Traits applied to a suite are inherited by all contained tests and sub-suites.
 ```swift
 @Suite("API Services", .tags(.network))
 struct APITests {
     @Suite("Authentication")
     struct AuthTests { /* ... */ }
+
+    @Suite("User Profile")
+    struct ProfileTests { /* ... */ }
 }
 ```
 
 ### Tags for Cross-Cutting Concerns
-Tags associate tests that share common characteristics, regardless of their suite.
+Tags associate tests with shared characteristics, regardless of their file or suite. This is incredibly powerful for filtering and analysis.
+
 1.  **Define Tags in a Central File:**
     ```swift
     // /Tests/Support/TestTags.swift
     import Testing
     extension Tag {
-        @Tag static var fast: Self
+        @Tag static var network: Self
         @Tag static var regression: Self
+        @Tag static var spicy: Self // As seen on TV
     }
     ```
 2.  **Apply Tags & Filter:**
     ```swift
-    @Test("Username validation", .tags(.fast, .regression)) // Apply
-    // swift test --filter-tag fast // Run from CLI
+    @Test("Username validation", .tags(.regression)) // Apply the tag
+    // CLI: swift test --filter-tag regression
+    // Xcode: Use the Test Navigator filter bar
     ```
+3.  **Leverage Tags in Xcode:**
+    *   **Test Navigator:** Filter tests by tag or switch to the **"Group by Tag"** view.
+    *   **Test Plans:** The editor lets you include or exclude tests based on tags (e.g., "Run all tests *except* those with the `unreleased` tag").
+    *   **Test Reports:** The "Insights" tab can automatically detect patterns, like **"All 5 tests with tag 'spicy' failed,"** pointing you directly to a systemic issue.
 
 ---
 
 ## **7. Concurrency and Asynchronous Testing**
 
-### Async Tests
-Simply mark your test function `async` and use `await`.
-```swift
-@Test("User profile downloads correctly")
-async func testProfileDownload() async throws { /* ... */ }
-```
+Swift Testing is built for the concurrent world.
+
+### Parallel By Default
+Tests run in parallel out-of-the-box, even on physical devices. The execution order is randomized to help surface hidden dependencies between tests (a common source of flakiness).
+
+### Opting Out with `.serialized`
+If a test suite is not yet thread-safe, apply the `.serialized` trait to force its tests to run one at a time. This should be a temporary measure while you refactor tests to be isolated.
 
 ### Confirmations for Multiple Callbacks
-To test APIs that fire multiple times (like streams or event handlers), use `confirmation`.
+For APIs that fire a callback multiple times (like streams or event handlers), use `confirmation` to validate how many times it was called.
 ```swift
 @Test("Data stream sends three packets")
 async func testDataStream() async {
     let streamFinished = confirmation("Stream sent 3 packets", expectedCount: 3)
-    // ...
+    let myStream = MyDataStream { await streamFinished() }
+    myStream.start()
+
+    // The test will wait for the confirmation to be fulfilled 3 times.
 }
 ```
 
-### Controlling Parallelism with `.serialized`
-Apply the `.serialized` trait to any `@Test` or `@Suite` to opt out of concurrent execution for tests that are not thread-safe.
-
-### Preventing Runaway Tests with Time Limits
-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)`).
+### Preventing Runaway Tests with `.timeLimit`
+The `.timeLimit` trait is a safety net to prevent hung tests from stalling your CI pipeline. If a test exceeds the limit, it fails immediately. When applied to both a suite and a test, the **more restrictive (shorter) duration wins**.
 
 ```swift
-// Suite-level timeout of 10 seconds for all network tests
-@Suite("Network Fetcher", .timeLimit(.seconds(10)))
+@Suite(.timeLimit(.seconds(10)))
 struct NetworkFetcherTests {
+    @Test("Fetching a large file")
+    func testLargeFileDownload() async { /* Inherits 10s limit */ }
 
-    @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 { /* ... */ }
+    func testFastAPI() async { /* Overrides suite limit, must finish in 1s */ }
 }
 ```
 
@@ -212,119 +237,7 @@ struct NetworkFetcherTests {
 
 | Feature | What it Does & How to Use It |
 |---|---|
-| **`CustomTestStringConvertible`** | Provides custom, readable descriptions for your types in test failure logs. Conform your key models to this to make debugging easier. |
-| **`withKnownIssue`** | Marks a test as an "Expected Failure" due to a known bug. The test runs but won't fail the suite. If the bug gets fixed and the test passes, `withKnownIssue` will fail, alerting you to remove it. |
-| **`.bug("JIRA-123")` Trait** | Associates a test directly with a ticket in your issue tracker, adding valuable context to test reports. |
-| **`#expectAll { ... }`**| Groups multiple assertions. If any assertion inside the block fails, they are all reported together, but execution continues past the block. |
-
----
-
-## **9. CI and Command-Line Recipes**
-
-*   **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.
-
-***
-
-### Memory-Safety Patterns
-
-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.
-
-| XCTest Pattern | Swift Testing Equivalent & Explanation |
-| :--- | :--- |
-| `addTeardownBlock { [weak obj] … }` | **Use `deinit` to assert on weak references.** Because a new suite instance is created for each test and deinitialized afterward, you can place memory checks directly in `deinit`. This is cleaner and more idiomatic. <br><br> ```swift @Suite struct MyViewControllerTests { var strongVC: MyViewController? init() { self.strongVC = MyViewController() } deinit { // This runs after the test, once the suite instance is discarded. #expect(self.strongVC == nil, "MyViewController should have been deallocated.") } @Test func testVCLifecycle() { // The test can hold a weak reference to the object. weak var weakVC = strongVC #expect(weakVC != nil) // `strongVC` is released when the suite deinitializes. } } ``` |
-| `expectation.isInverted = true` | **Use a `confirmation` with an expected count of 0.** An inverted expectation in XCTest was used to assert something *didn't* happen. The modern equivalent is to create a `confirmation` that is expected to be fulfilled zero times. <br><br> ```swift @Test("Delegate method should not be called") async func testDelegateNotCalled() { let confirmation = confirmation("delegate.didFail was not called", expectedCount: 0) let delegate = MockDelegate(onFail: { await confirmation() }) let sut = SystemUnderTest(delegate: delegate) sut.performSuccessfulOperation() // Await a short duration to allow for any potential async calls. try? await Task.sleep(for: .milliseconds(100)) } ``` |
-
----
-
-### `#expect` Power-Moves
-
-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.
-
-| Overload & Example | Replaces... | Handy For... |
-| :--- | :--- | :--- |
-| **`#expect(throws: SomeError.self)`** | `XCTAssertThrowsError` | Validating error paths concisely. The test passes only if the specified error type is thrown. |
-| **`#expect(throws: Never.self)`** | `XCTAssertNoThrow` | Asserting that an operation successfully completes without any errors. This is ideal for "happy path" tests. |
-| **`#expect(performing:throws:)`** | Manual `do/catch` with pattern matching | **Error Payload Introspection.** This overload lets you provide a secondary closure to inspect the properties of a thrown error, which is perfect for validating errors with associated values. <br><br> ```swift #expect(performing: { try brewCoffee(with: .notEnoughBeans(needed: 10)) }, throws: { (error: BrewingError) in guard case let .notEnoughBeans(needed) = error else { return false } return needed == 10 }) ``` |
-| **`#expectAll { ... }`** | Multiple, separate `#expect` calls or a `for` loop of assertions. | **Grouping Failures.** When you need to run several assertions that are logically connected, wrapping them in `#expectAll` ensures that all assertions are executed, and all failures are reported together, even if the first one fails. <br><br> ```swift #expectAll { #expect(user.name == "Alex") #expect(user.age == 37) #expect(user.isPremium == true) } ``` |
-
----
-
-### Conditional Skips & Execution
-
-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.
-
-| Trait | What It Does & How to Use It |
-| :--- | :--- |
-| **`.disabled("Reason")`** | **Unconditionally skips a test.** The test will not run, and will be marked as "Skipped" in the test report. Always provide a descriptive reason. <br><br> ```swift @Test(.disabled("Flaky on CI, see FB12345")) func testFlakyFeature() { /* ... */ } ``` |
-| **`.enabled(if: condition)`** | **Conditionally runs a test.** This is the most powerful option for dynamic test execution. The test only runs if the boolean `condition` is `true`. This is perfect for tests related to feature flags. <br><br> ```swift struct FeatureFlags { static var isNewPaymentsAPIEnabled: Bool { // Logic to check remote config, etc. return ProcessInfo.processInfo.environment["PAYMENTS_ENABLED"] == "1" } } @Test(.enabled(if: FeatureFlags.isNewPaymentsAPIEnabled)) func testNewPaymentsAPI() { /* This test only runs if the flag is enabled. */ } ``` |
-
----
-
-### Specialised Assertions for Clearer Failures
-
-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*.
-
-| Assertion Type | Why It's Better Than a Generic Check |
-| :--- | :--- |
-| **Comparing Collections**<br>Use `#expect(collection:unorderedEquals:)` | A simple `==` check on arrays will fail if the elements are the same but the order is different. This specialized assertion checks for equality while ignoring order, preventing false negatives for tests where order doesn't matter. <br><br> **Generic (Brittle):** `#expect(tags == ["ios", "swift"])` <br> **Specialized (Robust):** `#expect(collection: tags, unorderedEquals: ["swift", "ios"])` |
-| **Comparing Results**<br>Use `#expect(result:equals:)` | When testing a `Result` type, a generic check might just tell you that two `Result` instances are not equal. This specialized assertion provides specific diagnostics for whether the failure was in the `.success` or `.failure` case, and exactly how the payloads differed. |
-| **Floating-Point Accuracy**<br>Use `accuracy:` overloads (via Swift Numerics or custom helpers) | Floating-point math is inherently imprecise. `#expect(0.1 + 0.2 == 0.3)` will fail. Specialized assertions allow you to specify a tolerance, ensuring tests are robust against minor floating-point inaccuracies. <br><br> **Generic (Fails):** `#expect(result == 0.3)` <br> **Specialized (Passes):** `#expect(result.isApproximatelyEqual(to: 0.3, absoluteTolerance: 0.0001))` |
-
-
-
-
-## **Appendix: Evergreen Testing Principles**
-
-These foundational principles pre-date Swift Testing but are 100% applicable. The framework is designed to make adhering to them easier than ever.
-
-### The F.I.R.S.T. Principles
-
-| Principle | Meaning | Swift Testing Application |
-|---|---|---|
-| **Fast** | Tests must execute in milliseconds. | Lean on default parallelism. Use `.serialized` sparingly and only on suites that absolutely require it. |
-| **Isolated**| Tests must not depend on each other or external state. | Swift Testing enforces this by creating a new suite instance for every test. Use dependency injection and test doubles to replace external dependencies. |
-| **Repeatable** | A test must produce the same result every time. | Control all inputs, such as dates and network responses, with mocks and stubs. Reset state in `deinit`. |
-| **Self-Validating**| The test must automatically report pass or fail without human inspection. | Use `#expect` and `#require`. Never rely on `print()` statements for validation. |
-| **Timely**| Write tests just before or alongside the production code they verify. | Embrace parameterized tests (`@Test(arguments:)`) to reduce the friction of writing comprehensive test cases. |
-
-### Core Tenets of Great Tests
-
-*   **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>”`.
-    ```swift
-    @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.
-    ```swift
-    #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:**
-    ```swift
-    let adminAccessLevel = 3
-    #expect(user.accessLevel == adminAccessLevel)
-    ```
+| **`CustomTestStringConvertible`** | Provides custom, readable descriptions for your types in test failure logs. Conform your key models to this for much clearer failure messages in Xcode and reports. |
+| **`withKnownIssue`** | Marks a test as an "Expected Failure" due to a known bug. This is better than `.disabled` because the test still compiles and runs. If the bug gets fixed and the test *passes*, `withKnownIssue` will fail, alerting you to remove it. |
+| **`.bug(_: "URL-or-ID")`** | Associates a test directly with a ticket in your issue tracker (e.g., `.bug("JIRA-123")`), adding valuable context to test reports. |
+| **`#expectAll { ... }`**| Groups multiple related assertions. All assertions inside the block are executed, and all failures are reported together, even if the first one fails. |
diff --git a/swift-testing-playbook.md b/swift-testing-playbook.md
@@ -1,4 +1,4 @@
-# The Ultimate Swift Testing Playbook (Extended Edition)
+# The Ultimate Swift Testing Playbook
 
 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.
 

diff --git a/swift-testing-playbook.md b/swift-testing-playbook.md
@@ -1,7 +1,3 @@
-Of course. I will expand the playbook with the requested sections and add more depth to existing topics, particularly `.timeLimit`. This version integrates a dedicated section on the test instance lifecycle, setup, and teardown, providing a more complete and practical guide for migrating to and mastering Swift Testing.
-
-***
-
 # The Ultimate Swift Testing Playbook (Extended Edition)
 
 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.

diff --git a/swift-testing-playbook.md b/swift-testing-playbook.md
@@ -0,0 +1,334 @@
+Of course. I will expand the playbook with the requested sections and add more depth to existing topics, particularly `.timeLimit`. This version integrates a dedicated section on the test instance lifecycle, setup, and teardown, providing a more complete and practical guide for migrating to and mastering Swift Testing.
+
+***
+
+# The Ultimate Swift Testing Playbook (Extended Edition)
+
+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.
+
+---
+
+## **1. Migration & Tooling Baseline**
+
+Ensure your environment is set up for a smooth, gradual migration.
+
+| What | Why |
+|---|---|
+| **Xcode 16 & Swift 6** | Swift Testing is bundled with the latest toolchain. Older versions will not compile. |
+| **Keep XCTest Targets** | Allows for a file-by-file migration. You can run new and legacy tests side-by-side, which is crucial for CI stability. |
+| **Enable Parallel Execution**| In your Test Plan, enable "Use parallel execution" to take immediate advantage of Swift Testing's default concurrency model. |
+
+### Migration Action Items
+- [ ] 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”**.
+
+---
+
+## **2. Expressive Assertions: `#expect` & `#require`**
+
+Replace the entire `XCTAssert` family with two powerful, expressive macros.
+
+| Macro | Use Case & Behavior |
+|---|---|
+| **`#expect(expression)`** | **Soft Check.** Use this for most validations. If the expression fails, the issue is recorded, but the test function continues executing, allowing you to find multiple failures in a single run. |
+| **`#require(expression)`**| **Hard Check.** Use this for critical preconditions. If the expression fails or throws, the test is immediately aborted. This prevents cascading failures from a failed setup. |
+
+### Power Move: Optional-Safe Unwrapping
+
+`#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.
+
+```swift
+// 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)
+```
+
+### Action Items
+- [ ] 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.
+
+---
+
+## **3. Setup, Teardown, and State Lifecycle**
+
+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.
+
+| Method | Replaces... | Behavior |
+|---|---|---|
+| `init()` | `setUpWithError()` | The initializer for your suite. Put all setup code here: create the System Under Test (SUT), prepare mocks, and establish the initial state. |
+| `deinit` | `tearDownWithError()` | The deinitializer for your suite. Put all cleanup code here, such as deleting temporary files or invalidating resources. It runs automatically after each test completes. |
+
+### Practical Example: A Database Test Suite
+
+```swift
+@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.
+    }
+}
+```
+
+### Migration Action Items
+- [ ] Convert test classes inheriting from `XCTestCase` to `struct`s or `final class`es.
+- [ ] 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()`.
+
+---
+
+## **4. Mastering Error Handling**
+
+Go beyond simple `do/catch` blocks with a dedicated, expressive API for error validation.
+
+| Overload | Replaces... | Example & Use Case |
+|---|---|---|
+| **`#expect(throws: Error.self)`**| Basic `XCTAssertThrowsError` | Verifies that *any* error was thrown. |
+| **`#expect(throws: BrewingError.self)`** | Typed `XCTAssertThrowsError` | Ensures an error of a specific *type* is thrown. |
+| **`#expect(throws: BrewingError.outOfBeans)`**| Specific Error `XCTAssertThrowsError`| Validates a specific error value is thrown. |
+| **`#expect(throws: Never.self)`** | `XCTAssertNoThrow` | Explicitly asserts that a function does *not* throw. |
+| **`#require(throws:)`** | Critical `XCTAssertThrowsError` | A hard check that halts the test if the expected error is *not* thrown. |
+
+---
+
+## **5. Parameterized Tests: Kill the Copy-Paste**
+
+Drastically reduce boilerplate by running a single test function with multiple argument sets.
+
+| Pattern | How to Use It |
+|---|---|
+| **Basic Arguments** | `@Test(arguments: [0, 100, -40])` Pass a simple collection. Each element is a separate test case. |
+| **Zipped Collections** | `@Test(arguments: zip(inputs, expected))` Use `zip` to pair inputs and outputs for validation, avoiding a combinatorial explosion. This is the most common pattern. |
+| **Multiple Collections** | `@Test(arguments: ["USD", "EUR"],)` Creates a test case for every possible combination (Cartesian Product). |
+
+---
+
+## **6. Structure and Organization at Scale**
+
+Use suites and tags to manage large and complex test bases.
+
+### Suites and Nested Suites
+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.
+```swift
+@Suite("API Services", .tags(.network))
+struct APITests {
+    @Suite("Authentication")
+    struct AuthTests { /* ... */ }
+}
+```
+
+### Tags for Cross-Cutting Concerns
+Tags associate tests that share common characteristics, regardless of their suite.
+1.  **Define Tags in a Central File:**
+    ```swift
+    // /Tests/Support/TestTags.swift
+    import Testing
+    extension Tag {
+        @Tag static var fast: Self
+        @Tag static var regression: Self
+    }
+    ```
+2.  **Apply Tags & Filter:**
+    ```swift
+    @Test("Username validation", .tags(.fast, .regression)) // Apply
+    // swift test --filter-tag fast // Run from CLI
+    ```
+
+---
+
+## **7. Concurrency and Asynchronous Testing**
+
+### Async Tests
+Simply mark your test function `async` and use `await`.
+```swift
+@Test("User profile downloads correctly")
+async func testProfileDownload() async throws { /* ... */ }
+```
+
+### Confirmations for Multiple Callbacks
+To test APIs that fire multiple times (like streams or event handlers), use `confirmation`.
+```swift
+@Test("Data stream sends three packets")
+async func testDataStream() async {
+    let streamFinished = confirmation("Stream sent 3 packets", expectedCount: 3)
+    // ...
+}
+```
+
+### Controlling Parallelism with `.serialized`
+Apply the `.serialized` trait to any `@Test` or `@Suite` to opt out of concurrent execution for tests that are not thread-safe.
+
+### Preventing Runaway Tests with Time Limits
+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)`).
+
+```swift
+// 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 { /* ... */ }
+}
+```
+
+---
+
+## **8. Advanced API Cookbook**
+
+| Feature | What it Does & How to Use It |
+|---|---|
+| **`CustomTestStringConvertible`** | Provides custom, readable descriptions for your types in test failure logs. Conform your key models to this to make debugging easier. |
+| **`withKnownIssue`** | Marks a test as an "Expected Failure" due to a known bug. The test runs but won't fail the suite. If the bug gets fixed and the test passes, `withKnownIssue` will fail, alerting you to remove it. |
+| **`.bug("JIRA-123")` Trait** | Associates a test directly with a ticket in your issue tracker, adding valuable context to test reports. |
+| **`#expectAll { ... }`**| Groups multiple assertions. If any assertion inside the block fails, they are all reported together, but execution continues past the block. |
+
+---
+
+## **9. CI and Command-Line Recipes**
+
+*   **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.
+
+***
+
+### Memory-Safety Patterns
+
+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.
+
+| XCTest Pattern | Swift Testing Equivalent & Explanation |
+| :--- | :--- |
+| `addTeardownBlock { [weak obj] … }` | **Use `deinit` to assert on weak references.** Because a new suite instance is created for each test and deinitialized afterward, you can place memory checks directly in `deinit`. This is cleaner and more idiomatic. <br><br> ```swift @Suite struct MyViewControllerTests { var strongVC: MyViewController? init() { self.strongVC = MyViewController() } deinit { // This runs after the test, once the suite instance is discarded. #expect(self.strongVC == nil, "MyViewController should have been deallocated.") } @Test func testVCLifecycle() { // The test can hold a weak reference to the object. weak var weakVC = strongVC #expect(weakVC != nil) // `strongVC` is released when the suite deinitializes. } } ``` |
+| `expectation.isInverted = true` | **Use a `confirmation` with an expected count of 0.** An inverted expectation in XCTest was used to assert something *didn't* happen. The modern equivalent is to create a `confirmation` that is expected to be fulfilled zero times. <br><br> ```swift @Test("Delegate method should not be called") async func testDelegateNotCalled() { let confirmation = confirmation("delegate.didFail was not called", expectedCount: 0) let delegate = MockDelegate(onFail: { await confirmation() }) let sut = SystemUnderTest(delegate: delegate) sut.performSuccessfulOperation() // Await a short duration to allow for any potential async calls. try? await Task.sleep(for: .milliseconds(100)) } ``` |
+
+---
+
+### `#expect` Power-Moves
+
+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.
+
+| Overload & Example | Replaces... | Handy For... |
+| :--- | :--- | :--- |
+| **`#expect(throws: SomeError.self)`** | `XCTAssertThrowsError` | Validating error paths concisely. The test passes only if the specified error type is thrown. |
+| **`#expect(throws: Never.self)`** | `XCTAssertNoThrow` | Asserting that an operation successfully completes without any errors. This is ideal for "happy path" tests. |
+| **`#expect(performing:throws:)`** | Manual `do/catch` with pattern matching | **Error Payload Introspection.** This overload lets you provide a secondary closure to inspect the properties of a thrown error, which is perfect for validating errors with associated values. <br><br> ```swift #expect(performing: { try brewCoffee(with: .notEnoughBeans(needed: 10)) }, throws: { (error: BrewingError) in guard case let .notEnoughBeans(needed) = error else { return false } return needed == 10 }) ``` |
+| **`#expectAll { ... }`** | Multiple, separate `#expect` calls or a `for` loop of assertions. | **Grouping Failures.** When you need to run several assertions that are logically connected, wrapping them in `#expectAll` ensures that all assertions are executed, and all failures are reported together, even if the first one fails. <br><br> ```swift #expectAll { #expect(user.name == "Alex") #expect(user.age == 37) #expect(user.isPremium == true) } ``` |
+
+---
+
+### Conditional Skips & Execution
+
+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.
+
+| Trait | What It Does & How to Use It |
+| :--- | :--- |
+| **`.disabled("Reason")`** | **Unconditionally skips a test.** The test will not run, and will be marked as "Skipped" in the test report. Always provide a descriptive reason. <br><br> ```swift @Test(.disabled("Flaky on CI, see FB12345")) func testFlakyFeature() { /* ... */ } ``` |
+| **`.enabled(if: condition)`** | **Conditionally runs a test.** This is the most powerful option for dynamic test execution. The test only runs if the boolean `condition` is `true`. This is perfect for tests related to feature flags. <br><br> ```swift struct FeatureFlags { static var isNewPaymentsAPIEnabled: Bool { // Logic to check remote config, etc. return ProcessInfo.processInfo.environment["PAYMENTS_ENABLED"] == "1" } } @Test(.enabled(if: FeatureFlags.isNewPaymentsAPIEnabled)) func testNewPaymentsAPI() { /* This test only runs if the flag is enabled. */ } ``` |
+
+---
+
+### Specialised Assertions for Clearer Failures
+
+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*.
+
+| Assertion Type | Why It's Better Than a Generic Check |
+| :--- | :--- |
+| **Comparing Collections**<br>Use `#expect(collection:unorderedEquals:)` | A simple `==` check on arrays will fail if the elements are the same but the order is different. This specialized assertion checks for equality while ignoring order, preventing false negatives for tests where order doesn't matter. <br><br> **Generic (Brittle):** `#expect(tags == ["ios", "swift"])` <br> **Specialized (Robust):** `#expect(collection: tags, unorderedEquals: ["swift", "ios"])` |
+| **Comparing Results**<br>Use `#expect(result:equals:)` | When testing a `Result` type, a generic check might just tell you that two `Result` instances are not equal. This specialized assertion provides specific diagnostics for whether the failure was in the `.success` or `.failure` case, and exactly how the payloads differed. |
+| **Floating-Point Accuracy**<br>Use `accuracy:` overloads (via Swift Numerics or custom helpers) | Floating-point math is inherently imprecise. `#expect(0.1 + 0.2 == 0.3)` will fail. Specialized assertions allow you to specify a tolerance, ensuring tests are robust against minor floating-point inaccuracies. <br><br> **Generic (Fails):** `#expect(result == 0.3)` <br> **Specialized (Passes):** `#expect(result.isApproximatelyEqual(to: 0.3, absoluteTolerance: 0.0001))` |
+
+
+
+
+## **Appendix: Evergreen Testing Principles**
+
+These foundational principles pre-date Swift Testing but are 100% applicable. The framework is designed to make adhering to them easier than ever.
+
+### The F.I.R.S.T. Principles
+
+| Principle | Meaning | Swift Testing Application |
+|---|---|---|
+| **Fast** | Tests must execute in milliseconds. | Lean on default parallelism. Use `.serialized` sparingly and only on suites that absolutely require it. |
+| **Isolated**| Tests must not depend on each other or external state. | Swift Testing enforces this by creating a new suite instance for every test. Use dependency injection and test doubles to replace external dependencies. |
+| **Repeatable** | A test must produce the same result every time. | Control all inputs, such as dates and network responses, with mocks and stubs. Reset state in `deinit`. |
+| **Self-Validating**| The test must automatically report pass or fail without human inspection. | Use `#expect` and `#require`. Never rely on `print()` statements for validation. |
+| **Timely**| Write tests just before or alongside the production code they verify. | Embrace parameterized tests (`@Test(arguments:)`) to reduce the friction of writing comprehensive test cases. |
+
+### Core Tenets of Great Tests
+
+*   **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>”`.
+    ```swift
+    @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.
+    ```swift
+    #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:**
+    ```swift
+    let adminAccessLevel = 3
+    #expect(user.accessLevel == adminAccessLevel)
+    ```