This PR adds support for the great work that Eric has completed: https://github.com/pointfreeco/swift-snapshot-testing/pull/628

png support only for now. I'll be working on updating the HEIC library next.

This allows users to make value-level changes before each snapshot is taken. This increases the amount of flexibility and control we are providing to the end user.

Closes #4

The idea of the library is to allow users to stitch multiple variants of the same value into a single image. This is possible using the different traits (such as dynamic text size or user interface style) or image strategies (such as device size).

However, it doesn't allow you to apply customisations to the view which are done at a custom class level. To be clearer, we should add the ability to change variables on the view itself for each test in the stitch.

assertSnapshot(matching: vc, as: .stitch(strategies: [
  ("iPhone 8", .image(on: .iPhone8), configure: { $0.theme = .light }),
  ("iPhone 8 Plus", .image(on: .iPhone8Plus), configure: { $0.theme = .dark }),
]))

I'm fortunate that all of my personal and work projects support Swift Package Manager in some part which enables us to use this project.

I understand not everyone is in the same boat, so if anybody has the need for CocoaPods then feel free to let me know here and I can add compatibility for you.

I won't do it unless someone asks though, always preferable to keep things light and easy!

We should increase the test coverage to demonstrate more real-world examples as opposed to flat blue blobs (which I'm pretty sure are against Apple's HIGs and wouldn't be allowed in production).

I want to demonstrate (and then document with images in the README) various different use cases including:

• Different Themes (A view controller which responds to light/mode dark)
• Different Localisations (A view controller which changes based on the user's locale)
• Different Accessibility Modes (A view controller which supports dynamic text sizes, smart invert, etc)
• Different Devices (A view controller which changes depending on the device or screen size)
• Different Sizes (A view/cell which changes based on the rendered size)

other ideas welcome

I also want to add some extra tests including:

• A performance test covering the entire stitch strategy
• A test which uses a custom strategy which adds random timeouts to the snapshots (and as such will return out of order - testing our sorting solution)
• A test which checks the title trimming approach
• Tests to cover independent units of code throughout the package (especially the calculateImageSize function)

⚠️ I'm writing this down for my own sanity. It's just an idea, and not something I think somebody should actually pick up. Though I'm always interested if people have their own opinions.

Currently, as part of the initialisation of the Snapshotting type we provide the diffing engine as the same as SnapshotTesting's own .image.

This diffing solution will compare pixel to pixel across our entire outputted image... this works as expected, but it could be better with our own solution.

Specifically, if we had the ability to diff each 'nested image' independently, then this would enable us to provide considerably better feedback to the user - aiding in their work to fix the error!

How would we do this?

Well a diffing engine has two requirements.

First of all the ability to losslessly convert the 'Value' (in our case an instance of UIImage) to Data and back to the UIImage. This is in order to save the file to disk. For our use case we can copy what SnapshotTesting does and simply convert to/from PNG.

The second is more complex and is where we have to compare two versions of 'Value' to check if they're the same. We could start with a crude precision check, this would be our "happy path" and would allow the test to quickly succeed if they were identical.

If they were different however, we would need to break each image down into the separate 'nested images' and then run comparison on those. First checking that each set of images contain the same images, and then checking each image for likeness (with an optional precision). This would need access to the original metadata (title/strategy information) which we could pass through.

The key challenge will be trying to break a UIImage down into this object with metadata. Ideally we would store a JSON file alongside the image file in order to safely serve this data - I'm not sure this is feasible without substantial API changes in the SnapshotTesting library. Instead, I think we're going to need to encode this data directly into the image itself 😱

Essentially the first pixel would denote how many lines of pixels are used to decode the data. The rest of the pixels would then be parsed into a Data object, which would be in turn turned into a Codable struct. The exact science here is to be explored, but it is technically viable.

One of the downsides of this approach (besides being awfully complex, and potentially not outweighed by the benefits - more on this later) is that tools which do external diffing might pick up on the subtle changes to our data pixels. Now I don't think this is likely to cause problems though as the data we would encode would simply inform us of the coordinates used to store each image and the title attached. Both of these pieces of information would already cause a significant enough change as to be caught by these external tools.

Is this worth it?

From a nerdy perspective, I'd love to explore it. Though it's very easy to win an argument where we say this is completely unnecessary. I think, if this does get added, we should definitely make it optional (at least initially) and it should be packaged separately requiring users to explicitly opt-in.