From swift-core-skills
Write and migrate tests using the Swift Testing framework with @Test, @Suite, #expect, #require, confirmation, parameterized tests, test tags, traits, withKnownIssue, XCTest UI testing, XCUITest, test plan, mocking, test doubles, testable architecture, snapshot testing, async test patterns, test organization, and test-driven development in Swift. Use when writing or migrating tests with Swift Testing framework, implementing parameterized tests, working with test traits, converting XCTest to Swift Testing, or setting up test organization and mocking patterns.
How this skill is triggered — by the user, by Claude, or both
Slash command
/swift-core-skills:swift-testingThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
Swift Testing is the modern testing framework for Swift (Xcode 16+, Swift 6+). Prefer it over XCTest for all new unit tests. Use XCTest only for UI tests, performance benchmarks, and snapshot tests.
Swift Testing is the modern testing framework for Swift (Xcode 16+, Swift 6+). Prefer it over XCTest for all new unit tests. Use XCTest only for UI tests, performance benchmarks, and snapshot 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("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 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.
See references/testing-patterns.md for suite organization, confirmation patterns, and known-issue handling.
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.
See references/testing-patterns.md for complete examples of:
Pass any Sendable & Collection to arguments:. Each element runs as an independent test case.
// Enum-based: runs one case per enum value
enum Environment: String, CaseIterable, Sendable {
case development, staging, production
}
@Test("Base URL is valid for all environments", arguments: Environment.allCases)
func baseURLIsValid(env: Environment) throws {
let url = try #require(URL(string: Config.baseURL(for: env)))
#expect(url.scheme == "https")
}
@Test("Fibonacci is positive for small inputs", arguments: 1...20)
func fibonacciPositive(n: Int) {
#expect(fibonacci(n) > 0)
}
Two argument collections produce a cartesian product (every combination):
@Test(arguments: ["light", "dark"], ["iPhone", "iPad"])
func snapshotTest(colorScheme: String, device: String) {
// Runs 4 combinations: light+iPhone, light+iPad, dark+iPhone, dark+iPad
let config = SnapshotConfig(colorScheme: colorScheme, device: device)
#expect(config.isValid)
}
Use zip for 1:1 pairing (avoids cartesian product):
@Test(arguments: zip(
[200, 201, 204],
["OK", "Created", "No Content"]
))
func httpStatusDescription(code: Int, expected: String) {
#expect(HTTPStatus(code).description == expected)
}
Create a CustomTestArgumentProviding conformance or use computed static properties:
struct APIEndpoint: Sendable {
let path: String
let expectedStatus: Int
static let testCases: [APIEndpoint] = [
.init(path: "/users", expectedStatus: 200),
.init(path: "/missing", expectedStatus: 404),
]
}
@Test("API returns expected status", arguments: APIEndpoint.testCases)
func apiStatus(endpoint: APIEndpoint) async throws {
let response = try await client.get(endpoint.path)
#expect(response.statusCode == endpoint.expectedStatus)
}
Declare tags as static members on Tag:
extension Tag {
@Tag static var networking: Self
@Tag static var database: Self
@Tag static var slow: Self
@Tag static var critical: Self
@Tag static var smoke: Self
}
Run tagged tests from Xcode Test Plans or the command line:
# Run only tests tagged .networking
swift test --filter tag:networking
# Exclude slow tests
swift test --skip tag:slow
In Xcode, configure Test Plans to include/exclude tags for different CI configurations (smoke tests vs full suite).
@Suite("Shopping Cart Operations")
struct ShoppingCartTests {
let cart: ShoppingCart
// init acts as setUp -- runs before each test in the suite
init() {
cart = ShoppingCart()
cart.add(Product(name: "Widget", price: 9.99))
}
@Test func itemCount() {
#expect(cart.items.count == 1)
}
@Test func totalPrice() {
#expect(cart.total == 9.99)
}
}
Use init for setup and deinit for teardown. For async cleanup, use a TestScoping trait:
@Suite(.tags(.database))
struct DatabaseTests {
let db: TestDatabase
init() async throws {
db = try await TestDatabase.createTemporary()
}
// deinit works for synchronous cleanup (struct suites only use init)
// For async teardown, use TestScoping trait instead
@Test func insertRecord() async throws {
try await db.insert(Record(id: 1, name: "Test"))
let count = try await db.count()
#expect(count == 1)
}
}
@Test functions can be async and throws directly:
@Test func fetchUserProfile() async throws {
let service = UserService(client: MockHTTPClient())
let user = try await service.fetchProfile(id: 42)
#expect(user.name == "Alice")
}
Access actor-isolated state with await:
actor Counter {
private(set) var value = 0
func increment() { value += 1 }
}
@Test func counterIncrements() async {
let counter = Counter()
await counter.increment()
await counter.increment()
let value = await counter.value
#expect(value == 2)
}
Use .timeLimit to prevent tests from hanging indefinitely:
@Test(.timeLimit(.seconds(5)))
func networkCallCompletes() async throws {
let result = try await api.fetchData()
#expect(result.isEmpty == false)
}
If the test exceeds the time limit, it fails immediately with a clear timeout diagnostic.
confirmation replaces XCTestExpectation / fulfill() / waitForExpectations. It verifies that an event occurs the expected number of times:
@Test func notificationPosted() async throws {
// Expects the closure to call confirm() exactly once
try await confirmation("UserDidLogin posted") { confirm in
let center = NotificationCenter.default
let observer = center.addObserver(
forName: .userDidLogin, object: nil, queue: .main
) { _ in
confirm()
}
await loginService.login(user: "test", password: "pass")
center.removeObserver(observer)
}
}
// Expect multiple confirmations
@Test func batchProcessing() async throws {
try await confirmation("Items processed", expectedCount: 3) { confirm in
processor.onItemComplete = { _ in confirm() }
await processor.process(items: [a, b, c])
}
}
// Enable only on CI
@Test(.enabled(if: ProcessInfo.processInfo.environment["CI"] != nil))
func integrationTest() async throws { ... }
// Disable with a reason
@Test(.disabled("Blocked by #123 -- server migration"))
func brokenEndpoint() async throws { ... }
// Bug reference -- links test to an issue tracker
@Test(.bug("https://github.com/org/repo/issues/42", "Intermittent timeout"))
func flakyNetworkTest() async throws { ... }
@Test(.timeLimit(.minutes(2)))
func longRunningImport() async throws {
try await importer.importLargeDataset()
}
// Apply time limit to entire suite
@Suite(.timeLimit(.seconds(30)))
struct FastTests {
@Test func quick1() { ... }
@Test func quick2() { ... }
}
Create reusable traits for common test configurations:
struct DatabaseTrait: TestTrait, SuiteTrait, TestScoping {
func provideScope(
for test: Test,
testCase: Test.Case?,
performing function: @Sendable () async throws -> Void
) async throws {
let db = try await TestDatabase.setUp()
defer { Task { await db.tearDown() } }
try await function()
}
}
extension Trait where Self == DatabaseTrait {
static var database: Self { .init() }
}
// Usage: any test with .database trait gets a fresh database
@Test(.database)
func insertUser() async throws { ... }
confirmation with expected counts, not sleep calls.init() in @Suite.sleep in tests. Use confirmation, clock injection, or withKnownIssue.Task cancellation, verify it cancels cleanly.@MainActor.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(report.data, named: "report.json").record()
#expect(report.isValid)
}
Test code that calls exit(), fatalError(), or preconditionFailure(). See references/testing-patterns.md for details.
@Test func invalidInputCausesExit() async {
await #expect(processExitsWith: .failure) {
processInvalidInput() // calls fatalError()
}
}
@Test, #expect), not XCTest assertionsfetchUserReturnsNilOnNetworkError not testFetchUser)confirmation(), not Task.sleep.critical, .slow)references/testing-patterns.mdnpx claudepluginhub andrew-d/claude-skills --plugin swift-ios-skills--swift-core-skillsWrites and migrates tests using Swift Testing framework (@Test, @Suite, #expect, #require). Covers parameterized tests, test traits, mocking, XCTest UI testing, and TDD patterns.
Guides writing tests with Swift Testing framework using @Test, #expect, #require macros, migrating from XCTest, async tests, and parameterization.
Guides Swift Testing: test structure, #expect/#require macros, traits/tags, parameterized tests, plans, parallel execution, async patterns, XCTest migration. For new tests, modernizing suites, flaky debugging.