Skip to content

Commit 21e1a8d

Browse files
committed
fix: add missing documentation
1 parent 247849b commit 21e1a8d

File tree

2 files changed

+44
-3
lines changed

2 files changed

+44
-3
lines changed

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

+41-2
Original file line numberDiff line numberDiff line change
@@ -47,7 +47,46 @@ The **Image Serialization Plugin** relies on the PluginAPI that is a combination
4747
- When an image needs to be serialized, the `ImageSerializer` checks the available plugins for one that supports the requested format.
4848
- If no plugin is found, it defaults to the built-in PNG encoding/decoding methods.
4949

50-
#### Extensibility:
50+
#### Extensibility
5151

52-
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.
52+
The plugin architecture allows developers to introduce new image formats without modifying the core SnapshotTesting library. By creating a new plugin that conforms to `ImageSerializationPlugin`, you can easily add support for additional image formats.
5353

54+
Here are a few example plugins demonstrating how to extend the library with new image formats:
55+
56+
- **[Image Serialization Plugin - HEIC](https://github.com/mackoj/swift-snapshot-testing-plugin-heic)**: Enables storing images in the `.heic` format, which reduces file sizes compared to PNG.
57+
- **[Image Serialization Plugin - WEBP](https://github.com/mackoj/swift-snapshot-testing-plugin-webp)**: Allows storing images in the `.webp` format, which offers better compression than PNG.
58+
- **[Image Serialization Plugin - JXL](https://github.com/mackoj/swift-snapshot-testing-plugin-jxl)**: Facilitates storing images in the `.jxl` format, which provides superior compression and quality compared to PNG.
59+
60+
## Usage
61+
62+
For example, if you want to use JPEG XL as a new image format for your snapshots, you can follow these steps. This approach applies to any image format as long as you have a plugin that conforms to `ImageSerializationPlugin`.
63+
64+
1. **Add the Dependency**: Include the appropriate image serialization plugin as a dependency in your `Package.swift` file. For JPEG XL, it would look like this:
65+
66+
```swift
67+
.package(url: "https://github.com/mackoj/swift-snapshot-testing-plugin-jxl.git", revision: "0.0.1"),
68+
```
69+
70+
2. **Link to Your Test Target**: Add the image serialization plugin to your test target's dependencies:
71+
72+
```swift
73+
.product(name: "JXLImageSerializer", package: "swift-snapshot-testing-plugin-jxl"),
74+
```
75+
76+
3. **Import and Set Up**: In your test file, import the serializer and configure the image format in the `setUp()` method:
77+
78+
```swift
79+
import JXLImageSerializer
80+
81+
override class func setUp() {
82+
SnapshotTesting.imageFormat = JXLImageSerializer.imageFormat
83+
}
84+
```
85+
86+
Alternatively, you can specify the image format for individual assertions:
87+
88+
```swift
89+
assertSnapshot(of: label, as: .image(precision: 0.9, format: JXLImageSerializer.imageFormat))
90+
```
91+
92+
This setup demonstrates how to integrate a specific image format plugin. Replace `JXLImageSerializer` with the appropriate plugin and format for other image formats.

Sources/SnapshotTesting/SnapshotTestingConfiguration.swift

+3-1
Original file line numberDiff line numberDiff line change
@@ -24,6 +24,7 @@ import ImageSerializationPlugin
2424
/// - Parameters:
2525
/// - record: The record mode to use while asserting snapshots.
2626
/// - diffTool: The diff tool to use while asserting snapshots.
27+
/// - imageFormat: The image format used while encoding/decoding images(default: .png).
2728
/// - operation: The operation to perform.
2829
public func withSnapshotTesting<R>(
2930
record: SnapshotTestingConfiguration.Record? = nil,
@@ -44,7 +45,7 @@ public func withSnapshotTesting<R>(
4445

4546
/// Customizes `assertSnapshot` for the duration of an asynchronous operation.
4647
///
47-
/// See ``withSnapshotTesting(record:diffTool:operation:)-2kuyr`` for more information.
48+
/// See ``withSnapshotTesting(record:diffTool:imageFormat:operation:)-2kuyr`` for more information.
4849
public func withSnapshotTesting<R>(
4950
record: SnapshotTestingConfiguration.Record? = nil,
5051
diffTool: SnapshotTestingConfiguration.DiffTool? = nil,
@@ -77,6 +78,7 @@ public struct SnapshotTestingConfiguration: Sendable {
7778
/// See ``Record-swift.struct`` for more information.
7879
public var record: Record?
7980

81+
/// The image format to use while encoding/decoding snapshot tests.
8082
public var imageFormat: ImageSerializationFormat?
8183

8284
public init(

0 commit comments

Comments
 (0)