Swift Testing と XCTest の間での的を絞った相互運用

Swift Testing と XCTest の間で、次の2方向の interop（相互運用）を導入します。

• lossy without interop な XCTest API は、Swift Testing から呼び出しても期待どおりに動くようにする。あわせて、より新しい Swift Testing 相当の API への移行を促すため、実行時に診断（runtime warning issue）を出します。
• Swift Testing API は、XCTest 側に同等機能がある場合に限り、XCTest から呼び出しても期待どおりに動くようにする。これにより、新しいテストやヘルパーを Swift Testing で書いておいても、XCTest 側からも安全に利用できます。

なお、本 Proposal が対象とする XCTest は、Swift Evolution のプロセスで扱える open source 実装である swift-corelibs-xctest です。Xcode に同梱されている proprietary な XCTest は対象外です。

Swift Testing 内での XCTest API のサポート

次の XCTest API が、Swift Testing のテスト内でも期待どおりに動くようになります。

• アサーション（XCTAssert* および無条件失敗の XCTFail）
• XCTExpectFailure などの expected failure 系 API（利用可能な場合）。Swift Testing の issue をこの方法で marking すると、ランタイム警告 issue が記録されます。
• issue handling trait。XCTest の issue は、可能な限り Swift Testing の issue に翻訳されます。XCTest 固有の情報は、Swift Testing 側の issue にコメントとして付与されます。

XCTSkip は Swift Testing 内で throw するとそのままテスト失敗として目立つ形で現れるため、変更はありません。XCTestExpectation や XCTWaiter についても、Swift concurrency の文脈で安全に使えないため、サポートの対象外です。これらの代替としては、Swift concurrency への移行が推奨されます。async / await に置き換えにくい場合は、continuation や confirmation を利用します。

あわせて、Swift Testing 内で XCTest API が呼び出されたことを開発者に伝えるために、次の仕組みが導入されます。

• runtime warning issue の記録。アサーション失敗とは別に、XCTest API が使われたこと自体をランタイム警告 issue として記録し、Swift Testing 相当 API への置き換えを促します。
• strict interop モード（オプトイン）。XCTest API の使用を fatalError("Usage of XCTest API in a Swift Testing context is unsupported") で停止させ、Swift Testing のみで構成されたテストに混入しないことを強制します。

具体的な挙動の変化は次の表のとおりです。

XCTest 内での Swift Testing API のサポート

次の Swift Testing API が、XCTest のテスト内でも期待どおりに動くようになります。

• #expect / #require（#expect(throws:) や exit testing、Issue.record() を含む）
• withKnownIssue。XCTest の issue をこの方法で marking すると、ランタイム警告 issue が記録されます。strict モードではこれが fatalError になります。
• test cancellation

これにより、XCTest のテストの中でも XCTAssert を #expect に置き換えるだけで、より新しく扱いやすい Swift Testing API の利点をすぐに享受できます。テストインフラ全体を Swift Testing に置き換えるのを待たずに、自分のペースで段階的に移行できます。

将来追加される Swift Testing の API についても、XCTest 側に同等機能がある場合に限り interop の対象になります。一方で、Swift Testing 固有の概念である trait のように XCTest 側に対応物がない機能については、interop の対象外です。なお、test cancellation は XCTest の XCTSkip と対応関係にあるため、本 Proposal で interop の対象に含まれます。

具体的な挙動の変化は次の表のとおりです。

interop モード

interop の振る舞いは、次の4つのモードで切り替えられます。none 以外のいずれのモードでも、XCTest 内で呼び出された Swift Testing API（Issue.record() を含む）は期待どおりに動き、アサーション失敗はそのままテスト失敗として記録されます。モードによって挙動が変わるのは、Swift Testing 内で呼び出された XCTest API の扱いです。

