Kitty: how tests run, and what they can see

Open the starter

This lesson's project is a new one, small and on its own. Trips waits: lesson 44 gives it a test target of its own. Kitty is the shared kitty of three friends on a long weekend in Lisbon. It shows what each of them paid and where each of them stands — who is owed money, and who owes it.

1. Download Kitty-starter.zip, this lesson's starting point. Double-click it in Finder to unzip it, then double-click Kitty.xcodeproj to open it in Xcode.

2. Run it before changing anything. In the toolbar, open the run destination menu and pick an iPhone simulator — iPhone 17, for example. Choose Product ▸ Run (⌘R). Device Hub opens with the app:

   

Five files. KittyApp.swift is Xcode's. ContentView.swift is the screen: who went, what each of them paid with the total under it, and a line for each friend. BalanceLine.swift is that line, a small view that turns a number of cents into words. Kitty.swift is the model — the friends, the expenses, and each friend's balance: what they paid, less their share of the total. And Money.swift holds the arithmetic, where this lesson begins:

import Foundation

/// A total in cents, split among `count` friends: one share each.
func shares(of cents: Int, among count: Int) -> [Int] {
    let each = (Double(cents) / Double(count)).rounded()
    return Array(repeating: Int(each), count: count)
}

/// Cents as euros, the way the screen writes money: €45.00.
func money(_ cents: Int) -> String {
    (Decimal(cents) / 100).formatted(.currency(code: "EUR"))
}

Money is kept in whole cents, as an Int: €90.00 is 9000. Only money(_:) turns cents into the euros the screen shows. The starter is set up as every project since lesson 15 — Swift 6, Default Actor Isolation set to nonisolated, Approachable Concurrency off — so Kitty says @MainActor itself, because the screen reads it.

Look at the screen once more. Ana is owed €41.67, Ben owes €38.33 and Cleo owes €3.33. Every number looks right. Keep them in mind.

Where tests live, and what ⌘U does

Tests are not part of the app. They live in a target of their own, a test bundle, which is built beside the app and never ships with it. Xcode's template for one is the Unit Testing Bundle, and its Testing System can be Swift Testing — Apple's framework of @Test functions and #expect, which since Xcode 16 replaces XCTest for new tests. Lesson 1 chose it when it made Peek; here you add a test target to a project that has none, which is the more usual case.

1. In Xcode, choose File ▸ New ▸ Target….

2. In the Test section of the templates, choose Unit Testing Bundle, and click Next.

3. Set Testing System: to Swift Testing. Xcode fills in Product Name: with KittyTests and Target to be Tested: with Kitty; leave them as they are. Click Finish.

Xcode adds a folder, KittyTests, beside Kitty, holding KittyTests.swift:

import Testing

struct KittyTests {

    @Test func example() async throws {
        // Write your test here and use APIs like `#expect(...)` to check expected conditions.
        // Swift Testing Documentation
        // https://developer.apple.com/documentation/testing
    }

}

A new target comes with Xcode's own settings, whatever the app's are: Swift 5, and Approachable Concurrency on. Give it Kitty's three, so that its code is checked as strictly as the code it tests — select the KittyTests target, open Build Settings, and set:

Build setting of KittyTests Swift Language Version: Swift 6 SWIFT_VERSION = 6.0

Build setting of KittyTests Default Actor Isolation: nonisolated SWIFT_DEFAULT_ACTOR_ISOLATION = nonisolated

Build setting of KittyTests Approachable Concurrency: No SWIFT_APPROACHABLE_CONCURRENCY = NO

Choose Product ▸ Test (⌘U). Xcode builds the app and the tests, and runs every test:

✓ KittyTests › example(): passed (0.000 s)

One test, and it passed, having checked nothing. What did ⌘U do to get there? It built two products, Kitty.app and KittyTests.xctest. Then it started Kitty in the simulator, as ⌘R does, and loaded the test bundle into Kitty's own process. The tests ran there, inside the app. The template set that up when it chose Kitty as the target to be tested: Kitty is the tests' host, the app they run in.

