Swift Testing

Swift Testing

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

Contents

• Basic Tests
• `@Test Traits`
• #expect and #require
• `@Suite and Test Organization`
• Execution Model
• XCTest Migration Boundaries
• Known Issues
• Additional Patterns
• Common Mistakes
• Test Attachments
• Exit Testing
• Version-Gated APIs
• Advanced API Review Checklist
• Review Checklist
• References

---

Basic Tests

import Testing

@Test("User can update their display name")
func updateDisplayName() {
    var user = User(name: "Alice")
    user.name = "Bob"
    #expect(user.name == "Bob")
}

@Test Traits

@Test("Validates email format")                                    // display name
@Test(.tags(.validation, .email))                                  // tags
@Test(.disabled("Server migration in progress"))                   // disabled
@Test(.enabled(if: ProcessInfo.processInfo.environment["CI"] != nil)) // conditional
@Test(.bug("https://github.com/org/repo/issues/42"))               // bug reference
@Test(.timeLimit(.minutes(1)))                                     // time limit
@Test("Timeout handling", .tags(.networking), .timeLimit(.seconds(30))) // combined

#expect and #require

// #expect records failure but continues execution
#expect(result == 42)
#expect(name.isEmpty == false)
#expect(items.count > 0, "Items should not be empty")

// #expect with error type checking
#expect(throws: ValidationError.self) {
    try validate(email: "not-an-email")
}

// #expect with specific error value
#expect {
    try validate(email: "")
} throws: { error in
    guard let err = error as? ValidationError else { return false }
    return err == .empty
}

// #require records failure AND stops test (like XCTUnwrap)
let user = try #require(await fetchUser(id: 1))
#expect(user.name == "Alice")

// #require for optionals -- unwraps or fails
let first = try #require(items.first)
#expect(first.isValid)

Rule: Use `#require` when subsequent assertions depend on the value. Use `#expect` for independent checks.

@Suite and Test Organization

See references/testing-patterns.md for suite organization, confirmation patterns, known-issue handling, and execution-model details.

Execution Model

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

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

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

Rules:

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

XCTest Migration Boundaries

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

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

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

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

Migration defaults:

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

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

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

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

Known Issues

Mark expected failures so they do not cause test failure:

withKnownIssue("Propane tank is empty") {
    #expect(truck.grill.isHeating)
}

// Intermittent / flaky failures
withKnownIssue(isIntermittent: true) {
    #expect(service.isReachable)
}

// Conditional known issue
withKnownIssue {
    #expect(foodTruck.grill.isHeating)
} when: {
    !hasPropane
}

If no known issues are recorded, Swift Testing records a distinct issue notifying you the problem may be resolved.

Additional Patterns

See references/testing-patterns.md for parameterized tests, tags and suites, async testing, traits, and execution-model details.

Test Attachments

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

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

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

import Testing
import UIKit

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

Exit Testing

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

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

Version-Gated APIs

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

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

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

Advanced API Review Checklist

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

Common Mistakes

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

Review Checklist

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

References

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

Advanced Testing Patterns

Warning-severity issues, programmatic test cancellation, and image attachments for Swift Testing.

Contents

• Warning-Severity Issues
• Programmatic Test Cancellation
• Exit Test Value Capturing
• Image Attachments
• Version Gates
• Proposal Reference

Warning-Severity Issues

ST-0013 adds a severity parameter to Issue.record() in Swift 6.3 / Xcode 26.4 and newer. Warnings are surfaced in test output but do not cause the test to fail.

@Test func dataIntegrity() {
    let result = loadData()

    // Hard failure — test fails
    #expect(result.isValid)

    // Warning — logged but test still passes
    if result.processingTime > 2.0 {
        Issue.record(
            "Processing took \(result.processingTime)s — exceeds 2s target",
            severity: .warning
        )
    }
}

Use warnings for:

• Performance regressions that aren't blocking
• Deprecated code paths that still work
• Non-critical data quality checks
• Flaky conditions you want to track without failing CI

Programmatic Test Cancellation

ST-0016 adds try Test.cancel() in Swift 6.3 / Xcode 26.4 and newer to stop a test from within without marking it as passed or failed. The test is recorded as "cancelled."

