Add SnapshotFormat option for audio file vs MD5 checksum snapshots

For repositories with many audio snapshot tests, .caf files can bloat
the repo. This adds a SnapshotFormat enum (.audio / .checksum) so users
can opt into lightweight 32-byte .md5 checksum files instead of full
ALAC audio snapshots. Default is .audio, preserving full backward
compatibility.

Author: jcavar

Sources/AudioSnapshotTesting/Core/AudioSnapshotTesting.swift

@@ -20,17 +20,22 @@ public struct AudioSnapshotTrait: TestTrait, SuiteTrait, TestScoping {
     /// The bit depth for ALAC encoding. Defaults to 16-bit.
     public let bitDepth: AudioBitDepth
 
+    /// The format used for storing snapshot artifacts.
+    public let format: SnapshotFormat
+
     /// Creates a new audio snapshot trait.
     /// - Parameters:
     ///   - record: Whether to record new snapshots. Defaults to `false`.
     ///   - strategy: The snapshot strategy for failure visualization. Defaults to `nil`.
     ///   - autoOpen: Whether to automatically open visualizations. Defaults to `false`.
     ///   - bitDepth: The bit depth for ALAC encoding. Defaults to `.bits16`.
-    public init(record: Bool = false, strategy: VisualisationStrategy? = nil, autoOpen: Bool = false, bitDepth: AudioBitDepth = .bits16) {
+    ///   - format: The format for storing snapshot artifacts. Defaults to `.audio`.
+    public init(record: Bool = false, strategy: VisualisationStrategy? = nil, autoOpen: Bool = false, bitDepth: AudioBitDepth = .bits16, format: SnapshotFormat = .audio) {
         self.record = record
         self.strategy = strategy
         self.autoOpen = autoOpen
         self.bitDepth = bitDepth
+        self.format = format
     }
 
     /// Called by Swift Testing to set up the test scope.
@@ -48,14 +53,16 @@ extension Trait where Self == AudioSnapshotTrait {
     ///   - strategy: The snapshot strategy for failure visualization. Defaults to `nil`.
     ///   - autoOpen: Whether to automatically open visualizations. Defaults to `false`.
     ///   - bitDepth: The bit depth for ALAC encoding. Defaults to `.bits16`.
+    ///   - format: The format for storing snapshot artifacts. Defaults to `.audio`.
     /// - Returns: An `AudioSnapshotTrait` configured with the specified options.
     public static func audioSnapshot(
         record: Bool = false,
         strategy: VisualisationStrategy? = nil,
         autoOpen: Bool = false,
-        bitDepth: AudioBitDepth = .bits16
+        bitDepth: AudioBitDepth = .bits16,
+        format: SnapshotFormat = .audio
     ) -> AudioSnapshotTrait {
-        AudioSnapshotTrait(record: record, strategy: strategy, autoOpen: autoOpen, bitDepth: bitDepth)
+        AudioSnapshotTrait(record: record, strategy: strategy, autoOpen: autoOpen, bitDepth: bitDepth, format: format)
     }
 }
 

Sources/AudioSnapshotTesting/Core/AudioSnapshotTrait.swift

@@ -0,0 +1,7 @@
+/// The format used for storing audio snapshot artifacts.
+public enum SnapshotFormat: Sendable {
+    /// Full ALAC-encoded .caf audio file (current behavior).
+    case audio
+    /// Lightweight MD5 checksum stored in a .md5 text file.
+    case checksum
+}

Sources/AudioSnapshotTesting/Core/SnapshotFormat.swift

@@ -0,0 +1,29 @@
+import CryptoKit
+import Foundation
+
+/// Handles MD5 checksum computation and file I/O for checksum-based snapshots.
+enum AudioChecksumWriter {
+    /// Computes the MD5 checksum of a file at the given URL.
+    /// - Parameter url: The file URL to hash.
+    /// - Returns: A 32-character lowercase hex string.
+    static func computeChecksum(of url: URL) throws -> String {
+        let data = try Data(contentsOf: url)
+        let digest = Insecure.MD5.hash(data: data)
+        return digest.map { String(format: "%02x", $0) }.joined()
+    }
+
+    /// Writes a checksum string to a `.md5` file.
+    /// - Parameters:
+    ///   - checksum: The 32-character hex checksum string.
+    ///   - url: The destination file URL.
+    static func writeChecksum(_ checksum: String, to url: URL) throws {
+        try checksum.write(to: url, atomically: true, encoding: .utf8)
+    }
+
+    /// Reads a checksum string from a `.md5` file.
+    /// - Parameter url: The file URL to read from.
+    /// - Returns: The checksum string (trimmed of whitespace).
+    static func readChecksum(from url: URL) throws -> String {
+        try String(contentsOf: url, encoding: .utf8).trimmingCharacters(in: .whitespacesAndNewlines)
+    }
+}

Sources/AudioSnapshotTesting/Internal/AudioChecksumWriter.swift

@@ -169,6 +169,40 @@ func multiChannelComparison() async throws {
     await assertAudioSnapshot(of: buffer, named: "multiChannelComparison.4ch")
 }
 
+@Test(
+    "Checksum snapshot records and verifies a deterministic buffer",
+    .audioSnapshot(record: false, format: .checksum)
+)
+func checksumRoundTrip() async throws {
+    let signal = synthesizeSignal(
+        frequencyAmplitudePairs: [(440, 0.5)],
+        count: 4410
+    )
+    let buffer = createBuffer(from: signal)
+    await assertAudioSnapshot(of: buffer, named: "checksumRoundTrip.440hz")
+}
+
+@Test(
+    "Checksum snapshot with multiple buffers uses indexed naming",
+    .audioSnapshot(record: false, format: .checksum)
+)
+func checksumMultiBuffer() async throws {
+    let signal1 = synthesizeSignal(
+        frequencyAmplitudePairs: [(440, 0.5)],
+        count: 4410
+    )
+    let signal2 = synthesizeSignal(
+        frequencyAmplitudePairs: [(880, 0.3)],
+        count: 4410
+    )
+    let buffer1 = createBuffer(from: signal1)
+    let buffer2 = createBuffer(from: signal2)
+    await assertAudioSnapshot(
+        of: [buffer1, buffer2],
+        named: "checksumMultiBuffer"
+    )
+}
+
 private func createBuffer(from samples: [Float], sampleRate: Double = 32768) -> AVAudioPCMBuffer {
     createBuffer(channels: [samples], sampleRate: sampleRate)
 }

Tests/AudioSnapshotTestingTests/AudioSnapshotTestingTests.swift

@@ -0,0 +1 @@
+60e4ed9c7ca9ae8b665aab56b5f09cd4

Tests/AudioSnapshotTestingTests/__AudioSnapshots__/AudioSnapshotTestingTests/checksumMultiBuffer.1.md5

@@ -0,0 +1 @@
+15bcba203f8d88260cd8d606496a45aa

Tests/AudioSnapshotTestingTests/__AudioSnapshots__/AudioSnapshotTestingTests/checksumMultiBuffer.2.md5

@@ -0,0 +1 @@
+60e4ed9c7ca9ae8b665aab56b5f09cd4