• None: interop なし。本 Proposal 適用前と同じ挙動です。
• Limited: Swift Testing 内での XCTest API 使用に対して、これまで無視されていた XCTest issue をランタイム警告 issue として記録します。あわせて、XCTest API が使われたこと自体に対するランタイム警告 issue も出ます。interop 導入によって既存の Swift Testing テストに新たなテスト失敗を持ち込みたくないプロジェクト向けです。
• Complete: デフォルトのモード。Swift Testing 内での XCTest API 使用について、これまで無視されていた XCTest issue を実際のテスト失敗として表面化させます。あわせて、XCTest API が使われたこと自体に対するランタイム警告 issue も出ます。
• Strict: complete モードの警告 issue は CI 上などで見落とされやすいため、Swift Testing 内に XCTest API がまったく混入しないことを保証するモードです。XCTest API の使用を fatalError にします。

interop モードは、テスト実行時の環境変数 SWIFT_TESTING_XCTEST_INTEROP_MODE で切り替えます。

具体的な挙動は次の例のとおりです。Issue.record("Interop failure") のように Swift Testing API を XCTest 内で使った場合、none 以外のすべてのモードでテスト失敗として記録されます。一方、XCTFail("Interop failure") のように XCTest API を Swift Testing 内で使った場合、limited ではランタイム警告 issue 止まり、complete では本来のテスト失敗として表面化、strict では fatalError になります。

class FooTests: XCTestCase {
    func testInterop() {
      // None:     no-op
      // Limited:  ❌ "Interop failure"
      // Complete: ❌ "Interop failure"
      // Strict:   ❌ "Interop failure"
      Issue.record("Interop failure")
    }
}

@Test func `Test Interop`() {
    // None:     no-op
    // Limited:  ⚠️ "Interop failure", ⚠️ Swift Testing primitive への移行を促す警告
    // Complete: ❌ "Interop failure", ⚠️ Swift Testing primitive への移行を促す警告
    // Strict:   💥 fatalError: Swift Testing primitive を使うべき
    XCTFail("Interop failure")
}

デフォルトの interop モードと移行

新しいプロジェクトのデフォルトは “complete”、既存プロジェクトのデフォルトは “limited” になり、後者は “complete” へのオプトインが容易な形で提供されます。

具体的には、interop が利用可能になるツールチェイン版を 6.X とすると、Swift Package では Package.swift の swift-tools-version を基準に次のように決まります。

• swift-tools-version >= 6.X: “complete” interop モード
• swift-tools-version < 6.X: “limited” interop モード

interop の目的は挙動を変えることそのものなので、本 Proposal の適用後は、これまで「成功」とみなされていたテストが新たに失敗する状況が出てきます。これは、見逃していた本物のバグを表面化させるという意味で、基本的にはプラスの変化として捉えられます。短期的に従来の挙動に戻したい場合は、次のいずれかを指定します。

• SWIFT_TESTING_XCTEST_INTEROP_MODE=limited: Swift Testing 内で使われた XCTest issue の重要度をエラーから警告に下げます（Swift Testing API を XCTest 内で使った場合の失敗はそのまま残ります）。
• SWIFT_TESTING_XCTEST_INTEROP_MODE=none: interop を完全に無効化します。

なお、当初の Proposal では limited モードが Swift Testing API の issue まで含めて警告に降格していましたが、XCTFail() を Issue.record() に書き換えると失敗が静かに警告へ降格してテストカバレッジを失う、という副作用がありました。Apr 2026 の amendment で limited モードの定義が見直され、Swift Testing API 由来の issue はモードによらずテスト失敗として扱う形に整理されています。

ツールとの統合

• Swift Package では、テスト実行に使うツールチェイン版にかかわらず、Package.swift の swift-tools-version から interop モードが決まります（そのツールチェイン版に対応するデフォルトモードが選ばれます。初期リリース時点では “complete”）。
• それ以外のプロジェクトでは、インストールされているツールチェイン版に対応するデフォルトモードが使われます。
• どのプロジェクトでも、環境変数 SWIFT_TESTING_XCTEST_INTEROP_MODE で実行時にモードを上書きできます。