@Test func requiresNetwork() async throws {
    guard NetworkMonitor.shared.isConnected else {
        try Test.cancel("No network — skipping integration test")
    }

    let response = try await APIClient.shared.healthCheck()
    #expect(response.status == .ok)
}

Key differences from other mechanisms:

• Throwing an error — marks the test as failed
• withKnownIssue — marks a failure as expected (test still runs)
• try Test.cancel() — marks the test as cancelled (neutral outcome, test stops)

Exit Test Value Capturing

ST-0012 allows exit tests to capture values from the enclosing scope when using the Swift 6.3 compiler. Exit testing itself requires Swift 6.2 / Xcode 26.0 or newer and uses the processExitsWith: macros.

When an exit-test body reads values from the parent process, correct the sample to use an explicit capture list and mention the Swift 6.3 compiler requirement. Captured values must conform to Sendable and Codable.

@Test func exitCodeValidation() async {
    let expectedCode: Int32 = 42
    await #expect(processExitsWith: .failure) { [expectedCode] in
        exit(expectedCode)  // Can now capture `expectedCode`
    }
}

Image Attachments

ST-0014 adds image attachments in Swift 6.3 / Xcode 26.4 and newer. Import both Testing and the relevant UI framework, then record platform image values directly and specify as: when you need an explicit format.

import Testing
import UIKit

@Test func renderedOutput() async throws {
    let view = ChartView(data: sampleData)
    let renderer = UIGraphicsImageRenderer(size: CGSize(width: 400, height: 300))
    let image = renderer.image { ctx in
        view.drawHierarchy(in: view.bounds, afterScreenUpdates: true)
    }

    // Attach UIImage directly
    Attachment.record(image, named: "chart-output", as: .png)
}

Supported Apple-platform image types include:

• UIImage on iOS, tvOS, visionOS, and watchOS when importing UIKit
• CGImage when importing CoreGraphics
• CIImage when importing CoreImage
• NSImage on macOS when importing AppKit

Version Gates

Do not use exit tests for iOS, tvOS, or watchOS runtime targets. For iOS app code that needs fatal-path coverage, move the exit behavior behind a smaller pure Swift API, test the non-exiting branches directly, and reserve exit tests for a supported host/tool target.

Proposal Reference

Swift Testing Patterns Reference

Contents

• Basic Tests and Traits
• Expectations and Requirements
• Suite Organization
• Parameterized Tests
• Execution Model
• Confirmation and Known Issues
• Tags
• TestScoping and Test Organization
• XCTest Migration Patterns
• Mocking and Test Doubles
• Testable Architecture
• Async and Concurrent Tests
• XCTest UI Tests — Page Object Pattern
• Performance Testing
• Snapshot Testing
• Test Attachments
• Exit Testing
• Test File Organization
• What to Test
• Common Mistakes and Review Checklist

Basic Tests and Traits

import Testing

@Test("User can update their display name")
func updateDisplayName() {
    var user = User(name: "Alice")
    user.name = "Bob"
    #expect(user.name == "Bob")
}

@Test(.tags(.validation, .email))
func validatesEmailFormat() { /* ... */ }

Expectations and Requirements

#expect(result == 42)
#expect(name.isEmpty == false)
#expect(items.count > 0, "Items should not be empty")

// Error type checking
#expect(throws: ValidationError.self) {
    try validate(email: "not-an-email")
}

// Specific error matching
#expect {
    try validate(email: "")
} throws: { error in
    guard let err = error as? ValidationError else { return false }
    return err == .empty
}

// #require unwraps or fails the test
let user = try #require(await fetchUser(id: 1))
let first = try #require(items.first)

Rule: Use `#require` when subsequent assertions depend on the value. Use `#expect` for independent checks.

Suite Organization

@Suite("User Authentication")
struct AuthTests {
    let service: AuthService
    let mockRepo: MockUserRepository

    // init() replaces setUp() -- runs before each test
    init() {
        mockRepo = MockUserRepository()
        service = AuthService(repository: mockRepo)
    }

    @Test func loginSucceeds() async throws {
        let user = try await service.login(email: "test@test.com", password: "pass")
        #expect(user.email == "test@test.com")
    }

    @Test func loginFailsWithBadPassword() async {
        #expect(throws: AuthError.invalidCredentials) {
            try await service.login(email: "test@test.com", password: "wrong")
        }
    }
}

