Swift Testing Agent Skill

The swift-testing-expert skill provides guidance for writing, reviewing, migrating, and debugging Swift tests using modern Swift Testing APIs. It is designed for developers working on Apple-platform or Swift server projects who want to prioritize readable tests, robust parallel execution, and clear diagnostics.

Core Capabilities

• Test Architecture: Guidance on suite organization and building blocks.
• Assertions: Best practices for using #expect and #require macros.
• Metadata: Using traits and tags for behavior and filtering.
• Advanced Testing: Implementing parameterized tests and managing async/await patterns.
• Migration: Incremental workflows for moving from XCTest to Swift Testing.
• Performance: Strategies for parallel execution, isolation, and preventing flakiness.

If your tests must interact with shared resources like a database, file system, or external service, use one of the following strategies:

1. Isolate backing state: Ensure each test uses a unique identifier or separate instance of the resource.
2. Use in-memory substitutes: Use fakes or in-memory versions of the resource for faster, isolated testing.
3. Selective serialization: Create a separate serial test plan specifically for the integration path that requires sequential access.

If a suite contains instance test methods, the suite type must have a callable zero-argument initializer. This can be an implicit initializer or an explicit one that provides default values for its properties.

If you cannot provide a zero-argument initializer, you must either:

1. Convert the tests to static/global functions.
2. Refactor the suite state to allow for zero-argument initialization.

import Testing

@Suite
struct SessionTests {
 let config: URLSessionConfiguration

 // Valid: callable with zero args due to default value.
 init(config: URLSessionConfiguration = .ephemeral) {
 self.config = config
 }

 @Test func usesEphemeralByDefault() {
 #expect(config == .ephemeral)
 }
}

Swift Testing uses a suite model (structs, actors, or classes) rather than requiring XCTestCase.

• Setup: Instead of setUp(), use the init() method of your suite (struct/class/actor) to initialize shared state.
• Teardown: Use deinit when using class or actor-based suites.
• Concurrency: Note that XCTest sync tests default to the @MainActor, whereas Swift Testing runs on arbitrary tasks unless you explicitly isolate them (e.g., using @MainActor).

import Testing

struct SessionTests {
 let session: Session

 init() {
 self.session = Session(environment: .test)
 }

 @Test func startsDisconnected() {
 #expect(session.isConnected == false)
 }
}

You can migrate from XCTest to Swift Testing incrementally without a full rewrite. Swift Testing and XCTest can coexist within the same target. During migration, a single source file can import both XCTest and Testing to allow for a phased transition.

import XCTest
import Testing

To use Swift Testing, follow these core principles:

• Imports: Only import Testing in your test targets; do not import it in your application code.
• Test Declaration: Use the @Test attribute to explicitly declare tests. These can be global functions or methods within a type.
• Suites: Use struct, actor, or class to group related tests.
  • Recommendation: Prefer struct for suites to leverage value semantics and prevent accidental state sharing between tests.
• Suite Metadata: Use the @Suite attribute when you need to add suite-level traits or custom display names.
• Hierarchy: Use nested suites to reflect feature groupings and improve test discoverability.

Instead of using fragile test-name patterns, use tags to filter and group tests in the Xcode navigator. This enables focused development loops and stable cross-suite inspection.

Suggested Tag Conventions:

• core: Always-on, fast checks.
• integration: Tests covering external dependencies.
• regression: Tests used to lock in bug fixes.
• flaky: Tests temporarily quarantined while being fixed.

Swift Testing uses Traits to modify test behavior, provide metadata, or control execution conditions. Traits can be categorized into three types:

1. Informational: Used for display names, linking bug reports, or adding metadata (e.g., .bug("URL")).
2. Conditional: Used to enable or disable tests based on runtime conditions or availability (e.g., .enabled(if:), .disabled("reason")).
3. Behavioral: Used to modify how the test runs (e.g., .timeLimit(...), .serialized).

Always include an actionable reason when using .disabled("reason") to assist in CI/test reporting.

import Testing

@Test("Uploads complete quickly", .timeLimit(.seconds(10)))
func uploadWithinTimeLimit() async throws {
 #expect(true)
}

@Test(.disabled("Flaky on CI while investigating issue"), .bug("https://example.com/issues/12"))
func temporaryDisabledTest() {
 #expect(true)
}