skip to content

Swift Testing tests that pass one at a time fail when the whole target runs; why does parallel execution cause this, and what does .serialized fix and not fix?

level: seniorimportance: should knowfreq 45%

answer

  1. same process, many tasks at once
  2. fresh suite instance per test
  3. globals, singletons, standard defaults
  4. serial inside the suite only

basics

~20 s

Swift Testing runs tests and parameterized cases in parallel by default, in one process, so tests sharing global state race. .serialized orders one suite's tests but not tests elsewhere; per-test state is the real fix.

solid answer

~50 s

Swift Testing runs tests in parallel by default, using task groups inside one process, so two tests that touch the same global state (a singleton cache, `UserDefaults.standard`, a file in Caches, a static variable) can interleave and fail only when the full target runs. Each instance-method test already gets a fresh suite instance, so instance properties are not the problem; shared state outside the instance is. `@Suite(.serialized)` makes the tests inside that suite, and the cases of its parameterized tests, run one at a time, but it does **not** stop tests in other suites from running alongside them, and on a test without arguments it has no effect (the compiler warns). The durable fix is to give each test its own state: create it in the suite's `init()` and clean it up in `deinit` of a class or actor suite.

code

swift · 31 lines
swift
import Foundation
import Testing

struct DisplayCurrency {
    let defaults: UserDefaults
    var code: String { defaults.string(forKey: "displayCurrency") ?? "USD" }
    func set(_ code: String) { defaults.set(code, forKey: "displayCurrency") }
}

final class DisplayCurrencyTests {
    let suiteName = "DisplayCurrencyTests.\(UUID().uuidString)"
    let defaults: UserDefaults

    init() throws {                 // runs before each test, on a fresh instance
        defaults = try #require(UserDefaults(suiteName: suiteName))
    }

    deinit {                        // runs after each test
        defaults.removePersistentDomain(forName: suiteName)
    }

    @Test func defaultsToUSD() {
        #expect(DisplayCurrency(defaults: defaults).code == "USD")
    }

    @Test func remembersChoice() {
        let preference = DisplayCurrency(defaults: defaults)
        preference.set("EUR")
        #expect(preference.code == "EUR")
    }
}

go deeper

for a junior

Recall that Swift Testing runs tests in parallel by default and that .serialized exists to make a suite's tests run one at a time.

for a middle

Explain the fresh-instance-per-test rule, why init() and deinit replace set-up and tear-down hooks, and why teardown needs a class or actor suite.

for a senior

Diagnose the race: find the state that outlives a test, inject it per test, and explain precisely why .serialized on one test or one suite leaves cross-suite races in place.

for a principal

Decide the team's parallel-safety rule, such as no shared singletons in tests and .serialized only with a recorded reason, and weigh it against the cost of keeping CI runs parallel and fast.

## Parallel by default Swift Testing runs tests **in parallel with each other by default**. It uses task groups, and tests generally all run **in the same process**; the Swift runtime decides how many run at once. Parameterized test cases are parallel too. This is a deliberate change from the sequential default many teams are used to, and it is why a test that passes on its own, or when run alone from Xcode, can fail when the whole target runs. The failure mode is always the same: two tests read and write **state that outlives a single test**, and the scheduler interleaves them. A test that sets the display currency to EUR runs while another test asserts the default is USD, and the second test fails, but only sometimes. ## Where the shared state hides Swift Testing already isolates one kind of state: for an instance-method test it creates a **fresh instance of the suite type for every test function**, so stored properties are never shared. The trouble is everything else: - singletons such as a shared rate cache or network session - `UserDefaults.standard`, the keychain, or files at fixed paths - `static var` properties and global variables (Swift 6 language mode flags most unprotected ones at compile time; `nonisolated(unsafe)` silences that check without making them safe) - mock servers or URL protocol registrations installed globally - shared caches and fixed temporary paths, such as one `URLCache` or one scratch directory reused by several suites ## What `.serialized` does | Applied to | Effect | |---|---| | a parameterized `@Test` | that test's cases run one at a time | | a non-parameterized `@Test` | no effect; the compiler emits a warning | | a `@Suite` | its test functions, their cases and nested suites run one at a time, recursively | | any test, with parallelization disabled globally | no additional effect | The key sentence from the documentation: the trait **does not affect the execution of a test relative to its peers or to unrelated tests**. If `DisplayCurrencyTests` is serialized but `OnboardingTests` in another suite also writes `displayCurrency` to `UserDefaults.standard`, the two suites still overlap. Putting `.serialized` on one test function to make it run alone does nothing at all. The heavier switch is turning parallelization off for the whole run, for example `swift test --no-parallel`. That hides every race and slows every run, so treat it as a diagnostic: if a failure disappears with it, you have shared state to find. ## The real fix: state per test 1. Find what the failing tests share, usually by reading what they write rather than what they assert. 2. Inject that dependency instead of reaching for a global. The code under test takes a `UserDefaults`, a cache or a file URL. 3. Create a private instance in the suite's **`init()`**, which runs before each test on the fresh instance. It may be `async` and `throws`. 4. Clean up in **`deinit`**, which runs after each test. A copyable `struct` cannot declare `deinit`, so a suite that needs teardown is a `final class` or an `actor`. 5. Keep `.serialized` for state you cannot isolate yet, and apply it to the suite that owns that state, knowing it only orders that suite's tests. The example creates a uniquely named `UserDefaults` domain per test and removes it in `deinit`, so the tests can run in parallel with each other and with everything else. ## Reading the symptoms - **Passes alone, fails in the full run**: shared state between suites; `.serialized` on one suite will not help. - **Fails only on CI**: more cores, more overlap; the race was always there. - **Different test fails each time**: the interleaving changes; look for a singleton both tests touch. - **Failures vanish with `--no-parallel`**: confirmed ordering dependency; now isolate the state. ## When it cannot be fixed this sprint Sometimes the shared state lives in code the team cannot change yet, such as a third-party SDK's singleton. Then choose deliberately: - **`@Suite(.serialized)` on the suite that owns the state**, with a comment saying why, removes races inside that suite only. - **`withKnownIssue("…", isIntermittent: true)`** around the flaky part keeps the test running and reports its failures as known, without failing the run. - **`.disabled("…")` plus `.bug(…)`** skips the test with a tracker link; nothing runs, so nothing tells you when it is fixed.

  • A flaky rates test cannot be fixed this sprint. Should it get .disabled or be wrapped in withKnownIssue?
    `.disabled("…")` with a `.bug(…)` link skips it, so nothing runs and nobody learns when it starts passing or what else breaks. Wrapping the body in `withKnownIssue("…", isIntermittent: true)` keeps it running and reports failures as known without failing the run. Without `isIntermittent`, a run where no known issue occurs is recorded as an issue, prompting you to remove the wrapper. Prefer `.disabled` only when running the test is harmful or very slow.
  • Why does adding .serialized to the failing test function not help?
    On a test without arguments `.serialized` has no effect, and the compiler warns about it. Even on a suite, it only orders the tests inside that suite; it never stops unrelated tests from running at the same time, so a race with another suite remains.
  • Is swift test --no-parallel an acceptable fix for the team?
    It disables parallel execution for the whole run, which hides the race and makes every run slower. It is a useful experiment: if failures disappear, the tests share state. The fix is still to isolate that state, after which the suite can run in parallel again.

  • All test functions in a suite share one instance, so its properties leak between tests.
  • .serialized on one test function makes it run while nothing else runs.
  • Swift Testing runs each test in its own process, so globals cannot collide.
  • .serialized on a suite also stops other suites from running at the same time.
  • Cleanup can go in deinit of an ordinary copyable struct suite.