Suites can nest for logical grouping:

@Suite("Payments")
struct PaymentTests {
    @Suite("Subscriptions")
    struct SubscriptionTests {
        @Test func renewsAutomatically() { /* ... */ }
    }
    @Suite("One-Time")
    struct OneTimeTests {
        @Test func chargesCorrectAmount() { /* ... */ }
    }
}

Parameterized Tests

@Test("Email validation", arguments: [
    ("user@example.com", true),
    ("user@", false),
    ("@example.com", false),
    ("", false),
])
func validateEmail(email: String, isValid: Bool) {
    #expect(EmailValidator.isValid(email) == isValid)
}

// From CaseIterable
@Test(arguments: Currency.allCases)
func currencyHasSymbol(currency: Currency) {
    #expect(currency.symbol.isEmpty == false)
}

// Two collections: cartesian product
@Test(arguments: [1, 2, 3], ["a", "b"])
func combinations(number: Int, letter: String) {
    #expect(number > 0)
}

// Use zip for 1:1 pairing
@Test(arguments: zip(["USD", "EUR"], ["$", "€"]))
func currencySymbols(code: String, symbol: String) {
    #expect(Currency(code: code).symbol == symbol)
}

Each argument combination runs as an independent test case reported separately.

Execution Model

Swift Testing uses Swift Concurrency and runs tests in parallel by default. Treat every test as isolated work unless you explicitly serialize a scope.

@Suite(.serialized, .tags(.database))
struct DatabaseTests {
    @Test func insertsRecord() async throws { /* ... */ }
    @Test func removesRecord() async throws { /* ... */ }
}

Use .serialized when tests must not overlap because they touch shared external state like a keychain, database, singleton service, or filesystem location. It does not make unrelated tests outside the serialized scope run one-at-a-time.

Important implications:

• Each test gets its own suite instance.
• Declaration order is not a contract.
• If one logical workflow depends on previous state, keep that workflow inside one test.
• Prefer isolated fixtures over shared mutable globals.

Confirmation and Known Issues

Confirmation (Async Event Testing)

// Basic confirmation -- event must fire exactly once
await confirmation("Received notification") { confirm in
    let observer = NotificationCenter.default.addObserver(
        forName: .userLoggedIn, object: nil, queue: .main
    ) { _ in confirm() }
    await authService.login()
    NotificationCenter.default.removeObserver(observer)
}

// Expected count -- event must fire exactly N times
await confirmation("Received 3 items", expectedCount: 3) { confirm in
    processor.onItem = { _ in confirm() }
    await processor.process(items)
}

Known Issues

// Known failing test -- does not count as failure
withKnownIssue("Propane tank is empty") {
    #expect(truck.grill.isHeating)
}

// Intermittent / flaky
withKnownIssue(isIntermittent: true) {
    #expect(service.isReachable)
}

// Conditional
withKnownIssue {
    #expect(foodTruck.grill.isHeating)
} when: {
    !hasPropane
}

// Match specific issues only
try withKnownIssue {
    let level = try #require(foodTruck.batteryLevel)
    #expect(level >= 0.8)
} matching: { issue in
    guard case .expectationFailed(let expectation) = issue.kind else { return false }
    return expectation.isRequired
}

If no known issues are recorded, Swift Testing records a distinct issue notifying you the problem may be resolved.

Tags

Tags must be declared as static members in an extension on Tag:

extension Tag {
    @Tag static var critical: Self
    @Tag static var slow: Self
    @Tag static var networking: Self
    @Tag static var validation: Self
}

@Test(.tags(.critical, .networking))
func apiCallReturnsData() async throws { /* ... */ }

Filter tests by tag in Xcode test plans or CLI (tag-based filtering syntax varies by toolchain — verify for your Swift version).

TestScoping and Test Organization

TestScoping consolidates per-test setup/teardown into reusable fixtures when attached through a custom trait:

struct DatabaseScope: TestTrait, SuiteTrait, TestScoping {
    func provideScope(
        for test: Test,
        testCase: Test.Case?,
        performing body: @Sendable () async throws -> Void
    ) async throws {
        let db = try await TestDatabase.create()
        do {
            try await body()
            try await db.destroy()
        } catch {
            try? await db.destroy()
            throw error
        }
    }
}

