Swift Testing Framework: Basics

Guidance for starting with Swift Testing (Testing framework) and writing clear, macro-driven tests.

Core Concepts

• Import Testing to unlock macros; tests are plain functions annotated with @Test .

• Name tests freely; use @Test("Display Name") to set the navigator title.

• #expect is the primary assertion; pass a boolean expression to assert truthy outcomes.

• Async/throwing tests are supported via async /throws on the test function.

• Works alongside XCTest in the same project.

Example: Simple Test

import Testing

func add(_ a: Int, _ b: Int) -> Int { a + b }

@Test("Verify addition function") func verifyAdd() { let result = add(1, 2) #expect(result == 3) }

Expecting Throws

Use #expect(throws:) to verify a thrown error. Inspect the error via the closure overload when you need to assert the specific case.

@Test func verifyThrowingFunction() { #expect(throws: MyError.self) { try throwingFunction() }

#expect {
    try throwingFunction()
} throws: { error in
    guard let myError = error as? MyError else { return false }
    return myError == .invalidInput
}

}

Require vs Expect

• #require throws immediately when the condition is false, halting the test early.

• Handy for unwrapping optionals before continuing with more assertions.

@Test func verifyOptionalFunc() throws { let result = try #require(optionalFunc()) // unwrap or fail fast #expect(result > 0) }

Recording Issues

Use Issue.record("message") to log and exit gracefully when continuing the test is pointless.

@Test func verifyOptionalFunc() throws { guard let result = optionalFunc() else { Issue.record("optional result is nil") return } #expect(result > 0) }

Best Practices Checklist

• Prefer @Test -annotated free functions; no need for XCTest naming conventions.

• Use @Test("Name") to keep navigator titles readable.

• Default to #expect for assertions; add multiple expects per test when logical.

• Use #require to guard preconditions/unwrap optionals before further checks.

• Assert thrown errors with #expect(throws:) , including specific case checks.

• Mix Swift Testing with XCTest during migration; convert incrementally.

• Keep tests small and focused; one behavior per test function.