swift-testing

name: "Swift Testing Framework Guidelines" description: "Modern Swift Testing patterns with @Test macros, #expect/#require assertions, async testing, parameterized tests, and test organization. Apply when writing or modifying tests, setting up test suites, or working with test files." agent_requested: true applies_to: ["/Tests//*.swift", "/*Tests.swift", "/*Test.swift"]

Swift Testing Framework Guidelines

Modern Testing with @Test Macros

Use the Swift Testing framework (not XCTest) for all tests. Tests should be placed in MyProjectPackage/Tests.

Basic Test Structure

import Testing

@Test("User can successfully log in with valid credentials")
func userLogin() async throws {
    let authService = AuthService()
    let result = try await authService.login(
        username: "testuser",
        password: "validpassword"
    )
    
    #expect(result.isSuccess)
    #expect(result.user.name == "Test User")
}

@Test("Login fails with invalid credentials")
func invalidLogin() async throws {
    let authService = AuthService()
    
    await #expect(throws: AuthError.invalidCredentials) {
        try await authService.login(username: "", password: "")
    }
}

Required Patterns

1. Use @Test macro instead of XCTest's test prefix
2. Use #expect and #require for assertions, not XCTAssert
3. Include descriptive test names as string parameters
4. Test async code with proper async/await patterns
5. Use #require when test should stop on failure

Key Swift Testing Features

• @Test: Marks a test function (replaces XCTest's test prefix)
• @Suite: Groups related tests together
• #expect: Validates conditions (replaces XCTAssert)
• #require: Like #expect but stops test execution on failure
• Parameterized Tests: Use @Test with arguments for data-driven tests
• async/await: Full support for testing async code
• Traits: Add metadata like .bug(), .feature(), or custom tags