Verify.ImageMagick

Extends Verify to allow verification of documents via Magick.NET.

See Milestones for release notes.

Converts documents pdfs to png for verification.

Verifying a pdf produces:

• The pdf itself as .verified.pdf. This can be omitted with ExcludeTargets.
• A .verified.txt with the page count.
• A png render of every page as #page_0001.verified.png, #page_0002.verified.png, etc.

Verifying an svg produces the svg as .verified.svg and a png render of it as .verified.png.

The page files are named by Verify's paged documents support, which every Verify plugin that splits a document into pages shares. So do the settings that choose what is verified.

Contains comparers for png, jpg, bmp, and tiff.

Sponsors

Entity Framework Extensions

Entity Framework Extensions is a major sponsor and is proud to contribute to the development this project.

Developed using JetBrains IDEs

NuGet

• https://nuget.org/packages/Verify.ImageMagick

Usage

[ModuleInitializer]
public static void Init()
{
    VerifyImageMagick.Initialize();
    VerifyImageMagick.RegisterComparers(threshold: 0.5);
}

^{snippet source | anchor}

Initialize registers the pdf to png converter and all comparers.

Choosing what is verified

What a pdf or an svg is split into is controlled by Verify's settings for paged documents, which replace the options this plugin had of its own.

PagesToInclude limits the pages of a pdf that are verified, to its first pages or to those a delegate accepts. The pdf itself is still verified whole, and the info file still holds the number of pages it has:

[Test]
public Task PagesToInclude() =>
    VerifyFile("sample.pdf")
        .PagesToInclude(1);

^{snippet source | anchor}

ExcludeDerivedTargets("png") leaves out the png renders, keeping the pdf or the svg. The render is skipped rather than dropped afterwards. The pages of a pdf are then only counted, so its info file still says how many there are:

[Test]
public Task ExcludeDerivedTargets() =>
    VerifyFile("sample.pdf")
        .ExcludeDerivedTargets("png");

^{snippet source | anchor}

It applies to a png rendered from a pdf or an svg. A png, webp or tiff that is itself being verified is not affected.

ExcludeTargets("pdf") leaves out the pdf, keeping its pages and its info file. A password-protected pdf requires it.

Each can also be set for every test, on VerifierSettings:

[ModuleInitializer]
public static void Init()
{
    VerifyImageMagick.Initialize();

    // For every test: no png, so only the source document is verified
    VerifierSettings.ExcludeDerivedTargets("png");
}

^{snippet source | anchor}

PDF converter

To register only the pdf to png converter:

VerifyImageMagick.RegisterPdfToPngConverter();

Verify a file

[Test]
public Task VerifyPdf() =>
    VerifyFile("sample.pdf");

^{snippet source | anchor}

Verify a Stream

[Test]
public Task VerifyPdfStream()
{
    var stream = new MemoryStream(File.ReadAllBytes("sample.pdf"));
    return Verify(stream, "pdf");
}

^{snippet source | anchor}

Result

Samples.VerifyPdf.verified.txt:

{
  PageCount: 2
}

^{snippet source | anchor}

Samples.VerifyPdf#page_0001.verified.png:

Image Comparers

The following will use ImageMagick to compare the images instead of the default binary comparison.

[Test]
public Task CompareImage() =>
    VerifyFile("sample.jpg");

^{snippet source | anchor}

Register all comparers

All comparers can be registered:

VerifyImageMagick.RegisterComparers();

Override transparent background

For images with a transparent background, that background can be overridden:

[Test]
public Task BackgroundColor() =>
    VerifyFile("transparent.png")
        .ImageMagickBackground(MagickColors.Blue);

^{snippet source | anchor}

Open password-protected PDFs

For password-protected PDF, the password can be provided to allow verification:

[Test]
public Task PdfPassword() =>
    VerifyFile("password.pdf")
        .ImageMagickPdfPassword("password")
        .ExcludeTargets("pdf");

^{snippet source | anchor}

Reviewing changes

A change to a pdf is a change to several files: the pdf, its info file, and every page. Verify tells the diff tool that the pages and the info file were derived from the pdf, and DiffEngineViewer, which draws a pdf's pages itself, shows them as one row and accepts them together. Other diff tools are given each file, as before. The png of an svg is derived from the svg in the same way.

When the pdf or the svg has itself changed, what was derived from it is compared exactly, skipping any comparer registered for png. ImageMagick writes the time into every png it renders, so every page of a changed pdf is then reported as changed, whether or not it draws differently.

Migrating from 3.x

Version 4 moves to the paged document support in Verify 33.3. The options of this plugin that chose what was verified are now settings of Verify:

3.x	4.x
Initialize(ImageMagickOutputs.None)	Initialize() and VerifierSettings.ExcludeDerivedTargets("png")
Initialize(ImageMagickOutputs.Png) or Initialize(ImageMagickOutputs.All)	Initialize()
.PagesToInclude(2), an extension method of this plugin	.PagesToInclude(2), a member of Verify's SettingsTask and VerifySettings

A call to PagesToInclude compiles unchanged. It can now also take a delegate, and both it and ExcludeDerivedTargets can be set for one verification or, on VerifierSettings, for all of them.

The page of a pdf is named by its number, which is 1 based. It was named by an index, which was 0 based and missing for a pdf with one page. A pdf also has an info file now, holding its page count:

3.x	4.x
Tests.Report#00.verified.png	Tests.Report#page_0001.verified.png
Tests.Report#01.verified.png	Tests.Report#page_0002.verified.png
Tests.Report.verified.png, of a pdf with one page	Tests.Report#page_0001.verified.png
Tests.Mail#Attachment.00.verified.png, of a pdf that is a target named Attachment	Tests.Mail#Attachment.page_0001.verified.png
	Tests.Report.verified.txt, the info file

The .verified.pdf is unchanged, and so are the .verified.svg and .verified.png of an svg.

Renamed snapshots show as a new file and a pending delete. Accepting both, or running once with AutoVerify, moves a test over. A page draws as it did, but ImageMagick writes the time into every png it renders, so an accepted page differs from the file it replaces by those bytes, and source control shows a rename with a small change.

Icon

Swirl designed by Philipp Petzka from The Noun Project.