Swift Testing

Overview

Swift Testing is Apple's modern testing framework introduced at WWDC 2024. It uses Swift macros (@Test, #expect) instead of naming conventions, runs tests in parallel by default, and integrates seamlessly with Swift concurrency.

Core principle: Tests should be fast, reliable, and expressive. The fastest tests run without launching your app or simulator.

The Speed Hierarchy

Tests run at dramatically different speeds depending on how they're configured:

Key insight: Move testable logic into Swift Packages or frameworks, then test with swift test or "None" host application.

Building Blocks

@Test Functions

import Testing

@Test func videoHasCorrectMetadata() {
    let video = Video(named: "example.mp4")
    #expect(video.duration == 120)
}

Key differences from XCTest:

• No test prefix required — @Test attribute is explicit
• Can be global functions, not just methods in a class
• Supports async, throws, and actor isolation
• Each test runs on a fresh instance of its containing suite

#expect and #require

// Basic expectation — test continues on failure
#expect(result == expected)
#expect(array.isEmpty)
#expect(numbers.contains(42))

// Required expectation — test stops on failure
let user = try #require(await fetchUser(id: 123))
#expect(user.name == "Alice")

// Unwrap optionals safely
let first = try #require(items.first)
#expect(first.isValid)

Why #expect is better than XCTAssert:

• Captures source code and sub-values automatically
• Single macro handles all operators (==, >, contains, etc.)
• No need for specialized assertions (XCTAssertEqual, XCTAssertNil, etc.)

Error Testing

// Expect any error
#expect(throws: (any Error).self) {
    try dangerousOperation()
}

// Expect specific error type
#expect(throws: NetworkError.self) {
    try fetchData()
}

// Expect specific error value
#expect(throws: ValidationError.invalidEmail) {
    try validate(email: "not-an-email")
}

// Custom validation
#expect {
    try process(data)
} throws: { error in
    guard let networkError = error as? NetworkError else { return false }
    return networkError.statusCode == 404
}

@Suite Types

@Suite("Video Processing Tests")
struct VideoTests {
    let video = Video(named: "sample.mp4")  // Fresh instance per test

    @Test func hasCorrectDuration() {
        #expect(video.duration == 120)
    }

    @Test func hasCorrectResolution() {
        #expect(video.resolution == CGSize(width: 1920, height: 1080))
    }
}

Key behaviors:

• Structs preferred (value semantics, no accidental state sharing)
• Each @Test gets its own suite instance
• Use init for setup, deinit for teardown (actors/classes only)
• Nested suites supported for organization

Traits

Traits customize test behavior:

// Display name
@Test("User can log in with valid credentials")
func loginWithValidCredentials() { }

// Disable with reason
@Test(.disabled("Waiting for backend fix"))
func brokenFeature() { }

// Conditional execution
@Test(.enabled(if: FeatureFlags.newUIEnabled))
func newUITest() { }

// Time limit
@Test(.timeLimit(.minutes(1)))
func longRunningTest() async { }

// Bug reference
@Test(.bug("https://github.com/org/repo/issues/123", "Flaky on CI"))
func sometimesFailingTest() { }

// OS version requirement
@available(iOS 18, *)
@Test func iOS18OnlyFeature() { }

Tags for Organization

// Define tags
extension Tag {
    @Tag static var networking: Self
    @Tag static var performance: Self
    @Tag static var slow: Self
}

// Apply to tests
@Test(.tags(.networking, .slow))
func networkIntegrationTest() async { }

// Apply to entire suite
@Suite(.tags(.performance))
struct PerformanceTests {
    @Test func benchmarkSort() { }  // Inherits .performance tag
}

Use tags to:

• Run subsets of tests (filter by tag in Test Navigator)
• Exclude slow tests from quick feedback loops
• Group related tests across different files/suites

Parameterized Testing

Transform repetitive tests into a single parameterized test:

// ❌ Before: Repetitive
@Test func vanillaHasNoNuts() {
    #expect(!IceCream.vanilla.containsNuts)
}
@Test func chocolateHasNoNuts() {
    #expect(!IceCream.chocolate.containsNuts)
}