feat: add Image Serialization Plugin

Author: mackoj

Package.swift

@@ -19,6 +19,10 @@ let package = Package(
       name: "SnapshotTestingPlugin",
       targets: ["SnapshotTestingPlugin"]
     ),
+    .library(
+      name: "ImageSerializationPlugin",
+      targets: ["ImageSerializationPlugin"]
+    ),
     .library(
       name: "InlineSnapshotTesting",
       targets: ["InlineSnapshotTesting"]
@@ -30,9 +34,16 @@ let package = Package(
   targets: [
     .target(
       name: "SnapshotTesting",
-      dependencies: ["SnapshotTestingPlugin"]
+      dependencies: [
+        "ImageSerializationPlugin",
+        "SnapshotTestingPlugin"
+      ]
     ),
     .target(name: "SnapshotTestingPlugin"),
+    .target(
+      name: "ImageSerializationPlugin",
+      dependencies: ["SnapshotTestingPlugin"]
+    ),
     .target(
       name: "InlineSnapshotTesting",
       dependencies: [

Sources/ImageSerializationPlugin/ImageSerializationPlugin.swift

@@ -0,0 +1,87 @@
+#if canImport(SwiftUI)
+import Foundation
+import SnapshotTestingPlugin
+
+#if canImport(UIKit)
+import UIKit.UIImage
+/// A type alias for `UIImage` when UIKit is available.
+public typealias SnapImage = UIImage
+#elseif canImport(AppKit)
+import AppKit.NSImage
+/// A type alias for `NSImage` when AppKit is available.
+public typealias SnapImage = NSImage
+#endif
+
+/// A type alias that combines `ImageSerialization` and `SnapshotTestingPlugin` protocols.
+///
+/// `ImageSerializationPlugin` is a convenient alias used to conform to both `ImageSerialization` and `SnapshotTestingPlugin` protocols.
+/// This allows for image serialization plugins that also support snapshot testing, leveraging the Objective-C runtime while maintaining image serialization capabilities.
+public typealias ImageSerializationPlugin = ImageSerialization & SnapshotTestingPlugin
+
+// TODO: async throws will be added later to encodeImage and decodeImage
+/// A protocol that defines methods for encoding and decoding images in various formats.
+///
+/// The `ImageSerialization` protocol is intended for classes that provide functionality to serialize (encode) and deserialize (decode) images.
+/// Implementing this protocol allows a class to specify the image format it supports and to handle image data conversions.
+/// This protocol is designed to be used in environments where SwiftUI is available and supports platform-specific image types via `SnapImage`.
+public protocol ImageSerialization {
+  
+  /// The image format that the serialization plugin supports.
+  ///
+  /// Each conforming class must specify the format it handles, using the `ImageSerializationFormat` enum. This property helps the `ImageSerializer`
+  /// determine which plugin to use for a given format during image encoding and decoding.
+  static var imageFormat: ImageSerializationFormat { get }
+  
+  /// Encodes a `SnapImage` into a data representation.
+  ///
+  /// This method converts the provided image into the appropriate data format. It may eventually support asynchronous operations and error handling using `async throws`.
+  ///
+  /// - Parameter image: The image to be encoded.
+  /// - Returns: The encoded image data, or `nil` if encoding fails.
+  func encodeImage(_ image: SnapImage) -> Data?
+  
+  /// Decodes image data into a `SnapImage`.
+  ///
+  /// This method converts the provided data back into an image. It may eventually support asynchronous operations and error handling using `async throws`.
+  ///
+  /// - Parameter data: The image data to be decoded.
+  /// - Returns: The decoded image, or `nil` if decoding fails.
+  func decodeImage(_ data: Data) -> SnapImage?
+}
+#endif
+
+/// An enumeration that defines the image formats supported by the `ImageSerialization` protocol.
+///
+/// The `ImageSerializationFormat` enum is used to represent various image formats. It includes a predefined case for PNG images and a flexible case for plugins,
+/// allowing for the extension of formats via plugins identified by unique string values.
+public enum ImageSerializationFormat: RawRepresentable, Sendable, Equatable {
+  /// Represents the default image format aka PNG.
+  case png
+  
+  /// Represents a custom image format provided by a plugin.
+  ///
+  /// This case allows for the extension of image formats beyond the predefined ones by using a unique string identifier.
+  case plugins(String)
+  
+  /// Initializes an `ImageSerializationFormat` instance from a raw string value.
+  ///
+  /// This initializer converts a string value into an appropriate `ImageSerializationFormat` case.
+  ///
+  /// - Parameter rawValue: The string representation of the image format.
+  public init?(rawValue: String) {
+    switch rawValue {
+      case "png": self = .png
+      default: self = .plugins(rawValue)
+    }
+  }
+  
+  /// The raw string value of the `ImageSerializationFormat`.
+  ///
+  /// This computed property returns the string representation of the current image format.
+  public var rawValue: String {
+    switch self {
+      case .png: return "png"
+      case let .plugins(value): return value
+    }
+  }
+}

Sources/SnapshotTesting/AssertSnapshot.swift

@@ -1,11 +1,49 @@
 import XCTest
+import ImageSerializationPlugin
 
 #if canImport(Testing)
   // NB: We are importing only the implementation of Testing because that framework is not available
   //     in Xcode UI test targets.
   @_implementationOnly import Testing
 #endif
 
+/// Whether or not to change the default output image format to something else.
+@available(
+  *,
+  deprecated,
+  message:
+    "Use 'withSnapshotTesting' to customize the image output format. See the documentation for more information."
+)
+public var imageFormat: ImageSerializationFormat {
+  get {
+    _imageFormat
+  }
+  set { _imageFormat = newValue }
+}
+
+@_spi(Internals)
+public var _imageFormat: ImageSerializationFormat {
+  get {
+#if canImport(Testing)
+    if let test = Test.current {
+      for trait in test.traits.reversed() {
+        if let diffTool = (trait as? _SnapshotsTestTrait)?.configuration.imageFormat {
+          return diffTool
+        }
+      }
+    }
+#endif
+    return __imageFormat
+  }
+  set {
+    __imageFormat = newValue
+  }
+}
+
+@_spi(Internals)
+public var __imageFormat: ImageSerializationFormat = .png
+
+
 /// Enhances failure messages with a command line diff tool expression that can be copied and pasted
 /// into a terminal.
 @available(

Sources/SnapshotTesting/Documentation.docc/Articles/ImageSerializationPlugin.md

@@ -0,0 +1,53 @@
+# Image Serialization Plugin
+
+Image Serialization Plugin is a plugin based on the PluginAPI, it provides support for encoding and decoding images. It leverages the plugin architecture to extend its support for different image formats without needing to modify the core system.
+
+Plugins that conform to the `ImageSerializationPlugin` protocol can be registered into the `PluginRegistry` and used to encode or decode images in different formats, such as PNG, JPEG, WebP, HEIC, and more.
+
+When a plugin supporting a specific image format is available, the `ImageSerializer` can dynamically choose the correct plugin based on the image format required, ensuring modularity and scalability in image handling.
+
+
+# Image Serialization Plugin
+
+The **Image Serialization Plugin** extends the functionality of the SnapshotTesting library by enabling support for multiple image formats through a plugin architecture. This PluginAPI allows image encoding and decoding to be easily extended without modifying the core logic of the system.
+
+## Overview
+
+The **Image Serialization Plugin** provides an interface for encoding and decoding images in various formats. By conforming to both the `ImageSerialization` and `SnapshotTestingPlugin` protocols, it integrates with the broader plugin system, allowing for the seamless addition of new image formats. The default implementation supports PNG, but this architecture allows users to define custom plugins for other formats.
+
+### Image Serialization Plugin Architecture
+
+The **Image Serialization Plugin** relies on the PluginAPI that is a combination of protocols and a centralized registry to manage and discover plugins. The architecture allows for dynamic registration of image serialization plugins, which can be automatically discovered at runtime using the Objective-C runtime. This makes the system highly extensible, with plugins being automatically registered without the need for manual intervention.
+
+#### Key Components:
+
+1. **`ImageSerialization` Protocol**:
+   - Defines the core methods for encoding and decoding images.
+   - Requires plugins to specify the image format they support using the `ImageSerializationFormat` enum.
+   - Provides methods for encoding (`encodeImage`) and decoding (`decodeImage`) images.
+
+2. **`ImageSerializationFormat` Enum**:
+   - Represents supported image formats.
+   - Includes predefined formats such as `.png` and extensible formats through the `.plugins(String)` case, allowing for custom formats to be introduced via plugins.
+
+3. **`ImageSerializer` Class**:
+   - Responsible for encoding and decoding images using the registered plugins.
+   - Retrieves available plugins from the `PluginRegistry` and uses the first matching plugin for the requested image format.
+   - Provides default implementations for PNG encoding and decoding if no plugin is available for a given format.
+
+#### Example Plugin Flow:
+
+1. **Plugin Discovery**:
+   - Plugins are automatically discovered at runtime through the Objective-C runtime, which identifies classes that conform to both the `ImageSerialization` and `SnapshotTestingPlugin` protocols.
+
+2. **Plugin Registration**:
+   - Each plugin registers itself with the `PluginRegistry`, allowing it to be retrieved when needed for image serialization.
+
+3. **Image Encoding/Decoding**:
+   - When an image needs to be serialized, the `ImageSerializer` checks the available plugins for one that supports the requested format.
+   - If no plugin is found, it defaults to the built-in PNG encoding/decoding methods.
+
+#### Extensibility:
+
+The plugin architecture allows developers to introduce new image formats without modifying the core SnapshotTesting library. By creating a new plugin that conforms to `ImageSerialization` and `SnapshotTestingPlugin`, other formats.
+

Sources/SnapshotTesting/Documentation.docc/SnapshotTesting.md

@@ -26,6 +26,7 @@ Powerfully flexible snapshot testing.
 ### Plugins
 
 - <doc:Plugins>
+- <doc:ImageSerializationPlugin>
 
 ### Deprecations
 

Sources/SnapshotTesting/SnapshotTestingConfiguration.swift

@@ -1,3 +1,5 @@
+import ImageSerializationPlugin
+
 /// Customizes `assertSnapshot` for the duration of an operation.
 ///
 /// Use this operation to customize how the `assertSnapshot` function behaves in a test. It is most
@@ -26,13 +28,14 @@
 public func withSnapshotTesting<R>(
   record: SnapshotTestingConfiguration.Record? = nil,
   diffTool: SnapshotTestingConfiguration.DiffTool? = nil,
+  imageFormat: ImageSerializationFormat? = nil,
   operation: () throws -> R
 ) rethrows -> R {
   try SnapshotTestingConfiguration.$current.withValue(
     SnapshotTestingConfiguration(
       record: record ?? SnapshotTestingConfiguration.current?.record ?? _record,
-      diffTool: diffTool ?? SnapshotTestingConfiguration.current?.diffTool
-        ?? SnapshotTesting._diffTool
+      diffTool: diffTool ?? SnapshotTestingConfiguration.current?.diffTool ?? SnapshotTesting._diffTool,
+      imageFormat: imageFormat ?? SnapshotTestingConfiguration.current?.imageFormat ?? _imageFormat
     )
   ) {
     try operation()
@@ -45,12 +48,14 @@ public func withSnapshotTesting<R>(
 public func withSnapshotTesting<R>(
   record: SnapshotTestingConfiguration.Record? = nil,
   diffTool: SnapshotTestingConfiguration.DiffTool? = nil,
+  imageFormat: ImageSerializationFormat? = nil,
   operation: () async throws -> R
 ) async rethrows -> R {
   try await SnapshotTestingConfiguration.$current.withValue(
     SnapshotTestingConfiguration(
       record: record ?? SnapshotTestingConfiguration.current?.record ?? _record,
-      diffTool: diffTool ?? SnapshotTestingConfiguration.current?.diffTool ?? _diffTool
+      diffTool: diffTool ?? SnapshotTestingConfiguration.current?.diffTool ?? _diffTool,
+      imageFormat: imageFormat ?? SnapshotTestingConfiguration.current?.imageFormat ?? _imageFormat
     )
   ) {
     try await operation()
@@ -71,13 +76,17 @@ public struct SnapshotTestingConfiguration: Sendable {
   ///
   /// See ``Record-swift.struct`` for more information.
   public var record: Record?
+  
+  public var imageFormat: ImageSerializationFormat?
 
   public init(
     record: Record?,
-    diffTool: DiffTool?
+    diffTool: DiffTool?,
+    imageFormat: ImageSerializationFormat?
   ) {
     self.diffTool = diffTool
     self.record = record
+    self.imageFormat = imageFormat
   }
 
   /// The record mode of the snapshot test.

Sources/SnapshotTesting/SnapshotsTestTrait.swift

@@ -2,6 +2,7 @@
   // NB: We are importing only the implementation of Testing because that framework is not available
   //     in Xcode UI test targets.
   @_implementationOnly import Testing
+  import ImageSerializationPlugin
 
   @_spi(Experimental)
   extension Trait where Self == _SnapshotsTestTrait {
@@ -12,12 +13,14 @@
     ///   - diffTool: The diff tool to use in failure messages.
     public static func snapshots(
       record: SnapshotTestingConfiguration.Record? = nil,
-      diffTool: SnapshotTestingConfiguration.DiffTool? = nil
+      diffTool: SnapshotTestingConfiguration.DiffTool? = nil,
+      imageFormat: ImageSerializationFormat? = nil
     ) -> Self {
       _SnapshotsTestTrait(
         configuration: SnapshotTestingConfiguration(
           record: record,
-          diffTool: diffTool
+          diffTool: diffTool,
+          imageFormat: imageFormat
         )
       )
     }

Sources/SnapshotTesting/Snapshotting/CALayer.swift

@@ -1,3 +1,4 @@
+import ImageSerializationPlugin
 #if os(macOS)
   import AppKit
   import Cocoa
@@ -14,7 +15,7 @@
     /// assertSnapshot(of: layer, as: .image(precision: 0.99))
     /// ```
     public static var image: Snapshotting {
-      return .image(precision: 1)
+      return .image(precision: 1, imageFormat: imageFormat)
     }
 
     /// A snapshot strategy for comparing layers based on pixel equality.
@@ -25,9 +26,9 @@
     ///     match. 98-99% mimics
     ///     [the precision](http://zschuessler.github.io/DeltaE/learn/#toc-defining-delta-e) of the
     ///     human eye.
-    public static func image(precision: Float, perceptualPrecision: Float = 1) -> Snapshotting {
+    public static func image(precision: Float, perceptualPrecision: Float = 1, imageFormat: ImageSerializationFormat) -> Snapshotting {
       return SimplySnapshotting.image(
-        precision: precision, perceptualPrecision: perceptualPrecision
+        precision: precision, perceptualPrecision: perceptualPrecision, imageFormat: imageFormat
       ).pullback { layer in
         let image = NSImage(size: layer.bounds.size)
         image.lockFocus()
@@ -46,7 +47,7 @@
   extension Snapshotting where Value == CALayer, Format == UIImage {
     /// A snapshot strategy for comparing layers based on pixel equality.
     public static var image: Snapshotting {
-      return .image()
+      return .image(imageFormat: imageFormat)
     }
 
     /// A snapshot strategy for comparing layers based on pixel equality.
@@ -59,12 +60,12 @@
     ///     human eye.
     ///   - traits: A trait collection override.
     public static func image(
-      precision: Float = 1, perceptualPrecision: Float = 1, traits: UITraitCollection = .init()
+      precision: Float = 1, perceptualPrecision: Float = 1, traits: UITraitCollection = .init(), imageFormat: ImageSerializationFormat
     )
       -> Snapshotting
     {
       return SimplySnapshotting.image(
-        precision: precision, perceptualPrecision: perceptualPrecision, scale: traits.displayScale
+        precision: precision, perceptualPrecision: perceptualPrecision, scale: traits.displayScale, imageFormat: imageFormat
       ).pullback { layer in
         renderer(bounds: layer.bounds, for: traits).image { ctx in
           layer.setNeedsLayout()