That is how the tests can call the app's code at all. The bundle is linked against Kitty's own executable, the one it is loaded into — the template set the target's build settings TEST_HOST and BUNDLE_LOADER to it — and @testable import Kitty lets it see what is only internal, which in an app is nearly everything. It has a cost worth knowing, too. Whatever Kitty does as it starts — a network request in its first screen's .task, a write to its files — it does on every ⌘U, before the first test. An edge case below proves it.

You can see it from a test. Replace the template's test with one that looks around. In KittyTests.swift:

import Testingimport UIKit@testable import Kittystruct KittyTests {    @Test func example() async throws {        // Write your test here and use APIs like `#expect(...)` to check expected conditions.        // Swift Testing Documentation        // https://developer.apple.com/documentation/testing    /// Unit tests run inside the app: by now Kitty has started, and its window is up.    @MainActor    @Test func theAppIsRunning() {        #expect(Bundle.main.bundleIdentifier == "com.example.Kitty")        #expect(UIApplication.shared.connectedScenes.count == 1)    }}

import Testing
import UIKit
@testable import Kitty

struct KittyTests {
    /// Unit tests run inside the app: by now Kitty has started, and its window is up.
    @MainActor
    @Test func theAppIsRunning() {
        #expect(Bundle.main.bundleIdentifier == "com.example.Kitty")
        #expect(UIApplication.shared.connectedScenes.count == 1)
    }
}

Run the tests (⌘U):

✓ KittyTests › theAppIsRunning(): passed (0.000 s)

Bundle.main is Kitty's bundle, not the tests', and Kitty's window is up: one scene is connected. UIApplication belongs to the main actor, so the test says @MainActor; a test that says nothing belongs to no actor, as everything in this project does.

A first test, and the cent it finds

Now a real test, of the arithmetic. The cheapest tests check a function with no screen and no model behind it: numbers in, numbers out. The first thing to check about splitting a bill is that the shares add up to the bill. In the Project navigator, select the KittyTests folder, make a new Swift File named SplitTests, and replace everything in it:

import Testing
@testable import Kitty

/// The arithmetic of the kitty: numbers in, numbers out — no model, no screen.
struct SplitTests {
    @Test func sharesAddUpToTheTotal() {
        let split = shares(of: 14500, among: 3)
        #expect(split.reduce(0, +) == 14500)
    }
}

Run the tests:

✓ KittyTests › theAppIsRunning(): passed (0.000 s)
✗ SplitTests › sharesAddUpToTheTotal(): failed (0.002 s)
    Expectation failed: split.reduce(0, +) == 14500
    split.reduce(0, +) → 14499

The shares come to €144.99, not €145.00. €145.00 among three is €48.333…; the starter rounds that to €48.33 for each friend, and the third of a cent each, three times over, is lost. The screen hid it, because every number on it is right to the cent on its own — only the sum is wrong. That is the kind of mistake a test is for.

Read what the failure says. #expect printed the expression as you wrote it, and under it the value of its left side: split.reduce(0, +) → 14499. You did not write a message, and nothing needed formatting by hand. Step 4 shows how #expect knows.

Fix the arithmetic: divide in whole cents, and give the cents that are left over, one each, to the first shares. In Money.swift:

/// A total in cents, split among `count` friends: one share each./// A total in cents, split among `count` friends: one share each. The cents that do not divide evenly go one each to/// the first shares, so that the shares always add up to the total.func shares(of cents: Int, among count: Int) -> [Int] {    let each = (Double(cents) / Double(count)).rounded()    return Array(repeating: Int(each), count: count)    let each = cents / count    let left = cents % count    return (0..<count).map { $0 < left ? each + 1 : each }}

/// A total in cents, split among `count` friends: one share each. The cents that do not divide evenly go one each to
/// the first shares, so that the shares always add up to the total.
func shares(of cents: Int, among count: Int) -> [Int] {
    let each = cents / count
    let left = cents % count
    return (0..<count).map { $0 < left ? each + 1 : each }
}

One total and one number of friends proves little. A test can take arguments: @Test(arguments:) runs it once for every argument, and with two collections, once for every combination of the two — here, every total with every size of group: nine cases. In SplitTests.swift, add a second test:

/// The arithmetic of the kitty: numbers in, numbers out — no model, no screen.struct SplitTests {    @Test func sharesAddUpToTheTotal() {        let split = shares(of: 14500, among: 3)        #expect(split.reduce(0, +) == 14500)    }    @Test(arguments: [1, 1000, 14500], [2, 3, 4])    func sharesAddUpForAnyKitty(cents: Int, friends: Int) {        #expect(shares(of: cents, among: friends).reduce(0, +) == cents)    }}

/// The arithmetic of the kitty: numbers in, numbers out — no model, no screen.
struct SplitTests {
    @Test func sharesAddUpToTheTotal() {
        let split = shares(of: 14500, among: 3)
        #expect(split.reduce(0, +) == 14500)
    }

    @Test(arguments: [1, 1000, 14500], [2, 3, 4])
    func sharesAddUpForAnyKitty(cents: Int, friends: Int) {
        #expect(shares(of: cents, among: friends).reduce(0, +) == cents)
    }
}

Run the tests:

✓ KittyTests › theAppIsRunning(): passed (0.000 s)
✓ SplitTests › sharesAddUpToTheTotal(): passed (0.000 s)
✓ SplitTests › sharesAddUpForAnyKitty(cents:friends:): passed (0.001 s)
    ✓ 1, 2: passed
    ✓ 1, 3: passed
    ✓ 1, 4: passed
    ✓ 1000, 2: passed
    ✓ 1000, 3: passed
    ✓ 1000, 4: passed
    ✓ 14500, 2: passed
    ✓ 14500, 3: passed
    ✓ 14500, 4: passed

Each case is reported on its own, so a failure would name the total and the group that broke. The extra cent goes to Ana, who is first in the list. Run the app (⌘R) to see the change on the screen:

How a test is found, and how a failure knows

XCTest finds its tests at run time by asking the Objective-C runtime for every subclass of XCTestCase, and for each class's methods whose names begin with test. Swift Testing has no runtime to ask: a struct has no Objective-C metadata, and a test can be a global function. So the work is done when the test is compiled, by the macro. Here is what @Test wrote beside sharesAddUpToTheTotal(), from the compiler's own expansion:

struct SplitTests {
    @Test func sharesAddUpToTheTotal() {
        let split = shares(of: 14500, among: 3)
        #expect(split.reduce(0, +) == 14500)
    }

    // 1. A function that runs the test: it makes a new SplitTests, and calls the method on it.
    @Sendable private static func b8db9354bbb01c19() async throws -> Void {
      @Sendable func __local(_:isolated (any _Concurrency.Actor)?=Testing.__defaultSynchronousIsolationContext) async throws {
        let __local = unsafe try await Testing.__requiringUnsafe(Testing.__requiringTry(Testing.__requiringAwait(SplitTests())))
        _ = unsafe try await Testing.__requiringUnsafe(Testing.__requiringTry(Testing.__requiringAwait(__local.sharesAddUpToTheTotal())))
      }
      try await __local()
    }

    // 2. A function that describes it: its name, its suite, and the function above.
    @Sendable private static func generator() async -> Testing.Test {
      return .__function(
      named: "sharesAddUpToTheTotal()",
      in: SplitTests.self,
      // (and its traits, and where it is in the file)
      testFunction: b8db9354bbb01c19
    )
    }

    // 3. A record that points at that description, in a section of the app's binary set aside for tests.
    @section("__DATA_CONST,__swift5_tests")
    @used
    private nonisolated static let testContentRecord: Testing.__TestContentRecord = (
      0x74657374, /* 'test' */
      0,
      { outValue, type, _, _ in
        Testing.Test.__store(generator, into: outValue, asTypeAt: type)
      },
      0,
      0
    )

    // …and the same three for sharesAddUpForAnyKitty(cents:friends:)
}

Three things, and each answers a question an interviewer may ask.

And #expect, which is also a macro. It does not receive true or false, as XCTAssert does. It receives the expression, and takes it apart:

@Test func sharesAddUpToTheTotal() {
    let split = shares(of: 14500, among: 3)
    Testing.__checkBinaryOperation(split.reduce(0, +),{ $0 == $1() },14500,
        expression: .__fromBinaryOperation(.__fromSyntaxNode("split.reduce(0, +)"),"==",.__fromSyntaxNode("14500")),
        comments: [],
        isRequired: false,
        sourceLocation: Testing.SourceLocation.__here()).__expected()
}

Both sides of the == are passed separately, with the operator between them as a closure, and with the text of each side as you wrote it. So when the check fails, Swift Testing has the expression, the value of each side and the line it is on — everything the failure in step 3 printed. isRequired: false and .__expected() at the end are what make #expect record a failure and carry on. try #require(count == 1) expands to the same call with isRequired: true and .__required(), which throws when the check fails — and the thrown error ends the test.

Testing what the screen shows: the model

A SwiftUI screen is drawn from its model, so a test of the model is a test of what the screen will say. Kitty holds the logic that matters: the total, and each friend's balance. Test it with no screen at all. In KittyTests.swift, add three tests for the model, and keep the one that looks around:

import Testingimport UIKit@testable import Kitty/// The model the screen reads, tested without the screen.struct KittyTests {    let kitty = Kitty.lisbon        // made again for every test    @Test func payingRaisesYourBalance() {        let before = kitty.balance(of: "Ben")        kitty.add("Coffee", cents: 450, paidBy: "Ben")        #expect(kitty.balance(of: "Ben") == before + 300)    }    @Test func totalIsEverythingPaid() {        #expect(kitty.total == 14500)    }    @Test func balancesAddUpToZero() {        let balances = kitty.people.map { kitty.balance(of: $0) }        #expect(balances.reduce(0, +) == 0)    }    /// Unit tests run inside the app: by now Kitty has started, and its window is up.    @MainActor    @Test func theAppIsRunning() {        #expect(Bundle.main.bundleIdentifier == "com.example.Kitty")        #expect(UIApplication.shared.connectedScenes.count == 1)    }}

import Testing
import UIKit
@testable import Kitty

/// The model the screen reads, tested without the screen.
struct KittyTests {
    let kitty = Kitty.lisbon        // made again for every test

    @Test func payingRaisesYourBalance() {
        let before = kitty.balance(of: "Ben")
        kitty.add("Coffee", cents: 450, paidBy: "Ben")
        #expect(kitty.balance(of: "Ben") == before + 300)
    }

    @Test func totalIsEverythingPaid() {
        #expect(kitty.total == 14500)
    }

    @Test func balancesAddUpToZero() {
        let balances = kitty.people.map { kitty.balance(of: $0) }
        #expect(balances.reduce(0, +) == 0)
    }

    /// Unit tests run inside the app: by now Kitty has started, and its window is up.
    @MainActor
    @Test func theAppIsRunning() {
        #expect(Bundle.main.bundleIdentifier == "com.example.Kitty")
        #expect(UIApplication.shared.connectedScenes.count == 1)
    }
}

Run the tests:

They do not compile. Xcode reports

main actor-isolated default value in a nonisolated context

One error, at the first line that touches the model. Kitty.lisbon belongs to the main actor, as everything of Kitty's does, because the screen reads it. The suite belongs to no actor, because in this project nothing is on an actor unless it says so — the test target included. So the compiler refuses to make the property's default value there, exactly as it would in the app, and the calls in the tests would be refused for the same reason. Put the suite on the main actor, as the model is — and the one test that said @MainActor no longer needs to:

import Testingimport UIKit@testable import Kitty/// The model the screen reads, tested without the screen./// The model the screen reads, tested without the screen. It belongs to the main actor, so its tests do too.@MainActorstruct KittyTests {    let kitty = Kitty.lisbon        // made again for every test    @Test func payingRaisesYourBalance() {        let before = kitty.balance(of: "Ben")        kitty.add("Coffee", cents: 450, paidBy: "Ben")        #expect(kitty.balance(of: "Ben") == before + 300)    }    @Test func totalIsEverythingPaid() {        #expect(kitty.total == 14500)    }    @Test func balancesAddUpToZero() {        let balances = kitty.people.map { kitty.balance(of: $0) }        #expect(balances.reduce(0, +) == 0)    }    /// Unit tests run inside the app: by now Kitty has started, and its window is up.    @MainActor    @Test func theAppIsRunning() {        #expect(Bundle.main.bundleIdentifier == "com.example.Kitty")        #expect(UIApplication.shared.connectedScenes.count == 1)    }}

import Testing
import UIKit
@testable import Kitty

/// The model the screen reads, tested without the screen. It belongs to the main actor, so its tests do too.
@MainActor
struct KittyTests {
    let kitty = Kitty.lisbon        // made again for every test

    @Test func payingRaisesYourBalance() {
        let before = kitty.balance(of: "Ben")
        kitty.add("Coffee", cents: 450, paidBy: "Ben")
        #expect(kitty.balance(of: "Ben") == before + 300)
    }

    @Test func totalIsEverythingPaid() {
        #expect(kitty.total == 14500)
    }

    @Test func balancesAddUpToZero() {
        let balances = kitty.people.map { kitty.balance(of: $0) }
        #expect(balances.reduce(0, +) == 0)
    }

    /// Unit tests run inside the app: by now Kitty has started, and its window is up.
    @Test func theAppIsRunning() {
        #expect(Bundle.main.bundleIdentifier == "com.example.Kitty")
        #expect(UIApplication.shared.connectedScenes.count == 1)
    }
}

Run the tests:

✓ KittyTests › payingRaisesYourBalance(): passed (0.000 s)
✓ KittyTests › totalIsEverythingPaid(): passed (0.000 s)
✓ KittyTests › balancesAddUpToZero(): passed (0.000 s)
✓ KittyTests › theAppIsRunning(): passed (0.000 s)
✓ SplitTests › sharesAddUpToTheTotal(): passed (0.000 s)
✓ SplitTests › sharesAddUpForAnyKitty(cents:friends:): passed (0.001 s)
    ✓ 1, 2: passed
    ✓ 1, 3: passed
    ✓ 1, 4: passed
    ✓ 1000, 2: passed
    ✓ 1000, 3: passed
    ✓ 1000, 4: passed
    ✓ 14500, 2: passed
    ✓ 14500, 3: passed
    ✓ 14500, 4: passed

Each test begins with a new Kitty.lisbon, because each test gets a new KittyTests and the property is made with it. The coffee that payingRaisesYourBalance() adds is never seen by totalIsEverythingPaid(), whichever runs first. That is the whole of set-up in Swift Testing: a stored property, or an init. A suite that is a class or an actor can also have a deinit, which runs after each test, for tearing down.

One more thing to know about running these. With Xcode's own settings, Swift Testing runs the tests of a suite at the same time, as tasks in the one process. A suite on the main actor still takes turns on the main actor, but a plain suite's tests really overlap. So tests must not share anything they change: a static property, a file, a UserDefaults key. Swift 6 refuses a global var that is not isolated, which catches the commonest case. When tests must share something that cannot be split up, mark their suite @Suite(.serialized), and its tests run one at a time. An edge case below shows both.

Testing a view, and what a test cannot see

A view is a struct, and a test can make one: BalanceLine(person: "Ana", cents: 4166). What the test can read is whatever the struct offers as plain Swift: its stored properties, and its computed ones. BalanceLine keeps the words it shows in words, so they can be checked without drawing anything. In the KittyTests folder, make a new Swift File named BalanceLineTests, and replace everything in it:

import Testing
@testable import Kitty

/// A view is a struct: a test can make one, and read what it says before anything is drawn.
@MainActor
struct BalanceLineTests {
    @Test func owedMoney() {
        #expect(BalanceLine(person: "Ana", cents: 4166).words == "Ana is owed €41.66")
    }

    @Test func owesMoney() {
        #expect(BalanceLine(person: "Ben", cents: -3833).words == "Ben owes €38.33")
    }

    @Test func square() {
        #expect(BalanceLine(person: "Cleo", cents: 0).words == "Cleo is square")
    }
}

Run the tests:

✓ BalanceLineTests › owedMoney(): passed (0.000 s)
✓ BalanceLineTests › owesMoney(): passed (0.000 s)
✓ BalanceLineTests › square(): passed (0.000 s)
✓ KittyTests › payingRaisesYourBalance(): passed (0.000 s)
✓ KittyTests › totalIsEverythingPaid(): passed (0.000 s)
✓ KittyTests › balancesAddUpToZero(): passed (0.000 s)
✓ KittyTests › theAppIsRunning(): passed (0.000 s)
✓ SplitTests › sharesAddUpToTheTotal(): passed (0.000 s)
✓ SplitTests › sharesAddUpForAnyKitty(cents:friends:): passed (0.001 s)
    ✓ 1, 2: passed
    ✓ 1, 3: passed
    ✓ 1, 4: passed
    ✓ 1000, 2: passed
    ✓ 1000, 3: passed
    ✓ 1000, 4: passed
    ✓ 14500, 2: passed
    ✓ 14500, 3: passed
    ✓ 14500, 4: passed

A View belongs to the main actor — the protocol says so — so these tests say @MainActor too. That is as far as a unit test goes into a view, and it is worth knowing exactly where it stops.

So the habit that makes SwiftUI testable is to keep views thin: decisions go into the model, into functions, and into plain properties like words, where a unit test can reach them in milliseconds. What is left in body is layout, and layout is checked in other ways — by eye in previews while you work, by a test that draws the view into a picture, and by a UI test that drives the running app. Lesson 47 does both of the last two, on Trips.

XCTest, beside it

XCTest is the framework every iOS test was written in until 2024, and most projects still have its tests. It runs in the same target as Swift Testing, and ⌘U runs both. Write the first test again in XCTest's way, to see the difference. In the KittyTests folder, make a new Swift File named SplitXCTests, and replace everything in it:

import XCTest
@testable import Kitty

/// The first test again, as XCTest writes it: a class, a method whose name begins with `test`, and an assertion function.
final class SplitXCTests: XCTestCase {
    func testSharesAddUpToTheTotal() {
        XCTAssertEqual(shares(of: 14500, among: 3).reduce(0, +), 14500)
    }
}

Run the tests:

✓ SplitXCTests › testSharesAddUpToTheTotal(): passed (0.003 s)
✓ BalanceLineTests › owedMoney(): passed (0.001 s)
✓ BalanceLineTests › owesMoney(): passed (0.000 s)
✓ BalanceLineTests › square(): passed (0.000 s)
✓ KittyTests › payingRaisesYourBalance(): passed (0.000 s)
✓ KittyTests › totalIsEverythingPaid(): passed (0.000 s)
✓ KittyTests › balancesAddUpToZero(): passed (0.000 s)
✓ KittyTests › theAppIsRunning(): passed (0.000 s)
✓ SplitTests › sharesAddUpToTheTotal(): passed (0.000 s)
✓ SplitTests › sharesAddUpForAnyKitty(cents:friends:): passed (0.001 s)
    ✓ 1, 2: passed
    ✓ 1, 3: passed
    ✓ 1, 4: passed
    ✓ 1000, 2: passed
    ✓ 1000, 3: passed
    ✓ 1000, 4: passed
    ✓ 14500, 2: passed
    ✓ 14500, 3: passed
    ✓ 14500, 4: passed

Both frameworks, one run. Side by side:

XCTest is still the only way to do two things: drive the running app from outside, with XCUIApplication, and measure performance, with measure(metrics:). So a project keeps both. New unit tests are written with @Test; UI tests stay in XCTest, in their own target. Since Swift 6.4 the two even report each other's failures: in a new project an XCTAssertEqual that fails inside a @Test fails it, and so does an #expect inside an XCTestCase — an edge case and a card below show each.