Help us improve
Share bugs, ideas, or general feedback.
From apple-kit-skills
Writes and migrates tests using Swift Testing framework (@Test, @Suite, #expect, #require). Covers parameterized tests, test traits, mocking, XCTest UI testing, and TDD patterns.
npx claudepluginhub dpearson2699/swift-ios-skills --plugin swiftui-skillsHow this skill is triggered — by the user, by Claude, or both
Slash command
/apple-kit-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.
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.
Writes, reviews, and improves Swift Testing code using modern APIs and best practices, including migration from XCTest.
Share bugs, ideas, or general feedback.
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.
@Test Traits@Suite and Test Organizationimport 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 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 OrganizationSee references/testing-patterns.md for suite organization, confirmation patterns, known-issue handling, and execution-model details.
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:
@Suite(.serialized) is for exclusive execution, not for expressing logical ordering between tests.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 parameterized tests, tags and suites, async testing, traits, and execution-model details.
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 are available via cross-import overlays — import both Testing and a UI framework:
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.png")
}
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()
}
}
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..serialized only when exclusive execution is required..serialized to express workflow steps. Serialized execution does not make one test feed another; keep dependent steps in one test.@Test, #expect), not XCTest assertionsfetchUserReturnsNilOnNetworkError not testFetchUser)confirmation(), not Task.sleep.critical, .slow).serialized used only for truly exclusive state, not to model workflow sequencing