Sanniv Khare 7 min read

XCTest to Swift Testing on Swift 6.4: a porting guide

XCTest to Swift Testing on Swift 6.4: a porting guide

Swift 6.4 (released 15 Sep 2026) is the first version where a half-ported test target is safe. Under ST-0021, an XCTAssert inside a Swift Testing @Test no longer passes silently, and #expect inside an XCTestCase now reports. So port file by file, keep the suite green between commits, and raise the interop mode as you go: limited, then complete, then strict.

How much of the work is mechanical? We counted every XCTest call in the test targets of five Apple open-source packages on their main branches (18 Nov 2026). In swift-nio, 10,051 of 10,469 calls (96%) have a one-line replacement in Apple’s mapping table; in swift-algorithms, all 313 do. The rest is expectations, skips and project-specific helpers, and that is where the time goes.

Why we did this: the native iOS modules of our banking apps and both of our Mac apps, Nix and QuitAll, still carry XCTest targets, and new tests should not be written in a framework we plan to leave.

What Swift 6.4 changed

Before 6.4, mixing the two frameworks was a trap. ST-0021 describes the old behaviour as a false negative: an XCTAssert in a Swift Testing test was a no-op, and so was #expect in an XCTest. Swift 6.4’s release post puts the fix in one line: “You can now safely use XCTAssert in Swift Testing tests or #expect within XCTests (ST-0021).”

The behaviour is set by an interop mode:

Mode XCTest API inside a @Test
none Ignored, as before 6.4
limited Reported as a runtime warning issue
complete Reported as a failure
strict Any XCTest API use is a fatal error

Which mode you get by default depends on the toolchain and your package’s tools version, per Apple’s migration article: a toolchain older than 6.4 gives none; a 6.4 toolchain with swift-tools-version below 6.4 gives limited; 6.4 with 6.4 gives complete. You can override it with the SWIFT_TESTING_XCTEST_INTEROP_MODE environment variable. The proposal says strict may become the default in a future release.

None of the five packages we cloned declares tools version 6.4 yet (swift-nio 6.1, swift-argument-parser 6.0, swift-log 6.2), so on a 6.4 toolchain they all run in limited mode. Most existing apps will be in the same place.

The assertion mapping

This is Apple’s table from “Migrating a test from XCTest”: each XCTest call as a comment, its Swift Testing form below it.

// XCTAssert(x), XCTAssertTrue(x)
  #expect(x)
// XCTAssertFalse(x)
  #expect(!x)
// XCTAssertNil(x)
  #expect(x == nil)
// XCTAssertNotNil(x)
  #expect(x != nil)
// XCTAssertEqual(x, y)
  #expect(x == y)
// XCTAssertNotEqual(x, y)
  #expect(x != y)
// XCTAssertIdentical(x, y)
  #expect(x === y)
// XCTAssertNotIdentical(x, y)
  #expect(x !== y)
// XCTAssertGreaterThan(x, y)
  #expect(x > y)
// XCTAssertGreaterThanOrEqual(x, y)
  #expect(x >= y)
// XCTAssertLessThanOrEqual(x, y)
  #expect(x <= y)
// XCTAssertLessThan(x, y)
  #expect(x < y)
// XCTAssertThrowsError(try f())
  #expect(throws: (any Error).self) {
    try f()
  }
// XCTAssertNoThrow(try f())
  #expect(throws: Never.self) {
    try f()
  }
// try XCTUnwrap(x)
  try #require(x)
// XCTFail("...")
  Issue.record("...")

The gap Apple names: there is no equivalent of XCTAssertEqual(_:_:accuracy:). Use isApproximatelyEqual() from swift-numerics. swift-nio has two of those calls.

Around the assertions, the structure changes too:

XCTest Swift Testing
XCTestCase subclass a type, @Suite optional
setUp() init()
tearDown() deinit (class or actor only)
func testX() @Test func x()
stop at the first failure #require
XCTestExpectation confirmation()
XCTSkip .enabled(if:), .disabled(if:)
XCTExpectFailure withKnownIssue
XCTAttachment Attachment.record

Every row is from Apple’s article. One behaviour change hides in it: Swift Testing runs tests in parallel by default, where XCTest ran them in order. A suite that shares state needs @Suite(.serialized).

One XCTest test ported to Swift Testing

The same test before and after. Treat it as a pattern to adapt and compile against your own target.

How much real code the table covers

We wrote a 19-line counter that walks a package’s test folders, strips comments, and counts each XCTest form plus the files that import each framework:

#!/usr/bin/env python3
"""Count XCTest forms and Swift Testing use in Swift test files."""
import re, sys, pathlib, collections
FORMS = (r"XCTAssert\w*|XCTUnwrap|XCTFail|XCTSkip\w*|XCTExpectFailure"
         r"|XCTestExpectation|expectation\(|wait\(for:|fulfillment\(of:"
         r"|measure\w*\s*[({]|XCUIApplication")
