Promote Darwin image attachments to API. (#1274)

This PR promotes image attachments on Apple platforms to API (pending
approval of ST-0014).

### Checklist:

- [x] Code and documentation should follow the style of the [Style
Guide](https://github.com/apple/swift-testing/blob/main/Documentation/StyleGuide.md).
- [x] If public symbols are renamed or modified, DocC references should
be updated.

Author: grynspan

Sources/Overlays/CMakeLists.txt

@@ -1,9 +1,13 @@
 # This source file is part of the Swift.org open source project
 #
-# Copyright (c) 2024 Apple Inc. and the Swift project authors
+# Copyright (c) 2024–2025 Apple Inc. and the Swift project authors
 # Licensed under Apache License v2.0 with Runtime Library Exception
 #
 # See http://swift.org/LICENSE.txt for license information
 # See http://swift.org/CONTRIBUTORS.txt for Swift project authors
 
+add_subdirectory(_Testing_AppKit)
+add_subdirectory(_Testing_CoreGraphics)
+add_subdirectory(_Testing_CoreImage)
 add_subdirectory(_Testing_Foundation)
+add_subdirectory(_Testing_UIKit)

Sources/Overlays/_Testing_AppKit/Attachments/NSImage+AttachableAsCGImage.swift

@@ -1,7 +1,7 @@
 //
 // This source file is part of the Swift.org open source project
 //
-// Copyright (c) 2024 Apple Inc. and the Swift project authors
+// Copyright (c) 2024–2025 Apple Inc. and the Swift project authors
 // Licensed under Apache License v2.0 with Runtime Library Exception
 //
 // See https://swift.org/LICENSE.txt for license information
@@ -10,7 +10,7 @@
 
 #if SWT_TARGET_OS_APPLE && canImport(AppKit)
 public import AppKit
-@_spi(Experimental) public import _Testing_CoreGraphics
+public import _Testing_CoreGraphics
 
 extension NSImageRep {
   /// AppKit's bundle.
@@ -33,8 +33,13 @@ extension NSImageRep {
 
 // MARK: -
 
-@_spi(Experimental)
+/// @Metadata {
+///   @Available(Swift, introduced: 6.3)
+/// }
 extension NSImage: AttachableAsCGImage {
+  /// @Metadata {
+  ///   @Available(Swift, introduced: 6.3)
+  /// }
   public var attachableCGImage: CGImage {
     get throws {
       let ctm = AffineTransform(scale: _attachmentScaleFactor) as NSAffineTransform

Sources/Overlays/_Testing_AppKit/CMakeLists.txt

@@ -0,0 +1,23 @@
+# This source file is part of the Swift.org open source project
+#
+# Copyright (c) 2024–2025 Apple Inc. and the Swift project authors
+# Licensed under Apache License v2.0 with Runtime Library Exception
+#
+# See http://swift.org/LICENSE.txt for license information
+# See http://swift.org/CONTRIBUTORS.txt for Swift project authors
+
+if (CMAKE_SYSTEM_NAME STREQUAL "Darwin")
+  add_library(_Testing_AppKit
+    Attachments/NSImage+AttachableAsCGImage.swift
+    ReexportTesting.swift)
+
+  target_link_libraries(_Testing_AppKit PUBLIC
+    Testing
+    _Testing_CoreGraphics)
+
+  target_compile_options(_Testing_AppKit PRIVATE
+    -enable-library-evolution
+    -emit-module-interface -emit-module-interface-path $<TARGET_PROPERTY:_Testing_AppKit,Swift_MODULE_DIRECTORY>/_Testing_AppKit.swiftinterface)
+
+  _swift_testing_install_target(_Testing_AppKit)
+endif()

Sources/Overlays/_Testing_AppKit/ReexportTesting.swift

@@ -1,12 +1,12 @@
 //
 // This source file is part of the Swift.org open source project
 //
-// Copyright (c) 2024 Apple Inc. and the Swift project authors
+// Copyright (c) 2024–2025 Apple Inc. and the Swift project authors
 // Licensed under Apache License v2.0 with Runtime Library Exception
 //
 // See https://swift.org/LICENSE.txt for license information
 // See https://swift.org/CONTRIBUTORS.txt for Swift project authors
 //
 
-@_exported @_spi(Experimental) @_spi(ForToolsIntegrationOnly) public import Testing
-@_exported @_spi(Experimental) @_spi(ForToolsIntegrationOnly) public import _Testing_CoreGraphics
+@_exported public import Testing
+@_exported public import _Testing_CoreGraphics

Sources/Overlays/_Testing_CoreGraphics/Attachments/AttachableAsCGImage.swift

@@ -1,7 +1,7 @@
 //
 // This source file is part of the Swift.org open source project
 //
-// Copyright (c) 2024 Apple Inc. and the Swift project authors
+// Copyright (c) 2024–2025 Apple Inc. and the Swift project authors
 // Licensed under Apache License v2.0 with Runtime Library Exception
 //
 // See https://swift.org/LICENSE.txt for license information
@@ -13,12 +13,12 @@ public import CoreGraphics
 private import ImageIO
 
 /// A protocol describing images that can be converted to instances of
-/// ``Testing/Attachment``.
+/// [`Attachment`](https://developer.apple.com/documentation/testing/attachment).
 ///
 /// Instances of types conforming to this protocol do not themselves conform to
-/// ``Testing/Attachable``. Instead, the testing library provides additional
-/// initializers on ``Testing/Attachment`` that take instances of such types and
-/// handle converting them to image data when needed.
+/// [`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:
@@ -27,17 +27,26 @@ private import ImageIO
 /// |-|-|
 /// | 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) |
+/// @Comment {
 /// | 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.
-@_spi(Experimental)
+///
+/// @Metadata {
+///   @Available(Swift, introduced: 6.3)
+/// }
 @available(_uttypesAPI, *)
 public protocol AttachableAsCGImage: 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.

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

@@ -9,7 +9,7 @@
 //
 
 #if SWT_TARGET_OS_APPLE && canImport(CoreGraphics)
-@_spi(Experimental) public import Testing
+public import Testing
 
 public import UniformTypeIdentifiers
 
@@ -64,6 +64,10 @@ extension AttachableImageFormat {
   /// The content type corresponding to this image format.
   ///
   /// The value of this property always conforms to [`UTType.image`](https://developer.apple.com/documentation/uniformtypeidentifiers/uttype-swift.struct/image).
+  ///
+  /// @Metadata {
+  ///   @Available(Swift, introduced: 6.3)
+  /// }
   public var contentType: UTType {
     switch kind {
     case .png:
@@ -89,6 +93,10 @@ extension AttachableImageFormat {
   ///
   /// If `contentType` does not conform to [`UTType.image`](https://developer.apple.com/documentation/uniformtypeidentifiers/uttype-swift.struct/image),
   /// the result is undefined.
+  ///
+  /// @Metadata {
+  ///   @Available(Swift, introduced: 6.3)
+  /// }
   public init(_ contentType: UTType, encodingQuality: Float = 1.0) {
     precondition(
       contentType.conforms(to: .image),

Sources/Overlays/_Testing_CoreGraphics/Attachments/Attachment+AttachableAsCGImage.swift

@@ -1,17 +1,16 @@
 //
 // This source file is part of the Swift.org open source project
 //
-// Copyright (c) 2024 Apple Inc. and the Swift project authors
+// Copyright (c) 2024–2025 Apple Inc. and the Swift project authors
 // Licensed under Apache License v2.0 with Runtime Library Exception
 //
 // See https://swift.org/LICENSE.txt for license information
 // See https://swift.org/CONTRIBUTORS.txt for Swift project authors
 //
 
 #if SWT_TARGET_OS_APPLE && canImport(CoreGraphics)
-@_spi(Experimental) public import Testing
+public import Testing
 
-@_spi(Experimental)
 @available(_uttypesAPI, *)
 extension Attachment {
   /// Initialize an instance of this type that encloses the given image.
@@ -33,7 +32,9 @@ extension Attachment {
   /// |-|-|
   /// | 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) |
+  /// @Comment {
   /// | 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) |
+  /// }
   ///
   /// The testing library uses the image format specified by `imageFormat`. Pass
   /// `nil` to let the testing library decide which image format to use. If you
@@ -42,6 +43,10 @@ extension Attachment {
   /// specify a path extension, or if the path extension you specify doesn't
   /// correspond to an image format the operating system knows how to write, the
   /// testing library selects an appropriate image format for you.
+  ///
+  /// @Metadata {
+  ///   @Available(Swift, introduced: 6.3)
+  /// }
   public init<T>(
     _ image: T,
     named preferredName: String? = nil,
@@ -74,7 +79,9 @@ extension Attachment {
   /// |-|-|
   /// | 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) |
+  /// @Comment {
   /// | 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) |
+  /// }
   ///
   /// The testing library uses the image format specified by `imageFormat`. Pass
   /// `nil` to let the testing library decide which image format to use. If you
@@ -83,8 +90,12 @@ extension Attachment {
   /// specify a path extension, or if the path extension you specify doesn't
   /// correspond to an image format the operating system knows how to write, the
   /// testing library selects an appropriate image format for you.
+  ///
+  /// @Metadata {
+  ///   @Available(Swift, introduced: 6.3)
+  /// }
   public static func record<T>(
-    _ image: consuming T,
+    _ image: T,
     named preferredName: String? = nil,
     as imageFormat: AttachableImageFormat? = nil,
     sourceLocation: SourceLocation = #_sourceLocation

Sources/Overlays/_Testing_CoreGraphics/Attachments/CGImage+AttachableAsCGImage.swift

@@ -1,7 +1,7 @@
 //
 // This source file is part of the Swift.org open source project
 //
-// Copyright (c) 2024 Apple Inc. and the Swift project authors
+// Copyright (c) 2024–2025 Apple Inc. and the Swift project authors
 // Licensed under Apache License v2.0 with Runtime Library Exception
 //
 // See https://swift.org/LICENSE.txt for license information
@@ -11,8 +11,13 @@
 #if SWT_TARGET_OS_APPLE && canImport(CoreGraphics)
 public import CoreGraphics
 
-@_spi(Experimental)
+/// @Metadata {
+///   @Available(Swift, introduced: 6.3)
+/// }
 extension CGImage: AttachableAsCGImage {
+  /// @Metadata {
+  ///   @Available(Swift, introduced: 6.3)
+  /// }
   public var attachableCGImage: CGImage {
     self
   }

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

@@ -1,15 +1,15 @@
 //
 // This source file is part of the Swift.org open source project
 //
-// Copyright (c) 2024 Apple Inc. and the Swift project authors
+// Copyright (c) 2024–2025 Apple Inc. and the Swift project authors
 // Licensed under Apache License v2.0 with Runtime Library Exception
 //
 // See https://swift.org/LICENSE.txt for license information
 // See https://swift.org/CONTRIBUTORS.txt for Swift project authors
 //
 
 #if SWT_TARGET_OS_APPLE && canImport(CoreGraphics)
-@_spi(Experimental) public import Testing
+public import Testing
 private import CoreGraphics
 
 private import ImageIO
@@ -39,7 +39,6 @@ private import UniformTypeIdentifiers
 ///    useful.)
 
 @available(_uttypesAPI, *)
-@_spi(Experimental)
 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()

Sources/Overlays/_Testing_CoreGraphics/CMakeLists.txt

@@ -0,0 +1,26 @@
+# This source file is part of the Swift.org open source project
+#
+# Copyright (c) 2024–2025 Apple Inc. and the Swift project authors
+# Licensed under Apache License v2.0 with Runtime Library Exception
+#
+# See http://swift.org/LICENSE.txt for license information
+# See http://swift.org/CONTRIBUTORS.txt for Swift project authors
+
+if(APPLE)
+  add_library(_Testing_CoreGraphics
+    Attachments/_AttachableImageWrapper+AttachableWrapper.swift
+    Attachments/AttachableAsCGImage.swift
+    Attachments/AttachableImageFormat+UTType.swift
+    Attachments/Attachment+AttachableAsCGImage.swift
+    Attachments/CGImage+AttachableAsCGImage.swift
+    ReexportTesting.swift)
+
+  target_link_libraries(_Testing_CoreGraphics PUBLIC
+    Testing)
+
+  target_compile_options(_Testing_CoreGraphics PRIVATE
+    -enable-library-evolution
+    -emit-module-interface -emit-module-interface-path $<TARGET_PROPERTY:_Testing_CoreGraphics,Swift_MODULE_DIRECTORY>/_Testing_CoreGraphics.swiftinterface)
+
+  _swift_testing_install_target(_Testing_CoreGraphics)
+endif()