Skip to content

Reduce duplicated code between Darwin's and Windows' image attachments. #1270

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 10 commits into from
Aug 18, 2025
Merged

Reduce duplicated code between Darwin's and Windows' image attachments. #1270

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
10 commits
Select commit Hold shift + click to select a range
80f6237
Reduce duplicated code between Darwin's and Windows' image attachments.
grynspan Aug 15, 2025
08dd994
Teach Swift about an unreachable code path
grynspan Aug 15, 2025
3aa81da
Adjust import visibility
grynspan Aug 15, 2025
ebd6b9f
D.R.Y.
grynspan Aug 15, 2025
c1d7cd5
Unify platform-specific comments (as much as possible) so that docume…
grynspan Aug 18, 2025
a260a37
Fix typo
grynspan Aug 18, 2025
19f3f06
Fix table headers
grynspan Aug 18, 2025
97fc51d
Adjustments to the supported types table
grynspan Aug 18, 2025
a406ce4
Fix some broken links when building DocC from a package
grynspan Aug 18, 2025
7c1f88d
Fix backtick typo
grynspan Aug 18, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
17 changes: 8 additions & 9 deletions Sources/Overlays/_Testing_CoreGraphics/Attachments/AttachableAsCGImage.swift
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -20,22 +20,21 @@ private import ImageIO
/// initializers on ``Testing/Attachment`` that take instances of such types and
/// handle converting them to image data when needed.
///
/// The following system-provided image types conform to this protocol and can
/// be attached to a test:
/// You can attach instances of the following system-provided image types to a
/// test:
///
/// - [`CGImage`](https://developer.apple.com/documentation/coregraphics/cgimage)
/// - [`CIImage`](https://developer.apple.com/documentation/coreimage/ciimage)
/// - [`NSImage`](https://developer.apple.com/documentation/appkit/nsimage)
/// (macOS)
/// - [`UIImage`](https://developer.apple.com/documentation/uikit/uiimage)
/// (iOS, watchOS, tvOS, visionOS, and Mac Catalyst)
/// | 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.
@_spi(Experimental)
@available(_uttypesAPI, *)
public protocol AttachableAsCGImage {
public protocol AttachableAsCGImage: SendableMetatype {
/// An instance of `CGImage` representing this image.
///
/// - Throws: Any error that prevents the creation of an image.
Expand Down
49 changes: 25 additions & 24 deletions Sources/Overlays/_Testing_CoreGraphics/Attachments/Attachment+AttachableAsCGImage.swift
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -26,15 +26,14 @@ extension Attachment {
/// This value is used when recording issues associated with the
/// attachment.
///
/// The following system-provided image types conform to the
/// ``AttachableAsCGImage`` protocol and can be attached to a test:
/// You can attach instances of the following system-provided image types to a
/// test:
///
/// - [`CGImage`](https://developer.apple.com/documentation/coregraphics/cgimage)
/// - [`CIImage`](https://developer.apple.com/documentation/coreimage/ciimage)
/// - [`NSImage`](https://developer.apple.com/documentation/appkit/nsimage)
/// (macOS)
/// - [`UIImage`](https://developer.apple.com/documentation/uikit/uiimage)
/// (iOS, watchOS, tvOS, visionOS, and Mac Catalyst)
/// | 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) |
///
/// 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
Expand All @@ -48,8 +47,12 @@ extension Attachment {
named preferredName: String? = nil,
as imageFormat: AttachableImageFormat? = nil,
sourceLocation: SourceLocation = #_sourceLocation
) where AttachableValue == _AttachableImageWrapper<T> {
let imageWrapper = _AttachableImageWrapper(image: image, imageFormat: imageFormat)
) where T: AttachableAsCGImage, AttachableValue == _AttachableImageWrapper<T> {
let imageWrapper = _AttachableImageWrapper(
image: image._copyAttachableValue(),
imageFormat: imageFormat,
deinitializingWith: { _ in }
)
self.init(imageWrapper, named: preferredName, sourceLocation: sourceLocation)
}

Expand All @@ -64,17 +67,14 @@ extension Attachment {
/// - sourceLocation: The source location of the call to this function.
///
/// This function creates a new instance of ``Attachment`` wrapping `image`
/// and immediately attaches it to the current test.
/// and immediately attaches it to the current test. You can attach instances
/// of the following system-provided image types to a test:
///
/// The following system-provided image types conform to the
/// ``AttachableAsCGImage`` protocol and can be attached to a test:
///
/// - [`CGImage`](https://developer.apple.com/documentation/coregraphics/cgimage)
/// - [`CIImage`](https://developer.apple.com/documentation/coreimage/ciimage)
/// - [`NSImage`](https://developer.apple.com/documentation/appkit/nsimage)
/// (macOS)
/// - [`UIImage`](https://developer.apple.com/documentation/uikit/uiimage)
/// (iOS, watchOS, tvOS, visionOS, and Mac Catalyst)
/// | 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) |
///
/// 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
Expand All @@ -88,19 +88,20 @@ extension Attachment {
named preferredName: String? = nil,
as imageFormat: AttachableImageFormat? = nil,
sourceLocation: SourceLocation = #_sourceLocation
) where AttachableValue == _AttachableImageWrapper<T> {
) where T: AttachableAsCGImage, AttachableValue == _AttachableImageWrapper<T> {
let attachment = Self(image, named: preferredName, as: imageFormat, sourceLocation: sourceLocation)
Self.record(attachment, sourceLocation: sourceLocation)
}
}

// MARK: -

@_spi(Experimental) // STOP: not part of ST-0014
@available(_uttypesAPI, *)
extension Attachment where AttachableValue: AttachableWrapper, AttachableValue.Wrapped: AttachableAsCGImage {
/// The image format to use when encoding the represented image.
@_disfavoredOverload
public var imageFormat: AttachableImageFormat? {
// FIXME: no way to express `where AttachableValue == _AttachableImageWrapper<???>` on a property
@_disfavoredOverload public var imageFormat: AttachableImageFormat? {
// FIXME: no way to express `where AttachableValue == _AttachableImageWrapper<???>` on a property (see rdar://47559973)
(attachableValue as? _AttachableImageWrapper<AttachableValue.Wrapped>)?.imageFormat
}
}
Expand Down
34 changes: 0 additions & 34 deletions Sources/Overlays/_Testing_CoreGraphics/Attachments/ImageAttachmentError.swift
View file
Open in desktop

This file was deleted.

50 changes: 5 additions & 45 deletions ...Attachments/_AttachableImageWrapper.swift → ...hableImageWrapper+AttachableWrapper.swift
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -13,7 +13,7 @@
private import CoreGraphics

private import ImageIO
import UniformTypeIdentifiers
private import UniformTypeIdentifiers

/// ## Why can't images directly conform to Attachable?
///
Expand All @@ -38,53 +38,13 @@ import UniformTypeIdentifiers
/// (And no, the language does not let us write `where T: Self` anywhere
/// useful.)

/// A wrapper type for image types such as `CGImage` and `NSImage` that can be
/// attached indirectly.
///
/// You do not need to use this type directly. Instead, initialize an instance
/// of ``Attachment`` using an instance of an image type that conforms to
/// ``AttachableAsCGImage``. The following system-provided image types conform
/// to the ``AttachableAsCGImage`` protocol and can be attached to a test:
///
/// - [`CGImage`](https://developer.apple.com/documentation/coregraphics/cgimage)
/// - [`CIImage`](https://developer.apple.com/documentation/coreimage/ciimage)
/// - [`NSImage`](https://developer.apple.com/documentation/appkit/nsimage)
/// (macOS)
/// - [`UIImage`](https://developer.apple.com/documentation/uikit/uiimage)
/// (iOS, watchOS, tvOS, visionOS, and Mac Catalyst)
@_spi(Experimental)
@available(_uttypesAPI, *)
public final class _AttachableImageWrapper<Image>: Sendable where Image: AttachableAsCGImage {
/// The underlying image.
///
/// `CGImage` and `UIImage` are sendable, but `NSImage` is not. `NSImage`
/// instances can be created from closures that are run at rendering time.
/// The AppKit cross-import overlay is responsible for ensuring that any
/// instances of this type it creates hold "safe" `NSImage` instances.
nonisolated(unsafe) let image: Image

/// The image format to use when encoding the represented image.
let imageFormat: AttachableImageFormat?

init(image: Image, imageFormat: AttachableImageFormat?) {
self.image = image._copyAttachableValue()
self.imageFormat = imageFormat
}
}

// MARK: -

@available(_uttypesAPI, *)
extension _AttachableImageWrapper: AttachableWrapper {
public var wrappedValue: Image {
image
}

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 image.attachableCGImage
let attachableCGImage = try wrappedValue.attachableCGImage

// Create the image destination.
let contentType = AttachableImageFormat.computeContentType(for: imageFormat, withPreferredName: attachment.preferredName)
Expand All @@ -93,8 +53,8 @@ extension _AttachableImageWrapper: AttachableWrapper {
}

// Configure the properties of the image conversion operation.
let orientation = image._attachmentOrientation
let scaleFactor = image._attachmentScaleFactor
let orientation = wrappedValue._attachmentOrientation
let scaleFactor = wrappedValue._attachmentScaleFactor
let properties: [CFString: Any] = [
kCGImageDestinationLossyCompressionQuality: CGFloat(imageFormat?.encodingQuality ?? 1.0),
kCGImagePropertyOrientation: orientation,
Expand Down
39 changes: 20 additions & 19 deletions Sources/Overlays/_Testing_WinSDK/Attachments/AttachableAsIWICBitmapSource.swift
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,8 +9,7 @@
//

#if os(Windows)
@_spi(Experimental) import Testing

private import Testing
public import WinSDK

/// A protocol describing images that can be converted to instances of
Expand All @@ -21,13 +20,14 @@ public import WinSDK
/// initializers on ``Testing/Attachment`` that take instances of such types and
/// handle converting them to image data when needed.
///
/// The following system-provided image types conform to this protocol and can
/// be attached to a test:
/// You can attach instances of the following system-provided image types to a
/// test:
///
/// - [`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)
/// | 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,
Expand Down Expand Up @@ -93,26 +93,27 @@ public protocol _AttachableByAddressAsIWICBitmapSource {
}

/// 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.
///
/// The following system-provided image types conform to this protocol and can
/// be attached to a test:
/// You can attach instances of the following system-provided image types to a
/// test:
///
/// - [`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)
/// | 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.
@_spi(Experimental)
public protocol AttachableAsIWICBitmapSource {
public protocol AttachableAsIWICBitmapSource: SendableMetatype {
/// Create a WIC bitmap source representing an instance of this type.
///
/// - Returns: A pointer to a new WIC bitmap source representing this image.
Expand Down
5 changes: 2 additions & 3 deletions Sources/Overlays/_Testing_WinSDK/Attachments/AttachableImageFormat+CLSID.swift
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,8 +9,7 @@
//

#if os(Windows)
@_spi(Experimental) import Testing

@_spi(Experimental) public import Testing
public import WinSDK

extension AttachableImageFormat {
Expand Down Expand Up @@ -258,7 +257,7 @@ extension AttachableImageFormat {
///
/// If `clsid` does not represent an image encoder type supported by WIC, the
/// result is undefined. For a list of image encoders supported by WIC, see
/// the documentation for the [IWICBitmapEncoder](https://learn.microsoft.com/en-us/windows/win32/api/wincodec/nn-wincodec-iwicbitmapencoder)
/// the documentation for the [`IWICBitmapEncoder`](https://learn.microsoft.com/en-us/windows/win32/api/wincodec/nn-wincodec-iwicbitmapencoder)
/// class.
public init(_ clsid: CLSID, encodingQuality: Float = 1.0) {
self.init(kind: .systemValue(clsid), encodingQuality: encodingQuality)
Expand Down
Loading