extension Trait where Self == DatabaseScope {
    static var databaseScope: Self { .init() }
}

@Test(.databaseScope, .tags(.database))
func insertsRecord() async throws {
    // Test runs inside DatabaseScope.provideScope
}

XCTest Migration Patterns

Swift Testing tests are functions annotated with @Test; they do not need XCTestCase. Use the smallest shape that needs the fixture:

@Test func validatesTotal() {
    #expect(Cart(items: [.sample]).total == 9.99)
}

@Suite("Checkout")
struct CheckoutTests {
    let calculator = PriceCalculator()

    @Test func appliesDiscount() {
        #expect(calculator.total(discount: .percent(10)) == 8.99)
    }
}

@Suite("Shared Cache")
actor CacheTests {
    var cache = TestCache()

    @Test func storesValue() async {
        await cache.store("value", forKey: "key")
        #expect(await cache.value(forKey: "key") == "value")
    }
}

struct PureHelperTests {
    @Test static func normalizesInput() {
        #expect(normalize("  email@example.com ") == "email@example.com")
    }
}

Common XCTest mappings:

Convert setUp into isolated suite init() state. Avoid moving fixtures into singletons or shared globals; Swift Testing runs tests in parallel by default. Use actors or per-test fixtures for mutable test doubles, and use .serialized only when an external shared resource cannot be isolated.

XCTest Interoperability During Migration

XCTest and Swift Testing can coexist in the same target, bundle, and even source file during migration. Xcode 27 is the important dividing line for migration reviews: test plans created before Xcode 27 inherit the older limited behavior, while new Xcode 27 projects use complete behavior by default. Test framework interoperability controls how issues cross that boundary:

• limited: preserves the older migration behavior. Cross-framework issues from XCTest are warnings, so a Swift Testing test that reuses a helper wrapping XCTFail may still pass while showing migration warnings. Test plans created before Xcode 27 inherit this mode.
• complete: treats XCTest assertions and Swift Testing issues as test issues across both frameworks. New Xcode 27 projects use this mode by default, and it is the preferred migration default when available.
• strict: like complete, but cross-framework issues from XCTest are fatal so teams catch stale helper usage quickly.
• none: disables interop and should be reserved for projects that intentionally forbid mixed helpers.

For SwiftPM, set SWIFT_TESTING_XCTEST_INTEROP_MODE when the package needs an explicit mode. A package still declaring swift-tools-version: 6.3 can run under the Swift 6.4 toolchain with limited-mode behavior; updating the package to Swift tools version 6.4 or newer moves the default to complete-mode behavior.

Do not tell teams that all cross-framework APIs are categorically disallowed. Instead, keep existing helper code working under complete or strict while migrating toward native Swift Testing issue-reporting:

// Transitional helper body
func requireUser(_ user: User?) throws -> User {
    try #require(user, "Expected a user")
}

func recordMissingUser() {
    Issue.record("Expected a user")
}

Use native Swift Testing APIs for new Swift Testing tests. Keep UI automation, performance measurement, and Objective-C exception tests in XCTest.

Mocking and Test Doubles

Define testable boundaries with protocols:

protocol UserRepository: Sendable {
    func fetch(id: String) async throws -> User
    func save(_ user: User) async throws
}

actor MockUserRepository: UserRepository {
    var users: [String: User] = [:]
    var fetchError: (any Error)?
    private(set) var savedUsers: [User] = []

    init(users: [String: User] = [:], fetchError: (any Error)? = nil) {
        self.users = users
        self.fetchError = fetchError
    }

    func fetch(id: String) async throws -> User {
        if let error = fetchError { throw error }
        guard let user = users[id] else { throw NotFoundError() }
        return user
    }

    func save(_ user: User) async throws {
        savedUsers.append(user)
        users[user.id] = user
    }
}

Pattern: Mocks conform to protocols, never subclass concrete types. For parallel Swift Testing runs, keep mutable mock state isolated in an actor or another Sendable-safe fixture. Store call counts and arguments for verification behind that isolation boundary.

Testable Architecture

Inject dependencies through initializers for testability:

@Observable
class ProfileViewModel {
    var user: User?
    var error: Error?
    private let repository: any UserRepository

