ツール連携のための安定したJSONベースのABI

ツール連携のために、Swift Testing に安定した ABI を導入します。具体的には次の2つを定義します。

• 動的ローダ（Darwin・Linux・Windows）から実行時に解決できる安定したエントリポイント関数。シグネチャは将来にわたって変更されず、入力を受け取り、出力を非同期に返します。
• ツールが解釈できる安定した JSON ベースのスキーマ。入力（テスト構成・オプション）と出力（イベント）の両方に用います。

本 Proposal では出力側の JSON スキーマを定義し、入力側の JSON スキーマは後続の Proposal で扱います。

JSON スキーマによる出力

出力は、改行区切りの JSON オブジェクト列（JSON Lines）として、ファイルや名前付きパイプ、あるいはイベントハンドラに書き出されます。

テスト実行が始まると、まず計画されたテストの一覧が kind: "test" のレコードとして書き出されます。

{
  "kind": "test",
  "payload": {
    "displayName": "Can get stdout",
    "id": "TestingTests.FileHandleTests/canGetStdout()/FileHandleTests.swift:33:4",
    "isParameterized": false,
    "kind": "function",
    "name": "canGetStdout()",
    "sourceLocation": {
      "column": 4,
      "fileID": "TestingTests/FileHandleTests.swift",
      "line": 33
    }
  },
  "version": 0
}

その後、テスト実行中の各種イベント（テスト開始・issue 記録・テスト終了など）が kind: "event" のレコードとして順次書き出されます。

{
  "kind": "event",
  "payload": {
    "instant": { "absolute": 266418.545786299, "since1970": 1718302639.76747 },
    "kind": "testStarted",
    "messages": [
      { "symbol": "default", "text": "Test \"Can get stdout\" started." }
    ],
    "testID": "TestingTests.FileHandleTests/canGetStdout()/FileHandleTests.swift:33:4"
  },
  "version": 0
}

{
  "kind": "event",
  "payload": {
    "instant": { "absolute": 266636.524236724, "since1970": 1718302857.74857 },
    "issue": {
      "isKnown": false,
      "sourceLocation": {
        "column": 7, "fileID": "TestingTests/FileHandleTests.swift", "line": 29
      }
    },
    "kind": "issueRecorded",
    "messages": [
      { "symbol": "fail", "text": "Expectation failed: (EOF → -1) == (feof(fileHandle) → 0)" }
    ],
    "testID": "TestingTests.FileHandleTests/canGetStdout()/FileHandleTests.swift:33:4"
  },
  "version": 0
}

各イベントには 0 個以上の messages が含まれ、ツールが利用者向けに表示するための人間可読なテキストと、抽象化されたシンボル名（fail、default など）が入ります。これは Swift Testing 自身が標準エラーに書き出す出力に対応するもので、ツールは独自の UI に合わせて表示できます。

詳細な JSON スキーマは Swift Testing リポジトリの Documentation/ABI/JSON.md で定義されています。

コマンドラインからの利用

swift test に、ツール連携用の引数が3つ追加されます。引数名は Swift Package Manager 側のレビューで変わる可能性があります。

--event-stream-output-path を指定するとテスト実行中のイベントが JSON Lines として書き出されます。Darwin・Linux では mkfifo()、Windows では CreateNamedPipe() で作成した名前付きパイプを指定すれば、ファイルクローズを待たずにライブで結果を受け取れます。--configuration-path と --no-parallel のような明示的なコマンドライン引数の両方が指定された場合は、明示的な引数が優先されます。

--event-stream-output-path のみを指定して --event-stream-version を省略した場合、現状は Swift Testing 内部型を直接 JSON エンコードした不安定なフォーマットになります。これは Xcode 16 Beta 1 を支えるための過渡的な挙動で、将来的には最新の安定スキーマがデフォルトになる予定です。ツールの作者は破壊的変更を避けるため、明示的にバージョンを指定することが推奨されます。

Swift からの利用

Swift コードから直接エントリポイントを呼び出すために、@_spi(ForToolsIntegrationOnly) の ABIv0 という enum が公開されます。ABIv0.entryPoint プロパティで取得できる関数は、JSON でエンコードされた構成と、各レコードを受け取るコールバックを引数に取り、テスト実行が成功したかを返します。

@_spi(ForToolsIntegrationOnly)
public enum ABIv0 {
    public typealias EntryPoint = @convention(thin) @Sendable (
        _ configurationJSON: UnsafeRawBufferPointer?,
        _ recordHandler: @escaping @Sendable (_ recordJSON: UnsafeRawBufferPointer) -> Void
    ) async throws -> Bool

    public static var entryPoint: EntryPoint { get }
}

入出力の型を Data ではなく UnsafeRawBufferPointer にしているのは、Data が Foundation の型であり、Swift Testing が Foundation に公開依存することを避けるためです。これにより、将来 Foundation 自身が Swift Testing を採用しやすくなります。

C・C++ からの利用

Swift シンボルに直接リンクできないツールでも使えるよう、ABIv0.entryPoint の getter が C・C++ から呼べるシンボルとしてエクスポートされます。

extern "C" const void *_Nonnull swt_abiv0_getEntryPoint(void);

呼び出し側は dlsym()（POSIX）や GetProcAddress()（Windows）でこのシンボルを実行時に解決し、戻り値を unsafeBitCast(_:to:) で Swift の関数型に戻して呼び出します。データポインタから関数ポインタへの変換が許されないプラットフォーム（C 標準 §6.3.2.3, §J.5.7）ではこの操作はサポートされません。

なお、Swift Testing をパッケージ依存として組み込むとメイン実行可能ファイルに静的リンクされます。ELF を用いる Linux などでは、リンカに --export-dynamic を渡さないと実行時にメイン実行可能ファイルのシンボル情報が取得できないことがあるため、ツール側で注意が必要です。