Parameterized tests and test organization with Swift Testing

As a test suite grows, we often end up writing multiple test functions that exercise the same behavior with slightly different inputs. Each test is simple on its own, but the repetition makes the whole suite harder to scan and maintain.

Swift Testing addresses this with parameterized tests. They let us pass a collection of arguments to one test function and create a separate test case for each argument. We can then use suites and tags to keep those cases organized as the project grows.

In this article, we'll look at how to:

1. Replace repetitive tests with a parameterized test.
2. Model more complex inputs as test cases.
3. Test combinations of multiple argument collections.
4. Organize tests with suites, nested suites and tags.
5. Keep parallel execution in mind when structuring a suite.

If you're new to the framework, you can start with this developer guide on Swift Testing, which covers test functions, expectations and the differences from XCTest.

Architecture & Design Patterns for iOS

This book is a practical guide to essential architectural principles and design patterns for iOS development. It covers strategies for building maintainable apps with Swift and SwiftUI, including dependency injection, navigation, common patterns, and modularization.

LEARN MORE

Replacing repetitive tests with a parameterized test

Let's say our app contains a formatter that turns a title into a URL slug:

struct SlugFormatter {

    let separator: String

    init(separator: String = "-") {
        self.separator = separator
    }

    func format(_ title: String) -> String {
        title
            .lowercased()
            .replacingOccurrences(of: " ", with: separator)
    }
}

We could test several inputs by creating a separate test function for each one:

import Testing
@testable import ExampleApp

struct SlugFormatterTests {

    @Test func formatsSingleWord() {
        let result = SlugFormatter().format("Swift")
        #expect(result == "swift")
    }

    @Test func formatsMultipleWords() {
        let result = SlugFormatter().format("Swift Testing")
        #expect(result == "swift-testing")
    }

    @Test func formatsEmptyString() {
        let result = SlugFormatter().format("")
        #expect(result == "")
    }
}

The arrange and assertion logic is identical in all three tests. Only the input and expected output change. We can keep each pair together in a small test-case type:

struct SlugTestCase: Sendable {
    let title: String
    let expectedSlug: String
}

extension SlugTestCase {
    static let examples = [
        SlugTestCase(title: "Swift", expectedSlug: "swift"),
        SlugTestCase(title: "Swift Testing", expectedSlug: "swift-testing"),
        SlugTestCase(title: "", expectedSlug: "")
    ]
}

@Test(arguments: SlugTestCase.examples)
func formatsTitle(_ testCase: SlugTestCase) {
    let result = SlugFormatter().format(testCase.title)
    #expect(result == testCase.expectedSlug)
}

Swift Testing creates an individual test case for every element in the collection and passes that element to the test function. If one case fails, Xcode reports the corresponding argument, which makes the failing input easier to identify than a failure inside a manual loop.

As a shorter alternative, we can keep the inputs and expected outputs in separate collections and combine them with zip:

@Test(
    arguments: zip(
        ["Swift", "Swift Testing", ""],
        ["swift", "swift-testing", ""]
    )
)
func formatsTitle(_ title: String, expectedSlug: String) {
    let result = SlugFormatter().format(title)
    #expect(result == expectedSlug)
}

zip pairs the first title with the first expected slug, the second title with the second expected slug and so on. This gives us the same three test cases without introducing SlugTestCase. However, the two collections need to stay in the same order. A dedicated type keeps each input visibly next to its expected output and scales better when a test needs more values.

Testing more than one collection of arguments

We can also pass multiple collections to a parameterized test. Unlike zip, Swift Testing then uses the Cartesian product: every value from the first collection is paired with every value from the second.

This is useful when the same expectation applies to every combination. For example, suppose both editors and administrators should be able to edit every supported content type:

enum UserRole {
    case editor
    case administrator
}

enum ContentType {
    case article
    case video
}

@Test(
    arguments: [UserRole.editor, .administrator],
               [ContentType.article, .video]
)
func authorizedRoleCanEdit(_ role: UserRole, contentType: ContentType) {
    let result = Permissions().canEdit(contentType, as: role)
    #expect(result == true)
}

With two roles and two content types, Swift Testing creates four test cases. The expected result is explicit and doesn't need to be derived inside the test. If only particular roles and content types should be paired, zip or a dedicated test-case type would be a better fit than a Cartesian product.

Organizing tests in suites

Any Swift type that contains test functions acts as a test suite. We don't need to add @Suite when the type name already describes the group clearly:

struct SlugFormatterTests {
    @Test func formatsTitles() { ... }
    @Test func usesCustomSeparators() { ... }
}

Here, the suite groups two related behaviors of SlugFormatter, and that hierarchy is reflected in Xcode's Test navigator. As the suite grows, we can nest additional suite types to separate meaningful groups such as default formatting and custom separators.

The @Suite attribute becomes useful when we want to apply traits to the whole group or need a custom display name that adds information beyond the type name. We shouldn't add it only to repeat a name that is already clear in code.

Grouping related tests with tags

Suites create a source-level hierarchy: every test belongs to one place in that hierarchy. Tags provide an additional way to group tests across files and suites.

We first declare the tags as static members of Tag:

extension Tag {
    @Tag static var formatting: Self
    @Tag static var critical: Self
}

We can then apply them to an individual test:

@Test(
    .tags(.formatting, .critical),
    arguments: SlugTestCase.examples
)
func formatsTitle(_ testCase: SlugTestCase) {
    let result = SlugFormatter().format(testCase.title)

    #expect(result == testCase.expectedSlug)
}

Or we can apply a tag to a suite. Its tests and nested suites inherit that tag:

@Suite(.tags(.formatting))
struct SlugFormatterTests {
    // All tests in this suite inherit the formatting tag.
}

Tags are useful for categories that cross the suite hierarchy, such as critical tests, tests for a particular feature or tests that depend on a certain resource. Xcode can display and run tests by tag from the Test navigator.

Accounting for parallel execution

Swift Testing runs tests in parallel by default, including the individual cases of a parameterized test. This makes a large test suite faster, but it also means test cases shouldn't mutate shared state or rely on a particular execution order.

Swift Testing doesn't create one suite instance and call all test methods on it. For every test case, it first creates a new suite instance and then invokes the test method on that instance. In a parameterized test, this happens for every argument.

This means that formatter is initialized again for each test case in the following example:

struct SlugFormatterTests {
    let formatter = SlugFormatter()

    @Test(arguments: SlugTestCase.examples)
    func formatsTitle(_ testCase: SlugTestCase) {
        #expect(
            formatter.format(testCase.title) == testCase.expectedSlug
        )
    }
}

Independent test data is preferable to disabling parallelization. When tests must share a resource that can't safely be isolated, we can apply the .serialized trait:

@Suite(.serialized)
struct DatabaseMigrationTests {
    // Tests in this suite run one after another.
}

Applied to a suite, .serialized also affects its nested suites and parameterized test cases. It should be used deliberately: serialization can hide shared-state problems and slow the test suite, so isolating dependencies is usually the better long-term solution.

Conclusion

Parameterized tests let us describe a behavior once and verify it against many inputs. Each argument still becomes its own test case, so we keep focused diagnostics without duplicating the test logic.

For a maintainable test suite, we can use the different organization tools for different purposes:

• Parameterized tests cover multiple inputs for the same behavior.
• Suites group tests by feature or responsibility.
• Nested suites divide a larger feature into meaningful behaviors.
• Tags create groups that span multiple suites and files.

Together, these tools keep the suite easier to navigate while allowing us to add edge cases simply by extending an argument collection.