    init(repository: any UserRepository) {
        self.repository = repository
    }

    func load() async {
        do {
            user = try await repository.fetch(id: "current")
        } catch {
            self.error = error
        }
    }
}

// Test with mock
@Test @MainActor func viewModelLoadsUser() async {
    let mock = MockUserRepository(users: ["current": .preview])
    let vm = ProfileViewModel(repository: mock)
    await vm.load()
    #expect(vm.user?.name == "Alice")
}

@Test @MainActor func viewModelHandlesError() async {
    let mock = MockUserRepository(fetchError: URLError(.notConnectedToInternet))
    let vm = ProfileViewModel(repository: mock)
    await vm.load()
    #expect(vm.user == nil)
    #expect(vm.error != nil)
}

Async and Concurrent Tests

@Test @MainActor func viewModelUpdatesOnMainActor() async {
    let vm = ProfileViewModel(repository: MockUserRepository())
    await vm.load()
    #expect(vm.user != nil)
}

// Clock injection for time-dependent logic
@Test func debounceUsesCorrectDelay() async throws {
    let clock = TestClock()
    let debouncer = Debouncer(delay: .seconds(1), clock: clock)
    debouncer.submit { /* action */ }
    await clock.advance(by: .milliseconds(500))
    #expect(!debouncer.hasExecuted)
    await clock.advance(by: .milliseconds(500))
    #expect(debouncer.hasExecuted)
}

// Error path testing
@Test func fetchThrowsOnNetworkError() async {
    let mock = MockUserRepository(fetchError: URLError(.notConnectedToInternet))
    #expect(throws: URLError.self) {
        try await mock.fetch(id: "1")
    }
}

XCTest UI Tests — Page Object Pattern

Swift Testing does not support UI testing. Use XCTest with XCUITest for all UI tests.

class LoginUITests: XCTestCase {
    let app = XCUIApplication()

    override func setUpWithError() throws {
        continueAfterFailure = false
        app.launch()
    }

    func testLoginFlow() throws {
        let loginPage = LoginPage(app: app)
        let homePage = loginPage.login(email: "test@test.com", password: "password")
        XCTAssertTrue(homePage.welcomeLabel.exists)
    }
}

Page Object Pattern

Encapsulate UI element queries in page objects for reusable, readable UI tests:

struct LoginPage {
    let app: XCUIApplication
    var emailField: XCUIElement { app.textFields["Email"] }
    var passwordField: XCUIElement { app.secureTextFields["Password"] }
    var signInButton: XCUIElement { app.buttons["Sign In"] }

    @discardableResult
    func login(email: String, password: String) -> HomePage {
        emailField.tap(); emailField.typeText(email)
        passwordField.tap(); passwordField.typeText(password)
        signInButton.tap()
        return HomePage(app: app)
    }
}

struct HomePage {
    let app: XCUIApplication
    var welcomeLabel: XCUIElement { app.staticTexts["Welcome"] }
}

Performance Testing

class FeedPerformanceTests: XCTestCase {
    func testFeedParsingPerformance() throws {
        let data = try loadFixture("large-feed.json")
        let metrics: [XCTMetric] = [XCTClockMetric(), XCTMemoryMetric()]
        measure(metrics: metrics) {
            _ = try? FeedParser.parse(data)
        }
    }
}

Performance tests require XCTest — not available in Swift Testing.

Snapshot Testing

Add Point-Free's SnapshotTesting package to the test target via Swift Package Manager, then use it for visual regression. Requires XCTest:

import SnapshotTesting
import XCTest

class ProfileViewSnapshotTests: XCTestCase {
    func testProfileView() {
        let view = ProfileView(user: .preview)
        assertSnapshot(of: view, as: .image(layout: .device(config: .iPhone13)))

        // Dark mode
        assertSnapshot(of: view.environment(\.colorScheme, .dark),
                       as: .image(layout: .device(config: .iPhone13)), named: "dark")

        // Large Dynamic Type
        assertSnapshot(of: view.environment(\.dynamicTypeSize, .accessibility3),
                       as: .image(layout: .device(config: .iPhone13)), named: "largeText")
    }
}

Always test Dark Mode and large Dynamic Type in snapshots.