total = collections.Counter()
files = st = 0
for p in pathlib.Path(sys.argv[1]).rglob("*.swift"):
    if "Tests" not in p.parts and not p.parent.name.endswith("Tests"):
        continue
    t = re.sub(r"//.*", "", p.read_text(errors="ignore"))
    if "XCTest" in t: files += 1
    if "import Testing" in t: st += 1
    for m in re.findall(FORMS, t):
        total[re.sub(r"[\s({]+$", "", m)] += 1
print(f"files importing XCTest: {files}, importing Testing: {st}")
for k, v in total.most_common():
    print(f"{v:6d}  {k}")
Counting XCTest forms in swift-algorithms

swift-algorithms is the easy case: 313 calls, every one of them in Apple’s table.

What the five packages showed, at their main commits on 18 Nov 2026:

Package State What is left
swift-algorithms (8fdd7fe) 28 XCTest files, 0 Swift Testing 313 calls, all mechanical
swift-nio (93bd8f2) 147 XCTest, 24 Swift Testing 418 calls need hand work
swift-collections (8c409d4) 61 XCTest, 2 Swift Testing own helpers: 2,480 expectEqual calls
swift-argument-parser (d7b6ceb) 0 XCTest, 60 Swift Testing done
swift-log (c7413d9) 0 XCTest, 18 Swift Testing done
96 percent of XCTest calls in swift-nio have a one-line mapping

The 96% figure is a count of call sites, not of effort.

The 418 swift-nio calls without a table row are the useful part. They fall into three groups:

  • Project helpers built on XCTest, such as XCTAssertEqualWithoutAutoclosure (109 uses) and XCTAssertThrowsFileSystemErrorAsync (31). Port the helper once, with #expect and Issue.record inside, and its call sites move for free. swift-collections shows the extreme: almost all its 61 test files call its own expectEqual family, so the port there is a port of one support module.
  • Skips: 107 XCTSkip, 22 XCTSkipUnless, 6 XCTSkipIf, plus a custom skip helper. Static conditions become .enabled(if:) traits; conditions only known while the test runs become try Test.cancel(...), which Apple notes also works in XCTest.
  • Async expectations: 45 expectation(...), 44 fulfillment(of:), 6 wait(for:). These need a rewrite with confirmation(). Apple’s article points out that XCTestExpectation and Confirmation both default to “exactly once”; a range of counts needs a lower bound.

The two packages that are already done used the Swift Testing features you would expect: swift-argument-parser has 576 @Test functions, 249 #expect(throws:) checks and 11 .serialized traits; swift-log has 183 @Test functions.

The porting plan

Interop modes: limited, complete, strict

Raise the mode only when the previous stage is clean.

  1. Stay in limited mode (the default for a pre-6.4 tools version on Swift 6.4). Port the helpers first, then the files that are 100% mechanical. Watch the runtime warnings: each one is an XCTest call that a Swift Testing test was silently ignoring.
  2. Switch to complete by raising swift-tools-version to 6.4 or setting SWIFT_TESTING_XCTEST_INTEROP_MODE=complete in the test scheme. Those warnings now fail the test run, so mixed files are safe. Port expectations, skips and known issues.
  3. Finish in strict. Any XCTest API inside a Swift Testing test is now fatal, which proves the port is complete. Delete import XCTest where nothing needs it.

Keep measure blocks and UI tests that use XCUIApplication in XCTest for now: the mapping above has no row for them, and none of the five packages uses either in its test targets.

What to check on your own app

  • Run the counter on your test folder before estimating. The share of calls outside the table is the real size of the job.
  • Grep for accuracy:; each hit needs swift-numerics or a hand-written tolerance check.
  • Look for tests that share state through static properties or files: they need .serialized once they run in parallel.
  • Note your swift-tools-version: it decides which interop mode you start in.

Made by the team behind this post

Apps from our studio

  • Goes with this post

    Cardigami

    Pop-up greeting cards that rise out of the fold on iPhone Duo.

    iPhone · App Store

    Get
  • Goes with this post

    Nix

    The Mac uninstaller that finds what the Trash leaves behind: caches, logs, derived data and saved states.

    macOS

    Get
  • Goes with this post

    OneClick QuitAll

    Quit every running app in one click. See memory and CPU first.

    macOS · Mac App Store

    Get
  • BMDB.fun

    Your Bollywood world at a glance, with links straight to the OTT app that streams each film.

    Android TV · Web · Mobile

    Get

Need this built? Let’s talk.

We build and run apps for Mac, TV, mobile and the web, and write about what we learn.