テストへの添付（attachments）

テストに任意の値を添付するための型 Attachment と、添付可能な値を表すプロトコル Attachable を導入します。標準ライブラリの主要な型にはあらかじめ Attachable への適合が用意され、Foundation を併せて import している場合には Data や URL といった Foundation の型に対する適合もクロスインポートオーバーレイ経由で提供されます。

値をそのまま添付する

もっとも単純な使い方は、Attachable に適合した値を Attachment.record(_:named:sourceLocation:) に渡す方法です。標準ライブラリ側では Array<UInt8> / ContiguousArray<UInt8> / ArraySlice<UInt8> / String / Substring に対して Attachable への適合が用意されているので、これらは追加の準備なしにそのまま添付できます。

@Test func generatesReport() {
    let report: String = makeReport()
    Attachment.record(report, named: "report.txt")
}

preferredName はファイル名のヒントとしてテスティングライブラリに渡されます。テスティングライブラリ側で必要に応じて拡張子を補ったり、別の名前に置き換えたりすることがあります。明示的に渡さない場合は、テスティングライブラリが値の型から妥当な名前を導出します。

Attachment を一度組み立ててから添付することもできます。こうすると、添付前にプロパティを調整する余地が生まれます。

@Test func generatesReport() {
    let attachment = Attachment(makeReport(), named: "report.txt")
    Attachment.record(attachment)
}

1 つの Attachment を添付できるのは 1 回だけです。

Attachment 型と Attachable プロトコル

Attachment は添付対象の値の型をジェネリックパラメータに取る non-copyable な構造体で、値が Copyable / Sendable である場合にはそれぞれ条件付きで Copyable / Sendable にも適合します。

public struct Attachment<AttachableValue>: ~Copyable
where AttachableValue: Attachable & ~Copyable {
    public var preferredName: String { get }
    public var attachableValue: AttachableValue { get }

    public init(
        _ attachableValue: consuming AttachableValue,
        named preferredName: String? = nil,
        sourceLocation: SourceLocation = #_sourceLocation
    )

    public static func record(
        _ attachment: consuming Self,
        sourceLocation: SourceLocation = #_sourceLocation
    )

    public static func record(
        _ attachableValue: consuming AttachableValue,
        named preferredName: String? = nil,
        sourceLocation: SourceLocation = #_sourceLocation
    )
}

extension Attachment: Copyable where AttachableValue: Copyable {}
extension Attachment: Sendable where AttachableValue: Sendable {}

record(_:sourceLocation:) に渡された値が Sendable かつ Copyable ではない場合、テスティングライブラリは添付時点で値をバイト列にエンコードします。エンコード中にエラーが throw されると、それは現在のテストの issue として記録され、添付自体は破棄されます。

添付対象の型が満たすべき要件は Attachable プロトコルで表現されます。

public protocol Attachable: ~Copyable {
    var estimatedAttachmentByteCount: Int? { get }

    borrowing func withUnsafeBytes<R>(
        for attachment: borrowing Attachment<Self>,
        _ body: (UnsafeRawBufferPointer) throws -> R
    ) throws -> R

    borrowing func preferredName(
        for attachment: borrowing Attachment<Self>,
        basedOn suggestedName: String
    ) -> String
}

withUnsafeBytes(for:_:) は、その型を「ファイルとして書き出すなら自然な形式」のバイト列として渡す責務を持ちます。たとえば画像を表す型なら PNG や JPEG のバイト列を渡すのが望ましく、画像のテキスト表現を渡すのは適切ではありません。estimatedAttachmentByteCount は、添付をメモリ上に保持するか、すぐにストレージに書き出すかをテスティングライブラリが判断するためのヒントです。preferredName(for:basedOn:) は、テスト作者が指定した名前を基にファイル名を整える機会を型側に与えるもので、たとえば後述の Encodable 経由の実装では拡張子を補うために使われます。

Encodable / NSSecureCoding 経由の添付

Foundation が import されている環境では、Attachable かつ Encodable か、Attachable かつ NSSecureCoding に適合する型に対して、withUnsafeBytes(for:_:) のデフォルト実装が提供されます。エンコーダには Foundation の JSONEncoder や PropertyListEncoder が使われるため、この経路を使うには Foundation の import が必要です。利用者は自分の型を Attachable に適合させて Encodable を併用するだけで、JSON や plist として添付できるようになります。

AttachableWrapper でラップする

「直接 Attachable に適合させづらい型」に対しては、Attachable を継承する AttachableWrapper プロトコルが用意されています。サードパーティ製モジュールに定義された型や、final ではないクラス、追加情報がないとエンコードできない型などが該当します。これらに対しては、テスト側でラッパー型を定義して AttachableWrapper に適合させ、wrappedValue から元の値を取り出せるようにします。

public protocol AttachableWrapper<Wrapped>: Attachable, ~Copyable {
    associatedtype Wrapped
    var wrappedValue: Wrapped { get }
}

Attachment の attachableValue プロパティは、添付対象の型が AttachableWrapper に適合している場合には、ラッパー型ではなく内側の Wrapped の値を返すよう特殊化されています。ラッパー自身として取り出したいときは as で型を明示します。

let attachableValue = attachment.attachableValue as MyWrapper

ファイルや URL の中身を添付する

Foundation とのクロスインポートオーバーレイには、URL の指す先を添付するための初期化子も用意されています。最後のパスコンポーネントから自動的にファイル名が導出されるため、preferredName は省略可能です。

@Test func reportsFromDisk() async throws {
    let url = URL(fileURLWithPath: "/tmp/report.txt")
    let attachment = try await Attachment(contentsOf: url)
    Attachment.record(attachment)
}

extension Attachment where AttachableValue == _AttachableURLWrapper {
    public init(
        contentsOf url: URL,
        named preferredName: String? = nil,
        sourceLocation: SourceLocation = #_sourceLocation
    ) async throws
}

_AttachableURLWrapper は AttachableWrapper に適合する内部型で、URL とそこから読み込まれたデータを保持します。

ツール連携

swift test には添付の保存先を指定するための新しいオプションが追加されます。

--attachments-path  Path where attachments should be saved.

--attachments-path を指定すると、添付されたデータがそのディレクトリ以下にファイルとして書き出されます。指定されない場合、添付はディスクに保存されません。swift test を内部で呼び出すツールは、たとえばシステムの一時ディレクトリ配下にディレクトリを作ってこのオプションに渡し、終了後に必要なファイルを取り出すような使い方ができます。

JSON ベースのイベントストリーム ABI にも、添付を表す要素が追加されます。新しい event kind として valueAttached が追加され、その際のイベントには attachment フィールドが付き、そこに添付ファイルの絶対パスが入ります。これらの追加は後方互換であるため、JSON スキーマのバージョンは据え置きです。