Test Attachments

Attach diagnostic data to test results for debugging failures:

@Test func generateReport() async throws {
    let report = try generateReport()
    // Attach the output for later inspection
    Attachment.record(report.data, named: "report.json")
    #expect(report.isValid)
}

// Attach from a file URL
@Test func processImage() async throws {
    let output = try processImage()
    let attachment = try await Attachment(contentsOf: output.url, named: "result.png")
    Attachment.record(attachment)
}

Attachments support standard Attachable values such as Data, [UInt8], strings, and Encodable values when Foundation is imported. Image attachments require Swift 6.3 / Xcode 26.4 or newer and support platform image types such as UIImage, CGImage, CIImage, and NSImage; pass as: .png or another supported format when the filename should be explicit.

Exit Testing

Test code that calls exit(), fatalError(), or preconditionFailure(). Exit testing requires Swift 6.2 / Xcode 26.0 or newer and is supported on macOS, Linux, FreeBSD, OpenBSD, and Windows runtime targets, not iOS, tvOS, or watchOS:

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

Exit testing runs the closure in a subprocess. The test passes if the process exits with the expected status. Capturing values from the parent process in an exit-test capture list requires the Swift 6.3 compiler.

Test File Organization

Tests/AppTests/          # Swift Testing (Models/, ViewModels/, Services/)
Tests/AppUITests/        # XCTest UI tests (Pages/, Flows/)
Tests/Fixtures/          # Test data (JSON, images)
Tests/Mocks/             # Shared mock implementations

Name test files <TypeUnderTest>Tests.swift. Describe behavior in function names: fetchUserReturnsNilOnNetworkError() not testFetchUser(). Name mocks Mock<ProtocolName>.

What to Test

Always test: business logic, validation rules, state transitions in view models, error handling paths, edge cases (empty collections, nil, boundaries), async success and failure, Task cancellation.

Skip: SwiftUI view body layout (use snapshots), simple property forwarding, Apple framework behavior, private methods (test through public API).

CustomTestStringConvertible

When parameterized test arguments appear in test output, Swift Testing uses String(describing:) by default. Conform to CustomTestStringConvertible for better output:

enum Food: CaseIterable {
    case paella, oden, ragu
}

extension Food: CustomTestStringConvertible {
    var testDescription: String {
        switch self {
        case .paella: "paella valenciana"
        case .oden: "おでん"
        case .ragu: "ragù alla bolognese"
        }
    }
}

@Test(arguments: Food.allCases)
func isDelicious(_ food: Food) { /* output shows custom descriptions */ }

Use this for any type passed as a parameterized test argument where the default description is unclear — especially enums, IDs, or model types.

Availability-Conditional Tests

Use @available on test functions to run tests only on specific OS versions:

@Test
@available(iOS 18, macOS 15, *)
func usesNewAPI() async throws {
    let result = try await NewFramework.process()
    #expect(result.isValid)
}

Swift Testing skips @available-gated tests when running on older OS versions. This replaces XCTest's #available guard + early return pattern.

Do not put @available on a suite type or a type that contains a suite; Swift Testing requires suite types to always be available. Put availability gates on individual @Test functions instead.

Common Mistakes and Review Checklist

1. Testing implementation, not behavior. Test what the code does, not how. 2. No error path tests. If a function can throw, test the throw path. 3. Flaky async tests. Use confirmation with expected counts, not sleep calls. 4. Shared mutable state between tests. Each test sets up its own state via init() in @Suite or a fixture. 5. Missing accessibility identifiers in UI tests. XCUITest queries rely on them. 6. Using `sleep` in tests. Use confirmation, clock injection, or withKnownIssue. 7. Not testing cancellation. If code supports Task cancellation, verify it cancels cleanly. 8. Unclear XCTest migration boundaries. Apple allows XCTest and Swift Testing in one file during migration; prefer separate files when it keeps imports, ownership, and runner expectations clearer. 9. Non-Sendable test helpers shared across tests. Ensure test helper types are Sendable when shared across concurrent test cases. 10. Assuming test order. Parallel default execution means declaration order and suite nesting do not create a workflow. 11. Using `.serialized` as a dependency chain. Serialized scopes avoid overlap; they do not pass state from one test to the next.

Review Checklist

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