Skip to content
Tutorials Center
My learning

Topics

Lesson 118 of 146 ยท Advanced Swift

Testing in Swift

Learn to test Swift code with the Swift Testing framework (@Test, #expect, #require), XCTest, parameterized tests, async tests and a tiny harness you can run here.

A test is a small program that calls your code and checks the answer. It sounds too simple to matter, but tests are what let you change a large program without fear: rename a function, speed up an algorithm or upgrade to a new Swift version, run the tests, and know within seconds whether you broke something.

Swift has two official test frameworks. Swift Testing (the Testing module, introduced with Swift 6) is the modern one: tests are plain functions marked @Test, and you check results with the #expect macro. XCTest is the older framework from the Objective-C days: tests are methods named test... on a subclass of XCTestCase, and you check results with functions like XCTAssertEqual. New code should use Swift Testing; most existing projects still contain XCTest, and some things (UI tests, performance measurements) still need it. Both ship with the toolchain, and both really run on this site, so you will see genuine output from them below.

In a real project you run tests with `swift test` (SwiftPM) or the Test navigator in Xcode, which discover tests for you. On this site the whole program is one `main.swift` file, so we call the framework's entry point by hand. That entry point (`Testing.__swiftPMEntryPoint()`) is an implementation detail of SwiftPM: you will never write it in a real project. Also, the framework prints durations and may run tests in parallel, so the order of lines and the times you see will differ from run to run.

What makes code easy to test

Before any framework, the key idea: test small pieces that take input and return output. A function like slugify(_:) that turns a title into a URL fragment is trivial to test. A function that reads a file, calls a server and prints a result is not. So the best way to make code testable is to design it as in the earlier lessons: pure functions, value types, small protocols for the things that touch the outside world (clock, network, file system), and errors you can inspect (see errors and typed throws).

A test harness in 30 lines

You can understand what any test framework does by writing a tiny one. A test is a named closure that either returns normally (pass) or throws (fail). A runner executes them all, catches the failures and prints a summary:

Swift A hand-written test harness

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.

Everything real frameworks do is an extension of this: discover the tests automatically, run them in parallel, give richer messages, and group them in suites. Note the two Swift features doing the work: @autoclosure delays evaluating the condition until expect decides to, and the default argument #line captures the line of the caller, so the failure points at the test and not at the helper.

Swift Testing: @Test and #expect

With Swift Testing you import Testing, mark a function with @Test, and write #expect(...) with an ordinary Swift expression. Group related tests in a struct or class marked @Suite. A suite is created fresh for each test, so tests cannot leak state into each other through stored properties.

Swift Swift Testing: a real run

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.

Read the output from the bottom: the last line says Test run with 6 tests in 2 suites passed. Six, not eight, because the parameterized edgeCases test counts once, and the line above it shows it ran three test cases (with 3 test cases passed). The things to learn from this example:

  • @Test("display name") gives a human-readable name; the function name is used if you leave it out.
  • @Test(arguments:) runs the same function once per argument. This is the Swift Testing answer to the "loop over a table of cases" pattern, and each case is reported separately, so one bad row does not hide the others. Tuples are unpacked into the parameters.
  • #expect(throws:) checks that a block throws a specific error. Because parseAge uses typed throws, the closure is checked at compile time.
  • Tests can be async and throws. If a throwing test throws, the test fails with that error.
  • Output order differs between runs: tests run in parallel by default. Add .serialized to a suite if they must run one at a time.

What a failure looks like

#expect is a macro, so it can look inside the expression and report the value of each part. That is why Swift Testing needs just one assertion where XCTest needs a dozen. A failing test also exits with a non-zero code, which the page shows under the output. There is a second tool, #require, which stops the test when its condition fails (or an optional is nil) and also unwraps optionals:

Swift Failing expectations and #require (fails on purpose)

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.

Two lines in the output are worth reading closely. The first failing line ends with Expectation failed: (cart.total โ†’ 950) == 1000: the framework shows the actual value of the sub-expression (950) next to the code, so you rarely need a debugger to see what went wrong. The second ends with (cart.prices โ†’ []).first โ†’ nil โ†’ nil: #require found nil, so the test stopped there and #expect(first > 0) never ran. Note that the first test kept going after its failure and checked the second #expect too; use #require when later lines make no sense after a failure.

Use these in practice:

Tool Use it when
#expect(a == b) A normal check. The test continues if it fails.
try #require(x) A precondition for the rest of the test; unwraps optionals.
#expect(throws: E.self) { ... } The code must throw.
#expect(throws: Never.self) { ... } The code must not throw.
Issue.record("message") Fail the test from your own logic.

XCTest: the original framework

XCTest is still everywhere, so you must be able to read it. A test case is a subclass of XCTestCase; every method whose name starts with test is a test; checks are global functions such as XCTAssertEqual, XCTAssertTrue, XCTAssertNil and XCTAssertThrowsError. setUp() and tearDown() run before and after each test.

On Apple platforms and in SwiftPM the runner finds the tests for you. On Linux without SwiftPM, as here, you can register them by hand and call XCTMain:

Swift XCTest: a real run (fails on purpose)

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 output prints a timestamp for every suite, which is why it changes on every run. The line to look for is the failure message with this shape: error: PalindromeTests.testWrongOnPurpose : XCTAssertEqual failed: ("false") is not equal to ("true") - abc is not a palindrome, and the summary Executed 4 tests, with 1 failure. XCTest tells you both values only as strings, and you need a separate assert function for each kind of comparison. The explicit list of tests with closures exists only because we run outside SwiftPM; in a package you write just the class and the methods.

XCTest Swift Testing
subclass of XCTestCase, methods named test... @Test on any function, in a struct, class or at file level
XCTAssertEqual(a, b), XCTAssertTrue(c), ... #expect(a == b), #expect(c)
try XCTUnwrap(x) try #require(x)
XCTAssertThrowsError #expect(throws:)
loops over data @Test(arguments:)
setUp() / tearDown() init() / deinit of the suite type
UI tests and measure {} not yet: keep using XCTest

You can mix both frameworks in one test target, so migrate gradually.

Writing good tests

A framework does not make tests good. Habits that do:

  • Name the behavior, not the method. emptyCartHasNoDiscount tells you what broke; testCalculate2 does not.
  • One idea per test. Arrange the input, act by calling the code, assert the outcome. If you need many asserts for one idea, that is fine; if a test checks five ideas, split it.
  • Test the edges. Empty input, one element, negative numbers, Int.max, a string with emoji, a duplicate key. Bugs live at boundaries.
  • Keep tests independent and deterministic. No shared mutable globals, no real clock, no random numbers without a fixed seed (see seeded randomness), no network. A test that fails one run in twenty is worse than no test.
  • Inject what you cannot control. Replace the real clock or service with a small fake that conforms to the same protocol:
Swift Testing with an injected clock

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 production code passes a clock that reads the system time; the test passes FixedClock. The same idea works for anything with side effects.

Tests in a package (read-only)

On your own machine, tests live in a test target of a Swift package. This is a read-only example because it needs SwiftPM (see Swift Package Manager):

TEXT
MyLibrary/
โ”œโ”€โ”€ Package.swift
โ”œโ”€โ”€ Sources/
โ”‚   โ””โ”€โ”€ MyLibrary/
โ”‚       โ””โ”€โ”€ Slug.swift
โ””โ”€โ”€ Tests/
    โ””โ”€โ”€ MyLibraryTests/
        โ””โ”€โ”€ SlugTests.swift
Swift
// Tests/MyLibraryTests/SlugTests.swift (read-only example)
import Testing
@testable import MyLibrary

@Suite struct SlugTests {
    @Test func basic() {
        #expect(slugify("Hello Swift") == "hello-swift")
    }
}
Terminal
# read-only example: run in a terminal on your machine
swift test
swift test --filter SlugTests

@testable import gives the test target access to internal declarations of the module, which is how you test code that is not part of the public API (see access control). Features not shown here but worth knowing: .tags(...) to group tests across suites, .enabled(if:) and .disabled("reason") to skip tests conditionally, confirmation { } to test callbacks, and withKnownIssue { } to mark a bug you know about so it does not fail the build.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. What does the #expect macro report when cart.total == 1000 fails?

    Because #expect is a macro it can capture the pieces of the expression, so the failure message includes the actual values.
  2. 2. What is the difference between #expect and #require?

    Use #require for a precondition the rest of the test depends on. A failed #expect is recorded but the test keeps running.
  3. 3. How do you run the same Swift Testing function with several inputs?

    The arguments collection is passed to the function one element at a time, and every case is reported separately.
  4. 4. Why does the expect helper in the hand-written harness take the condition as @autoclosure, and line: Int = #line?

    The default argument #line is evaluated at the call site, so a failure points at the test line. Autoclosure lets the helper decide when to evaluate the expression.
  5. 5. Which is a good way to make time-dependent code testable?

    Injecting the dependency lets tests control the value and keeps them deterministic and fast.

Summary

  • A test calls code and checks the result; a failing test should say what was expected and what was found.
  • Swift Testing (import Testing) uses @Test, @Suite, #expect, #require and @Test(arguments:); tests may be async and throws and run in parallel.
  • XCTest uses XCTestCase subclasses and XCTAssert... functions; it is still needed for UI tests and performance measurement.
  • A test framework is a loop over throwing closures; the hand-written harness shows the idea and runs anywhere.
  • Test behavior, edges and errors; keep tests deterministic and independent; inject clocks, files and networks through protocols.
  • In real projects use test targets in a package and swift test (see the next lessons).

Next: Swift Package Manager