Skip to content
Tutorials Center
My learning

Topics

Lesson 129 of 146 ยท Platforms and Ecosystem

Swift Testing: @Test, #expect and Traits

Learn the Swift Testing framework in depth - suites and their lifecycle, parameterized tests, traits and tags, expecting errors, confirmations and known issues, all running for real.

Testing introduced the basics: a test is a function, #expect checks a condition, and Swift Testing replaces the pile of XCTAssert... functions with one macro. This lesson goes through the rest of the framework: how suites are created, how to run one test over many inputs, how traits and tags describe and control tests, and the tools for errors, callbacks and bugs you have not fixed yet.

Swift Testing is a normal Swift package (import Testing), so every example here is a real test run on the server. Each program ends with the line let code: Never = await Testing.__swiftPMEntryPoint(), which asks the framework to discover and run the tests in the file. On your own machine you do not write that line: swift test starts the runner for you (see Swift Package Manager). The runner prints its report to the error stream, and the order of the lines changes from run to run because tests run in parallel.

Tests, suites and a fresh instance for each test

Any function marked @Test is a test. A type that contains tests is a suite. You may add @Suite to give it a display name or traits, but a type with @Test methods is already treated as one.

The rule that surprises people coming from XCTest: Swift Testing creates a new instance of the suite for every test. Stored properties are your fixture, init is your setup, and if the suite has a deinit it is your teardown. There is no shared state to reset, so tests cannot affect each other.

sequenceDiagram
    participant R as Test runner
    participant S1 as Suite instance 1
    participant S2 as Suite instance 2
    R->>S1: init()
    R->>S1: run startsAtZero()
    R->>S1: deinit
    R->>S2: init()
    R->>S2: run incrementsOnce()
    R->>S2: deinit

Every test method gets its own suite instance, created by init and destroyed by deinit.

Swift A new suite instance for every test

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with readLine()), it gets the next line from this box.

setup prints twice, once per test, and both tests see counter.value == 0 at the start even though incrementsOnce changes it. A test that mutates the suite must be marked mutating, which works because a suite can be a struct. If setup can fail or is asynchronous, declare init() async throws and the framework awaits it.

At the end of the report you see a line such as Test run with 2 tests in 1 suite passed. Suites can nest: put a @Suite type inside another one to group related tests, and the report shows the hierarchy.

Running one test over many inputs

A hand-written for loop inside a test stops at the first failure and hides which input was bad. @Test(arguments:) calls the function once per element and reports each case on its own.

Swift Parameterized tests

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with readLine()), it gets the next line from this box.

Look at the summary lines near the end: palindromes(text:) passed with 3 test cases, combos(n:s:) with 6, zipped(n:word:) with 3. Passing two collections gives the cartesian product, which is easy to do by accident; wrap them in zip(...) when the values belong together. Each case prints its argument values, so a failure tells you exactly which input broke. Arguments must be Sendable, and for big or generated inputs they can be any Collection, including ranges.

Traits: describing and controlling tests

Extra arguments to @Test and @Suite are traits. Some add information, others change whether and how a test runs.

Trait Effect
.tags(.fast) Labels the test so you can filter and group by tag
.disabled("reason") Skips the test and shows the reason
.enabled(if: condition) Runs the test only when the condition is true
.timeLimit(.minutes(1)) Fails the test if it runs too long (granularity is minutes)
.bug("url", "title") Links the test to an issue tracker entry
.serialized On a suite or parameterized test: run one case at a time

Tags are declared once with the @Tag macro in an extension of Tag, and are then usable everywhere.

Swift Tags and traits in action

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with readLine()), it gets the next line from this box.

The report shows the disabled test as skipped with its reason, and the run summary counts five tests while only four of them executed. Traits set on a suite apply to every test inside it, which is the usual way to tag a whole group at once. In Xcode the tags also appear in the test navigator, and you can run just one tag.

Because the display name in @Test("fast math") is free text, reports and Xcode show it instead of the function name. Keep the function name for the code and the display name for people.

Tests run in parallel

Swift Testing runs tests in parallel by default, using Swift concurrency, so tests must not depend on order or on shared global state. If a group of tests really does share one resource (a single file, a port), mark the suite .serialized:

