Apply changes from ST-NNNN.

This PR applies the changes from [ST-NNNN](swiftlang/swift-evolution#2985).
It merges `AttachableAsCGImage` and `AttachableAsIWICBitmapSource` into a single
`AttachableAsImage` protocol and it adjusts the interfaces of
`AttachableImageFormat` and `Attachment where AttachableValue: AttachableAsImage`.

Author: grynspan

Sources/Overlays/_Testing_AppKit/Attachments/NSImage+AttachableAsCGImage.swift renamed to Sources/Overlays/_Testing_AppKit/Attachments/NSImage+AttachableAsImage.swift

@@ -36,21 +36,21 @@ extension NSImageRep {
 /// @Metadata {
 ///   @Available(Swift, introduced: 6.3)
 /// }
-extension NSImage: AttachableAsCGImage {
+extension NSImage: AttachableAsImage, AttachableAsCGImage {
   /// @Metadata {
   ///   @Available(Swift, introduced: 6.3)
   /// }
-  public var attachableCGImage: CGImage {
+  package var attachableCGImage: CGImage {
     get throws {
-      let ctm = AffineTransform(scale: _attachmentScaleFactor) as NSAffineTransform
+      let ctm = AffineTransform(scale: attachmentScaleFactor) as NSAffineTransform
       guard let result = cgImage(forProposedRect: nil, context: nil, hints: [.ctm: ctm]) else {
         throw ImageAttachmentError.couldNotCreateCGImage
       }
       return result
     }
   }
 
-  public var _attachmentScaleFactor: CGFloat {
+  package var attachmentScaleFactor: CGFloat {
     let maxRepWidth = representations.lazy
       .map { CGFloat($0.pixelsWide) / $0.size.width }
       .filter { $0 > 0.0 }

Sources/Overlays/_Testing_AppKit/CMakeLists.txt

@@ -8,7 +8,7 @@
 
 if (CMAKE_SYSTEM_NAME STREQUAL "Darwin")
   add_library(_Testing_AppKit
-    Attachments/NSImage+AttachableAsCGImage.swift
+    Attachments/NSImage+AttachableAsImage.swift
     ReexportTesting.swift)
 
   target_link_libraries(_Testing_AppKit PUBLIC

Sources/Overlays/_Testing_CoreGraphics/Attachments/AttachableAsCGImage.swift

@@ -9,42 +9,21 @@
 //
 
 #if SWT_TARGET_OS_APPLE && canImport(CoreGraphics)
-public import CoreGraphics
-private import ImageIO
+package import CoreGraphics
+package import ImageIO
+private import UniformTypeIdentifiers
 
 /// A protocol describing images that can be converted to instances of
-/// [`Attachment`](https://developer.apple.com/documentation/testing/attachment).
+/// [`Attachment`](https://developer.apple.com/documentation/testing/attachment)
+/// and which can be represented as instances of [`CGImage`](https://developer.apple.com/documentation/coregraphics/cgimage).
 ///
-/// Instances of types conforming to this protocol do not themselves conform to
-/// [`Attachable`](https://developer.apple.com/documentation/testing/attachable).
-/// Instead, the testing library provides additional initializers on [`Attachment`](https://developer.apple.com/documentation/testing/attachment)
-/// that take instances of such types and handle converting them to image data when needed.
-///
-/// You can attach instances of the following system-provided image types to a
-/// test:
-///
-/// | Platform | Supported Types |
-/// |-|-|
-/// | macOS | [`CGImage`](https://developer.apple.com/documentation/coregraphics/cgimage), [`CIImage`](https://developer.apple.com/documentation/coreimage/ciimage), [`NSImage`](https://developer.apple.com/documentation/appkit/nsimage) |
-/// | iOS, watchOS, tvOS, and visionOS | [`CGImage`](https://developer.apple.com/documentation/coregraphics/cgimage), [`CIImage`](https://developer.apple.com/documentation/coreimage/ciimage), [`UIImage`](https://developer.apple.com/documentation/uikit/uiimage) |
-/// | Windows | [`HBITMAP`](https://learn.microsoft.com/en-us/windows/win32/gdi/bitmaps), [`HICON`](https://learn.microsoft.com/en-us/windows/win32/menurc/icons), [`IWICBitmapSource`](https://learn.microsoft.com/en-us/windows/win32/api/wincodec/nn-wincodec-iwicbitmapsource) (including its subclasses declared by Windows Imaging Component) |
-///
-/// You do not generally need to add your own conformances to this protocol. If
-/// you have an image in another format that needs to be attached to a test,
-/// first convert it to an instance of one of the types above.
-///
-/// @Metadata {
-///   @Available(Swift, introduced: 6.3)
-/// }
+/// This protocol is not part of the public interface of the testing library. It
+/// encapsulates Apple-specific logic for image attachments.
 @available(_uttypesAPI, *)
-public protocol AttachableAsCGImage: _AttachableAsImage, SendableMetatype {
+package protocol AttachableAsCGImage: AttachableAsImage, SendableMetatype {
   /// An instance of `CGImage` representing this image.
   ///
   /// - Throws: Any error that prevents the creation of an image.
-  ///
-  /// @Metadata {
-  ///   @Available(Swift, introduced: 6.3)
-  /// }
   var attachableCGImage: CGImage { get throws }
 
   /// The orientation of the image.
@@ -53,38 +32,64 @@ public protocol AttachableAsCGImage: _AttachableAsImage, SendableMetatype {
   /// `CGImagePropertyOrientation`. The default value of this property is
   /// `.up`.
   ///
-  /// This property is not part of the public interface of the testing
-  /// library. It may be removed in a future update.
-  var _attachmentOrientation: UInt32 { get }
+  /// This property is not part of the public interface of the testing library.
+  /// It may be removed in a future update.
+  var attachmentOrientation: CGImagePropertyOrientation { get }
 
   /// The scale factor of the image.
   ///
   /// The value of this property is typically greater than `1.0` when an image
   /// originates from a Retina Display screenshot or similar. The default value
   /// of this property is `1.0`.
   ///
-  /// This property is not part of the public interface of the testing
-  /// library. It may be removed in a future update.
-  var _attachmentScaleFactor: CGFloat { get }
+  /// This property is not part of the public interface of the testing library.
+  /// It may be removed in a future update.
+  var attachmentScaleFactor: CGFloat { get }
 }
 
 @available(_uttypesAPI, *)
 extension AttachableAsCGImage {
-  public var _attachmentOrientation: UInt32 {
-    CGImagePropertyOrientation.up.rawValue
+  package var attachmentOrientation: CGImagePropertyOrientation {
+    .up
   }
 
-  public var _attachmentScaleFactor: CGFloat {
+  package var attachmentScaleFactor: CGFloat {
     1.0
   }
 
-  public func _deinitializeAttachableValue() {}
-}
+  public func withUnsafeBytes<R>(as imageFormat: AttachableImageFormat, _ body: (UnsafeRawBufferPointer) throws -> R) throws -> R {
+    let data = NSMutableData()
 
-@available(_uttypesAPI, *)
-extension AttachableAsCGImage where Self: Sendable {
-  public func _copyAttachableValue() -> Self {
-    self
+    // Convert the image to a CGImage.
+    let attachableCGImage = try attachableCGImage
+
+    // Create the image destination.
+    guard let dest = CGImageDestinationCreateWithData(data as CFMutableData, imageFormat.contentType.identifier as CFString, 1, nil) else {
+      throw ImageAttachmentError.couldNotCreateImageDestination
+    }
+
+    // Configure the properties of the image conversion operation.
+    let orientation = attachmentOrientation
+    let scaleFactor = attachmentScaleFactor
+    let properties: [CFString: Any] = [
+      kCGImageDestinationLossyCompressionQuality: CGFloat(imageFormat.encodingQuality),
+      kCGImagePropertyOrientation: orientation,
+      kCGImagePropertyDPIWidth: 72.0 * scaleFactor,
+      kCGImagePropertyDPIHeight: 72.0 * scaleFactor,
+    ]
+
+    // Perform the image conversion.
+    CGImageDestinationAddImage(dest, attachableCGImage, properties as CFDictionary)
+    guard CGImageDestinationFinalize(dest) else {
+      throw ImageAttachmentError.couldNotConvertImage
+    }
+
+    // Pass the bits of the image out to the body. Note that we have an
+    // NSMutableData here so we have to use slightly different API than we would
+    // with an instance of Data.
+    return try withExtendedLifetime(data) {
+      try body(UnsafeRawBufferPointer(start: data.bytes, count: data.length))
+    }
   }
 }
 #endif

Sources/Overlays/_Testing_CoreGraphics/Attachments/AttachableImageFormat+UTType.swift

@@ -9,58 +9,10 @@
 //
 
 #if SWT_TARGET_OS_APPLE && canImport(CoreGraphics)
-public import Testing
-
 public import UniformTypeIdentifiers
 
 @available(_uttypesAPI, *)
 extension AttachableImageFormat {
-  /// Get the content type to use when encoding the image, substituting a
-  /// concrete type for `UTType.image` in particular.
-  ///
-  /// - Parameters:
-  ///   - imageFormat: The image format to use, or `nil` if the developer did
-  ///     not specify one.
-  ///   - preferredName: The preferred name of the image for which a type is
-  ///     needed.
-  ///
-  /// - Returns: An instance of `UTType` referring to a concrete image type.
-  ///
-  /// This function is not part of the public interface of the testing library.
-  static func computeContentType(for imageFormat: Self?, withPreferredName preferredName: String) -> UTType {
-    guard let imageFormat else {
-      // The developer didn't specify a type. Substitute the generic `.image`
-      // and solve for that instead.
-      return computeContentType(for: Self(.image, encodingQuality: 1.0), withPreferredName: preferredName)
-    }
-
-    switch imageFormat.kind {
-    case .png:
-      return .png
-    case .jpeg:
-      return .jpeg
-    case let .systemValue(contentType):
-      let contentType = contentType as! UTType
-      if contentType != .image {
-        // The developer explicitly specified a type.
-        return contentType
-      }
-
-      // The developer didn't specify a concrete type, so try to derive one from
-      // the preferred name's path extension.
-      let pathExtension = (preferredName as NSString).pathExtension
-      if !pathExtension.isEmpty,
-         let contentType = UTType(filenameExtension: pathExtension, conformingTo: .image),
-         contentType.isDeclared {
-        return contentType
-      }
-
-      // We couldn't derive a concrete type from the path extension, so pick
-      // between PNG and JPEG based on the encoding quality.
-      return imageFormat.encodingQuality < 1.0 ? .jpeg : .png
-    }
-  }
-
   /// The content type corresponding to this image format.
   ///
   /// For example, if this image format equals ``png``, the value of this
@@ -100,12 +52,19 @@ extension AttachableImageFormat {
   /// @Metadata {
   ///   @Available(Swift, introduced: 6.3)
   /// }
-  public init(_ contentType: UTType, encodingQuality: Float = 1.0) {
-    precondition(
-      contentType.conforms(to: .image),
-      "An image cannot be attached as an instance of type '\(contentType.identifier)'. Use a type that conforms to 'public.image' instead."
-    )
-    self.init(kind: .systemValue(contentType), encodingQuality: encodingQuality)
+  public init(contentType: UTType, encodingQuality: Float = 1.0) {
+    switch contentType {
+    case .png:
+      self.init(kind: .png, encodingQuality: encodingQuality)
+    case .jpeg:
+      self.init(kind: .jpeg, encodingQuality: encodingQuality)
+    default:
+      precondition(
+        contentType.conforms(to: .image),
+        "An image cannot be attached as an instance of type '\(contentType.identifier)'. Use a type that conforms to 'public.image' instead."
+      )
+      self.init(kind: .systemValue(contentType), encodingQuality: encodingQuality)
+    }
   }
 
   /// Construct an instance of this type with the given path extension and
@@ -135,11 +94,12 @@ extension AttachableImageFormat {
   public init?(pathExtension: String, encodingQuality: Float = 1.0) {
     let pathExtension = pathExtension.drop { $0 == "." }
 
-    guard let contentType = UTType(filenameExtension: String(pathExtension), conformingTo: .image) else {
+    guard let contentType = UTType(filenameExtension: String(pathExtension), conformingTo: .image),
+          contentType.isDeclared else {
       return nil
     }
 
-    self.init(contentType, encodingQuality: encodingQuality)
+    self.init(contentType: contentType, encodingQuality: encodingQuality)
   }
 }
 #endif

Sources/Overlays/_Testing_CoreGraphics/Attachments/CGImage+AttachableAsCGImage.swift renamed to Sources/Overlays/_Testing_CoreGraphics/Attachments/CGImage+AttachableAsImage.swift

@@ -14,11 +14,11 @@ public import CoreGraphics
 /// @Metadata {
 ///   @Available(Swift, introduced: 6.3)
 /// }
-extension CGImage: AttachableAsCGImage {
+extension CGImage: AttachableAsImage, AttachableAsCGImage {
   /// @Metadata {
   ///   @Available(Swift, introduced: 6.3)
   /// }
-  public var attachableCGImage: CGImage {
+  package var attachableCGImage: CGImage {
     self
   }
 }

Sources/Overlays/_Testing_CoreGraphics/Attachments/_AttachableImageWrapper+AttachableWrapper.swift

@@ -9,76 +9,52 @@
 //
 
 #if SWT_TARGET_OS_APPLE && canImport(CoreGraphics)
-public import Testing
 private import CoreGraphics
 
-private import ImageIO
 private import UniformTypeIdentifiers
 
-/// ## Why can't images directly conform to Attachable?
-///
-/// Three reasons:
-///
-/// 1. Several image classes are not marked `Sendable`, which means that as far
-///    as Swift is concerned, they cannot be safely passed to Swift Testing's
-///    event handler (primarily because `Event` is `Sendable`.) So we would have
-///    to eagerly serialize them, which is unnecessarily expensive if we know
-///    they're actually concurrency-safe.
-/// 2. We would have no place to store metadata such as the encoding quality
-///    (although in the future we may introduce a "metadata" associated type to
-///    `Attachable` that could store that info.)
-/// 3. `Attachable` has a requirement with `Self` in non-parameter, non-return
-///    position. As far as Swift is concerned, a non-final class cannot satisfy
-///    such a requirement, and all image types we care about are non-final
-///    classes. Thus, the compiler will steadfastly refuse to allow non-final
-///    classes to conform to the `Attachable` protocol. We could get around this
-///    by changing the signature of `withUnsafeBytes()` so that the
-///    generic parameter to `Attachment` is not `Self`, but that would defeat
-///    much of the purpose of making `Attachment` generic in the first place.
-///    (And no, the language does not let us write `where T: Self` anywhere
-///    useful.)
-
 @available(_uttypesAPI, *)
-extension _AttachableImageWrapper: Attachable, AttachableWrapper where Image: AttachableAsCGImage {
-  public func withUnsafeBytes<R>(for attachment: borrowing Attachment<_AttachableImageWrapper>, _ body: (UnsafeRawBufferPointer) throws -> R) throws -> R {
-    let data = NSMutableData()
-
-    // Convert the image to a CGImage.
-    let attachableCGImage = try wrappedValue.attachableCGImage
-
-    // Create the image destination.
-    let contentType = AttachableImageFormat.computeContentType(for: imageFormat, withPreferredName: attachment.preferredName)
-    guard let dest = CGImageDestinationCreateWithData(data as CFMutableData, contentType.identifier as CFString, 1, nil) else {
-      throw ImageAttachmentError.couldNotCreateImageDestination
+extension _AttachableImageWrapper: Attachable, AttachableWrapper where Image: AttachableAsImage {
+  /// Get the image format to use when encoding an image, substituting a
+  /// concrete type for `UTType.image` in particular.
+  ///
+  /// - Parameters:
+  ///   - preferredName: The preferred name of the image for which a type is
+  ///     needed.
+  ///
+  /// - Returns: An instance of ``AttachableImageFormat`` referring to a
+  ///   concrete image type.
+  ///
+  /// This function is not part of the public interface of the testing library.
+  private func _imageFormat(forPreferredName preferredName: String) -> AttachableImageFormat {
+    if let imageFormat, case let contentType = imageFormat.contentType, contentType != .image {
+      // The developer explicitly specified a type.
+      return imageFormat
     }
 
-    // Configure the properties of the image conversion operation.
-    let orientation = wrappedValue._attachmentOrientation
-    let scaleFactor = wrappedValue._attachmentScaleFactor
-    let properties: [CFString: Any] = [
-      kCGImageDestinationLossyCompressionQuality: CGFloat(imageFormat?.encodingQuality ?? 1.0),
-      kCGImagePropertyOrientation: orientation,
-      kCGImagePropertyDPIWidth: 72.0 * scaleFactor,
-      kCGImagePropertyDPIHeight: 72.0 * scaleFactor,
-    ]
-
-    // Perform the image conversion.
-    CGImageDestinationAddImage(dest, attachableCGImage, properties as CFDictionary)
-    guard CGImageDestinationFinalize(dest) else {
-      throw ImageAttachmentError.couldNotConvertImage
+    // The developer didn't specify a concrete type, so try to derive one from
+    // the preferred name's path extension.
+    let pathExtension = (preferredName as NSString).pathExtension
+    if !pathExtension.isEmpty,
+       let contentType = UTType(filenameExtension: pathExtension, conformingTo: .image),
+       contentType.isDeclared {
+      return AttachableImageFormat(contentType: contentType)
     }
 
-    // Pass the bits of the image out to the body. Note that we have an
-    // NSMutableData here so we have to use slightly different API than we would
-    // with an instance of Data.
-    return try withExtendedLifetime(data) {
-      try body(UnsafeRawBufferPointer(start: data.bytes, count: data.length))
-    }
+    // We couldn't derive a concrete type from the path extension, so pick
+    // between PNG and JPEG based on the encoding quality.
+    let encodingQuality = imageFormat?.encodingQuality ?? 1.0
+    return encodingQuality < 1.0 ? .jpeg : .png
+  }
+
+  public func withUnsafeBytes<R>(for attachment: borrowing Attachment<_AttachableImageWrapper>, _ body: (UnsafeRawBufferPointer) throws -> R) throws -> R {
+    let imageFormat = _imageFormat(forPreferredName: attachment.preferredName)
+    return try wrappedValue.withUnsafeBytes(as: imageFormat, body)
   }
 
   public borrowing func preferredName(for attachment: borrowing Attachment<_AttachableImageWrapper>, basedOn suggestedName: String) -> String {
-    let contentType = AttachableImageFormat.computeContentType(for: imageFormat, withPreferredName: suggestedName)
-    return (suggestedName as NSString).appendingPathExtension(for: contentType)
+    let imageFormat = _imageFormat(forPreferredName: suggestedName)
+    return (suggestedName as NSString).appendingPathExtension(for: imageFormat.contentType)
   }
 }
 #endif