Meziantou.Framework.SnapshotTesting.SkiaSharp 1.0.13

Meziantou.Framework.SnapshotTesting.SkiaSharp

Meziantou.Framework.SnapshotTesting.SkiaSharp extends Meziantou.Framework.SnapshotTesting with support for SkiaSharp images, enabling snapshot validation of SKImage, SKBitmap, SKPixmap, and SKSurface objects stored as PNG, JPEG, or WebP files.

Setup

Call AddSkiaSharp() on your SnapshotSettings to register the SkiaSharp serializer and comparer:

using System.Runtime.CompilerServices;
using Meziantou.Framework.SnapshotTesting;
using Meziantou.Framework.SnapshotTesting.SkiaSharp;

internal static class SnapshotConfiguration
{
    [ModuleInitializer]
    internal static void Initialize()
    {
        SnapshotSettings.Default.AddSkiaSharp();
    }
}

Then validate images from your tests:

public sealed class SampleTests
{
    [Fact]
    public void ValidateImage()
    {
        using var bitmap = SKBitmap.Decode("sample.png");
        Snapshot.Validate(bitmap, SnapshotType.Png);
    }
}

Note that SkiaSharp requires the native libraries to be available at runtime. They are included in the SkiaSharp package for Windows and macOS. On Linux, add a reference to SkiaSharp.NativeAssets.Linux.

Image comparison

By default, images are compared pixel-by-pixel (exact comparison). To allow minor rendering differences, configure a Structural Similarity Index (SSIM) threshold:

// In the module initializer shown above
SnapshotSettings.Default.AddSkiaSharp(new ImageComparisonSettings
{
    SimilarityThreshold = 0.99f, // 0.0 = completely different, 1.0 = identical
});

When SimilarityThreshold is set, the images must have the same dimensions and their score must be greater than or equal to the threshold. The score is the mean SSIM over every 7×7 window of the images (uniform weights, sample covariance, K1 = 0.01, K2 = 0.03), the value scikit-image's structural_similarity(expected, actual, data_range=255, channel_axis=-1) computes with its default parameters. The R, G, and B channels are premultiplied by the alpha channel and averaged, and the score is the lower of that value and the SSIM of the alpha channel, so opacity differences are detected. Because the score is a mean, a localized difference lowers it in proportion to the area it covers: a difference confined to 1% of the image lowers it by about 0.01 at most. Fully transparent pixels are equal whatever color they hide, with both the exact and the SSIM comparison, and a snapshot that cannot be decoded does not match.

16-bit PNGs follow the same rule as the built-in ImageComparer and the ImageSharp package: the exact comparison sees every bit of every sample (an 8-bit sample v equals the 16-bit sample v × 257), and the SSIM reduces each sample to 8 bits by keeping its high byte. SkiaSharp cannot decode 16-bit samples exactly, so when the 8-bit pixels of a 16-bit PNG match, the exact comparison checks the full samples with the built-in decoder of Meziantou.Framework.SnapshotTesting.

When images do not match, the assertion message says why under the changed file: an image cannot be decoded, the images have different sizes or different pixels, or the SSIM score is below the threshold.