Converting Xctest To Swift Testing

Converting XCTest to Swift Testing

Use this skill to convert an existing XCTest file to the Swift Testing framework following Bitwarden iOS patterns.

Before You Start — Is This File Convertible?

Do NOT convert the following; leave them in XCTest:

Stop and flag the issue before proceeding.

Step 1: Read the File

Read the entire test file first. Understand:

• What type is under test (processor, coordinator, service, etc.)
• Whether any methods have @MainActor (and which)
• Whether any tests use addTeardownBlock
• Any non-mechanical patterns that may need judgment calls

Step 2: Transform the File Header

Imports

Replace import XCTest with import Testing. Keep all other imports unchanged:

// Before:
import XCTest
@testable import BitwardenShared

// After:
import Testing
@testable import BitwardenShared

XCTest implicitly re-exports Foundation, so removing it can cause missing-symbol build errors if the file uses Foundation types directly. If the build fails after conversion, add import Foundation.

Class → Struct

@MainActor placement

If test methods had @MainActor (processor tests, coordinator tests), move it to the struct declaration:

// Before: @MainActor on individual methods
// After:
@MainActor
struct FooProcessorTests {

Service tests typically do not need @MainActor — do NOT add it unless the service dispatches to main.

Step 3: Convert Properties

Change force-unwrapped var properties (those ending in !) to let non-optionals:

// Before:
var coordinator: MockCoordinator<FooRoute, FooEvent>!
var errorReporter: MockErrorReporter!
var subject: FooProcessor!

// After:
let coordinator: MockCoordinator<FooRoute, FooEvent>
let errorReporter: MockErrorReporter
let subject: FooProcessor

services property: Remove it if it is only used inside setUp() to construct the subject — it does not need to be a stored property in Swift Testing. Keep it as let services: MockServiceContainer if test methods reference it directly for assertions.

Step 4: Convert Setup, Teardown, and State Lifecycle

Swift Testing replaces setUpWithError and tearDownWithError with a more natural, type-safe lifecycle using init() and deinit.

The Core Concept: A fresh, new instance of the test suite (struct or class) is created for each test function it contains. This is the cornerstone of test isolation, guaranteeing that state from one test cannot leak into another.

setUp() → init()

Move all setup code into init(), removing the super.setUp() call:

// Before:
override func setUp() {
    super.setUp()

    coordinator = MockCoordinator()
    errorReporter = MockErrorReporter()
    subject = FooProcessor(
        coordinator: coordinator.asAnyCoordinator(),
        services: ServiceContainer.withMocks(errorReporter: errorReporter),
        state: FooState(),
    )
}

// After:
init() {
    coordinator = MockCoordinator()
    errorReporter = MockErrorReporter()
    subject = FooProcessor(
        coordinator: coordinator.asAnyCoordinator(),
        services: ServiceContainer.withMocks(errorReporter: errorReporter),
        state: FooState(),
    )
}

tearDown() → delete

Remove the entire tearDown() override. Swift Testing creates a fresh struct instance for every test — all properties are discarded automatically. No nilling out is needed.

addTeardownBlock { ... }

• If the block just nils out properties: delete it (struct isolation handles this).
• If the block cleans up external resources (e.g., temp files, keychain entries): convert to deinit and change the struct to a class. deinit is not available on struct.

Action Items

• Convert test classes from XCTestCase to structs (preferred for automatic state isolation) or final classes.
• Move setUp logic into the suite's init().
• Move tearDown logic into the suite's deinit (and use a class or actor if needed).
• Define the SUT and its dependencies as let properties, initialized in init().

Step 5: Convert Test Methods

Rename and annotate

Remove the test_ prefix. Add @Test attribute. Remove @MainActor from individual methods (it's now on the struct):

// Before:
@MainActor
func test_receive_valueChanged_updatesState() { ... }

// After:
@Test
func receive_valueChanged_updatesState() { ... }

async throws signatures are unchanged:

// Before:
@MainActor
func test_perform_appeared_loadsData() async throws { ... }

// After:
@Test
func perform_appeared_loadsData() async throws { ... }

Add DocC comments

Every @Test function must have a /// doc comment. The comment must start with the backtick-wrapped symbol name of the function under test (including parameter labels), followed by a plain-English description of the behaviour being verified:

/// `receive(_:)` updates the state when the value changes.
@Test
func receive_valueChanged_updatesState() { ... }

/// `perform(_:)` loads data when the view appears.
@Test
func perform_appeared_loadsData() async throws { ... }

For parameterized tests the same rule applies — the symbol name comes first:

/// `parseCard(lines:)` extracts card numbers across space-separated, dash-separated, and multi-segment formats.
@Test(arguments: zip(inputs, expectedNumbers))
func parseCard_extractsCardNumber(lines: [String], expectedNumber: String) { ... }

Step 6: Convert Assertions

Replace the entire XCTAssert family with two powerful, expressive macros. They accept regular Swift expressions, eliminating the need for dozens of specialized XCTAssert functions.

Power Move: Visual Failure Diagnostics

Unlike XCTAssert, which often only reports that a comparison failed, #expect shows you the exact values that caused the failure, directly in the IDE and logs. This visual feedback is a massive productivity boost.

Code:

@Test("User count meets minimum requirement")
func userCount_minimum() {
    let userCount = 5
    // This check will fail
    #expect(userCount > 10)
}

Failure Output in Xcode:

▽ Expected expression to be true
#expect(userCount > 10)
      |         | |
      5         | 10
                false

Power Move: Optional-Safe Unwrapping

#require is the new, safer replacement for XCTUnwrap. It not only checks for nil but also unwraps the value for subsequent use.

Before: The XCTest Way

// In an XCTestCase subclass...
func testFetchUser_succeeds_XCTest() async throws {
    let user = try XCTUnwrap(await fetchUser(id: "123"), "Fetching user should not return nil")
    XCTAssertEqual(user.id, "123")
}

After: The Swift Testing Way

@Test("Fetching a valid user succeeds")
func fetchUser_succeeds() async throws {
    // #require both checks for nil and unwraps `user` in one step.
    // If fetchUser returns nil, the test stops here and fails.
    let user = try #require(await fetchUser(id: "123"))

    // `user` is now a non-optional User, ready for further assertions.
    #expect(user.id == "123")
    #expect(user.age == 37)
}

Common Assertion Conversions Quick Reference

Use this table as a cheat sheet when migrating your XCTest assertions.

Action Items

• Run grep -R "XCTAssert\|XCTUnwrap" . to find all legacy assertions.
• Convert try XCTUnwrap() calls to try #require(). This is a direct and superior replacement.
• Convert most XCTAssert...() calls to #expect(). Use #require() only for preconditions where continuing the test makes no sense.
• Group related checks logically within a test. Since #expect continues on failure, you can naturally check multiple properties of an object in a single test.

Step 7: Drastically Reduce Boilerplate with Parameterized Tests

Run a single test function with multiple argument sets to maximize coverage with minimal code. This is superior to a for-in loop because each argument set runs as an independent test, can be run in parallel, and failures are reported individually.

Example: Migrating Repetitive Tests to a Parameterized One

Before: The XCTest Way

func test_flavorVanilla_containsNoNuts() {
    let flavor = Flavor.vanilla
    XCTAssertFalse(flavor.containsNuts)
}
func test_flavorPistachio_containsNuts() {
    let flavor = Flavor.pistachio
    XCTAssertTrue(flavor.containsNuts)
}
func test_flavorChocolate_containsNoNuts() {
    let flavor = Flavor.chocolate
    XCTAssertFalse(flavor.containsNuts)
}

After: The Swift Testing Way using zip

@Test("Flavor nut content is correct", arguments: zip(
    [Flavor.vanilla, .pistachio, .chocolate],
    [false, true, false]
))
func flavor_containsNuts(flavor: Flavor, expected: Bool) {
    #expect(flavor.containsNuts == expected)
}

Action Items

• Combine multiple tests with matching boilerplate into a single parameterized test

Step 8: Bitwarden-Specific Patterns

Unchanged patterns

These work identically in both frameworks — do not modify them:

• coordinator.asAnyCoordinator()
• ServiceContainer.withMocks(...)
• BitwardenTestError.example / .mock("desc")
• coordinator.alertShown, coordinator.routes
• errorReporter.errors

Cast assertions

// Before:
XCTAssertEqual(errorReporter.errors.last as? BitwardenTestError, .example)

// After:
#expect(errorReporter.errors.last as? BitwardenTestError == .example)

coordinator.alertShown nil check

// Before:
XCTAssertNotNil(coordinator.alertShown.last)

// After:
#expect(coordinator.alertShown.last != nil)

Optional unwrap then assert

// Before:
let action = try XCTUnwrap(stackNavigator.actions.last)
XCTAssertEqual(action.type, .pushed)

// After:
let action = try #require(stackNavigator.actions.last)
#expect(action.type == .pushed)

Step 9: Verify

Run these checks after conversion:

1. No XCTest remnants: grep for XCTAssert, setUp, tearDown, XCTestCase, import XCTest — all should be gone.
2. All tests annotated: every former test_ function has @Test.
3. No forced optionals: no force-unwrapped var properties remain.
4. Build passes: run mint run swiftformat . and build the target.
5. Tests pass: run the converted test file.

Reference Material

This is additional information about Swift Testing that doesn't neatly fit into steps above.

Conditional Execution & Skipping

Dynamically control which tests run based on feature flags, environment, or known issues.