Swift
@Suite(.serialized)
struct DatabaseTests {
    @Test func insert() { /* ... */ }
    @Test func delete() { /* ... */ }
}

.serialized keeps the tests inside that suite apart from each other; tests in other suites still run alongside. Prefer making the tests independent, for example by giving each its own in-memory store from init, over serializing. See concurrency for why shared mutable state needs care.

Expecting errors

The throws: form of #expect has several shapes. All of them below pass in a single run:

Swift Errors, confirmations and known issues

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with readLine()), it gets the next line from this box.

Three of these tools deserve a closer look:

  • #expect(throws: Never.self) is the way to say "this must not throw". The test fails if it does, with the error printed.
  • confirmation tests code that calls you back, such as a delegate, a handler or an event. You get a done function, call it where the event would fire, and the framework checks that it was called exactly expectedCount times by the time the closure finishes. It replaces XCTest's expectation objects and does not need a timeout.
  • withKnownIssue wraps a check that you know fails today. The test passes and the report says with 1 known issue, but if the check starts succeeding the test fails, which reminds you to remove the wrapper. Use it instead of commenting out a failing test. The example compares 0.1 + 0.2 with 0.3, which is never equal in floating point (see Foundation numbers).

try #require(...) from the previous lesson unwraps items.first and stops the test at once if it is nil. To record a failure from your own logic, call Issue.record("message").

Migrating from XCTest, and what stays

Swift Testing and XCTest live in the same test target and can be mixed, so you can migrate file by file. Rough translation:

XCTest Swift Testing
class FooTests: XCTestCase struct FooTests (optionally @Suite)
func testBar() @Test func bar()
setUp() / tearDown() init() / deinit
XCTAssertEqual(a, b) #expect(a == b)
XCTUnwrap(x) try #require(x)
XCTAssertThrowsError #expect(throws:)
XCTestExpectation confirmation
XCTSkip .enabled(if:) / .disabled

Do not translate everything. UI tests (XCUIApplication) and performance measurements (measure { }) are not supported by Swift Testing yet and stay in XCTest. Also avoid mixing the two inside one test: call XCTAssert only in XCTest tests and #expect only in Swift Testing tests.

Writing tests that read well

  • Name the behavior, not the method: @Test("discount applies only above 100").
  • One reason to fail per test. Use parameters for variations instead of copy-pasted tests.
  • Keep tests fast and deterministic: inject clocks, random generators and file systems (see Testing for the injection pattern).
  • Group by feature with suites and by purpose with tags (.slow, .integration).
  • Put the interesting value in the failure message: #expect(total == 1000, "cart: \(cart)").

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. How does Swift Testing set up the state a test needs?

    Each test runs on its own suite instance, so stored properties and init act as the fixture and deinit as teardown.
  2. 2. What does @Test(arguments: [1, 2, 3], ["a", "b"]) run?

    Two collections produce their cartesian product. Use zip(...) to pair the elements instead.
  3. 3. What happens to a test using withKnownIssue when the wrapped check starts to pass?

    A known issue is expected to fail. If it no longer does, the test reports that so the workaround is not forgotten.
  4. 4. Which tool replaces XCTest's expectation objects for callback-based code?

    confirmation gives you a closure to call from the callback and checks that it was called the expected number of times.
  5. 5. Which kinds of test should usually stay in XCTest for now?

    Swift Testing does not support XCUIApplication-based UI tests or XCTest's measure blocks.

Summary

  • @Test marks a test; a type holding tests is a suite, instantiated fresh for each test with init as setup and deinit as teardown.
  • @Test(arguments:) runs one function over many inputs; two collections make a product, zip pairs them.
  • Traits (.tags, .disabled, .enabled(if:), .timeLimit, .bug, .serialized) describe and control tests; declare tags with @Tag.
  • Tests run in parallel; make them independent and use .serialized only for truly shared resources.
  • #expect(throws:), #require, confirmation, withKnownIssue and Issue.record cover errors, preconditions, callbacks and unfixed bugs.
  • Keep UI and performance tests in XCTest; the two frameworks can share a target.

Next: App Architecture: MVC, MVVM and Clean Boundaries