Swift Testing での画像添付（Apple プラットフォーム）

Apple プラットフォーム向けに、画像を直接 attachment として扱う仕組みを導入します。具体的には次の 3 つです。

• 画像型を Attachment に渡せるようにするためのプロトコル AttachableAsCGImage
• 添付時に画像形式や品質を指定するための型 AttachableImageFormat
• 上記を受け取る Attachment.init(...) と Attachment.record(...) のオーバーロード

これらは macOS 11.0 / iOS 14.0 / watchOS 7.0 / tvOS 14.0 以降で利用できます。本 Proposal は Apple プラットフォームのみが対象で、Windows などへの対応は今後の見通しとして扱われています。

AttachableAsCGImage プロトコル

「CGImage として取り出せる画像」を表すプロトコルとして AttachableAsCGImage が追加されます。Attachable を直接継承するのではなく、テスティングライブラリ側でこのプロトコルに適合した値を画像のバイト列に変換するためのフックです。

@available(macOS 11.0, iOS 14.0, watchOS 7.0, tvOS 14.0, *)
public protocol AttachableAsCGImage {
  /// An instance of `CGImage` representing this image.
  ///
  /// - Throws: Any error that prevents the creation of an image.
  var attachableCGImage: CGImage { get throws }
}

このプロトコルには、システム標準の次の画像型があらかじめ適合しています。

• CGImage
• CIImage
• NSImage（macOS）
• UIImage（iOS, watchOS, tvOS, visionOS, Mac Catalyst）

CGImage.attachableCGImage は self をそのまま返し、それ以外の型は内部で保持している CGImage を取り出すか、必要に応じてその場でレンダリングします。テスト作者は通常、自分で AttachableAsCGImage への適合を書く必要はなく、別の表現の画像を扱いたい場合は事前に上記のいずれかの型に変換します。

なお、適合する型は将来追加される可能性があり、その判断は Testing Workgroup が行います。

画像を添付する

Attachment に、AttachableAsCGImage に適合する値を直接渡せる初期化子と record(...) のオーバーロードが追加されます。

@available(macOS 11.0, iOS 14.0, watchOS 7.0, tvOS 14.0, *)
extension Attachment {
  public init<T>(
    _ attachableValue: T,
    named preferredName: String? = nil,
    as imageFormat: AttachableImageFormat? = nil,
    sourceLocation: SourceLocation = #_sourceLocation
  ) where AttachableValue == _AttachableImageWrapper<T>

  public static func record<T>(
    _ image: T,
    named preferredName: String? = nil,
    as imageFormat: AttachableImageFormat? = nil,
    sourceLocation: SourceLocation = #_sourceLocation
  ) where AttachableValue == _AttachableImageWrapper<T>
}

_AttachableImageWrapper<Image> はジェネリクスの都合で API シグネチャに現れる内部のラッパー型で、Sendable かつ AttachableWrapper に適合しています。テスト作者がこの型を直接組み立てる必要はありません。

imageFormat は出力する画像の形式を指定するパラメータで、nil の場合はテスティングライブラリが選びます。nil を渡したときの選択は、preferredName の拡張子に応じた形式が利用可能ならそれを使い、利用可能な拡張子が指定されていなければライブラリが適切な形式を自動的に選ぶ、という挙動になります。

AttachableImageFormat で形式と品質を指定する

画像形式と、必要に応じてエンコード品質を抽象的に表す型として AttachableImageFormat が追加されます。PNG と JPEG は常に利用可能で、それ以外の形式はプラットフォームに依存します。Apple プラットフォームでは、Image I/O フレームワークの CGImageDestinationCopyTypeIdentifiers() が返す形式が利用できます。

@available(macOS 11.0, iOS 14.0, watchOS 7.0, tvOS 14.0, *)
public struct AttachableImageFormat: Sendable {
  /// The encoding quality to use for this image format.
  public var encodingQuality: Float { get }
}

encodingQuality は 0.0（最低品質）から 1.0（最高品質）までの値で、形式が可変品質エンコーディングをサポートしない場合は無視されます。

PNG と JPEG については、よく使われる形式として静的プロパティと関数が用意されています。

@available(macOS 11.0, iOS 14.0, watchOS 7.0, tvOS 14.0, *)
extension AttachableImageFormat {
  public static var png: Self { get }
  public static var jpeg: Self { get } // 最高品質の JPEG
  public static func jpeg(withEncodingQuality encodingQuality: Float) -> Self
}

たとえば 50% の品質で JPEG として保存したい場合は .jpeg(withEncodingQuality: 0.5) を指定します。

Apple プラットフォーム向けには UTType を受け取る初期化子も用意されており、Image I/O が対応する任意の形式を選べます。UTType.image に適合しない型を渡した場合の挙動は未定義です。

@available(macOS 11.0, iOS 14.0, watchOS 7.0, tvOS 14.0, *)
extension AttachableImageFormat {
  public var contentType: UTType { get }

  public init(_ contentType: UTType, encodingQuality: Float = 1.0)
}

利用例

たとえば SwiftUI のビューを画像としてレンダリングし、PNG として添付するには次のように書けます。

import Testing
import UIKit
import SwiftUI

@MainActor @Test func `attaching a SwiftUI view as an image`() throws {
  let myView: some View = ...
  let image = try #require(ImageRenderer(content: myView).uiImage)
  Attachment.record(image, named: "my view", as: .png)
  // OR: Attachment.record(image, named: "my view.png")
}

as: .png を明示する代わりに、preferredName の拡張子（my view.png）から PNG を選ばせることもできます。