Class Snapshot

Namespace

PDiffy

Assembly

PDiffy.dll

Snapshot tests for PDFs, Word documents, text and JSON: VerifyPdfAsync, VerifyDocxAsync, VerifyTextAsync and VerifyJsonAsync. The approved snapshot lives in {name}.verified.{extension}, and a mismatch writes {name}.received.{extension} and an HTML report, then throws SnapshotException, so it works with any test framework. The settings here apply to every kind.

public static class Snapshot

Inheritance

object

Snapshot

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.MemberwiseClone()

object.ReferenceEquals(object, object)

object.ToString()

Fields

AcceptVariable

Set PDIFFY_ACCEPT=1 to accept every received snapshot as the new verified one. Ignored on CI.

public const string AcceptVariable = "PDIFFY_ACCEPT"

Field Value

string

KeepDocumentVariable

Set PDIFFY_KEEP_DOCUMENT=1, or KeepDocument, to also write the PDF or Word document behind a failing snapshot, as {name}.received.pdf or {name}.received.docx next to the received file, so it can be opened in a viewer. It's on by default on CI, where a document can be hard to make again; PDIFFY_KEEP_DOCUMENT=0 turns it off.

public const string KeepDocumentVariable = "PDIFFY_KEEP_DOCUMENT"

Field Value

string

OpenReportVariable

Set PDIFFY_OPEN_REPORT=1 to open the HTML report of each snapshot that differs from its verified file, in the default browser. Ignored on CI.

public const string OpenReportVariable = "PDIFFY_OPEN_REPORT"

Field Value

string

RunLogVariable

Set PDIFFY_RUN_LOG to a folder to log the verified file every snapshot call uses, one log per test process, so pdiffy unused can find the snapshots no test uses anymore.

public const string RunLogVariable = "PDIFFY_RUN_LOG"

Field Value

string

Properties

DefaultDocxOptions

Options every DOCX snapshot starts with, such as a profile or scrubbers, set once (in a module initializer, say) instead of in each test. Each call's own configure runs after them and adds to them: it can leave out more, but not bring back what these leave out, so keep them to what every test agrees on. The snapshot's first lines list what's ignored, but not what's scrubbed.

public static Action<DocxSnapshotOptions>? DefaultDocxOptions { get; set; }

Property Value

Action<DocxSnapshotOptions>

DefaultPdfOptions

Options every PDF snapshot starts with, such as a profile or scrubbers, set once (in a module initializer, say) instead of in each test. Each call's own configure runs after them and adds to them: it can leave out more, but not bring back what these leave out, so keep them to what every test agrees on. The snapshot's first lines list what's ignored, but not what's scrubbed.

public static Action<PdfSnapshotOptions>? DefaultPdfOptions { get; set; }

Property Value

Action<PdfSnapshotOptions>

DefaultTextOptions

Options every text and JSON snapshot starts with, such as scrubbers, set once (in a module initializer, say) instead of in each test. Each call's own configure runs after them. JSON's own scrubbing of GUIDs and timestamps runs first, so these can keep them with KeepGuids() or KeepDates().

public static Action<TextSnapshotOptions>? DefaultTextOptions { get; set; }

Property Value

Action<TextSnapshotOptions>

Directory

The folder that holds snapshot files, for every kind of snapshot. When null, each snapshot sits next to the test file that made it. A call's Directory option overrides it.

public static string? Directory { get; set; }

Property Value

string

KeepDocument

Whether a failing PDF or Word snapshot also writes the document it came from, as KeepDocumentVariable does. When it's null (the default), KeepDocumentVariable decides, and when that isn't set either, documents are kept on CI and nowhere else. Only a document passed as a stream or bytes can be kept; a PdfUaDocument or DocxDocument has no file to write.

public static bool? KeepDocument { get; set; }

Property Value

bool?

Location

Decides where each snapshot goes, for every kind of snapshot: given the call, return its folder and name. Start from Default, such as call => call.Default with { Folder = ... }, so whatever you don't set keeps its default. When null, every snapshot goes to its default location. A build that maps source paths still needs Directory when PDiffy can't find the test file's folder, since the default is worked out first.

public static Func<SnapshotCall, SnapshotLocation>? Location { get; set; }

Property Value

Func<SnapshotCall, SnapshotLocation>

Methods

ProjectFolder(params string[])

A folder in the test project, for Directory: Snapshot.ProjectFolder("Snapshots"). PDiffy's build file records the project's folder when the test project builds, so unlike a path worked out from the output folder, this is right with any output folder or runtime, as long as the tests run in the checkout that built them.

public static string ProjectFolder(params string[] parts)

Parameters

parts string[]

The folders under the project folder, if any.

Returns

string

Exceptions

SnapshotException

The project's folder wasn't recorded, because PDiffy's build file didn't run or the project sets GenerateAssemblyInfo to false.

VerifyDocx(DocxDocument, Action<DocxSnapshotOptions>?, string, string)

The synchronous version of VerifyDocxAsync, for a test that isn't async: on a mismatch it writes the received file and the report, and throws.

public static void VerifyDocx(DocxDocument docx, Action<DocxSnapshotOptions>? configure = null, string testFile = "", string testName = "")

Parameters

docx DocxDocument

The DOCX to check, already loaded with Load(Stream).

configure Action<DocxSnapshotOptions>

What to leave out or scrub, as for ToSnapshot(Action<DocxSnapshotOptions>?), and the snapshot's Name(string), Variant(string) or Directory(string).

testFile string

Filled in by the compiler with the calling test's file. Leave it out, or pass on your own [CallerFilePath] parameter from a helper.

testName string

Filled in by the compiler with the calling test's method. Leave it out, or pass on your own [CallerMemberName] parameter from a helper.

VerifyDocx(byte[], Action<DocxSnapshotOptions>?, string, string)

The synchronous version of VerifyDocxAsync, for a test that isn't async: on a mismatch it writes the received file and the report, and throws.

public static void VerifyDocx(byte[] docx, Action<DocxSnapshotOptions>? configure = null, string testFile = "", string testName = "")

Parameters

docx byte[]

The DOCX to check, as bytes.

configure Action<DocxSnapshotOptions>

What to leave out or scrub, as for ToSnapshot(Action<DocxSnapshotOptions>?), and the snapshot's Name(string), Variant(string) or Directory(string).

testFile string

Filled in by the compiler with the calling test's file. Leave it out, or pass on your own [CallerFilePath] parameter from a helper.

testName string

Filled in by the compiler with the calling test's method. Leave it out, or pass on your own [CallerMemberName] parameter from a helper.

VerifyDocx(Stream, Action<DocxSnapshotOptions>?, string, string)

The synchronous version of VerifyDocxAsync, for a test that isn't async: on a mismatch it writes the received file and the report, and throws.

public static void VerifyDocx(Stream docx, Action<DocxSnapshotOptions>? configure = null, string testFile = "", string testName = "")

Parameters

docx Stream

The DOCX to check. The stream is left open.

configure Action<DocxSnapshotOptions>

What to leave out or scrub, as for ToSnapshot(Action<DocxSnapshotOptions>?), and the snapshot's Name(string), Variant(string) or Directory(string).

testFile string

Filled in by the compiler with the calling test's file. Leave it out, or pass on your own [CallerFilePath] parameter from a helper.

testName string

Filled in by the compiler with the calling test's method. Leave it out, or pass on your own [CallerMemberName] parameter from a helper.

VerifyDocxAsync(DocxDocument, Action<DocxSnapshotOptions>?, string, string)

Compares the snapshot of a DOCX already loaded with the verified one, as for a stream, so a test that also asserts on the document reads it once.

public static Task VerifyDocxAsync(DocxDocument docx, Action<DocxSnapshotOptions>? configure = null, string testFile = "", string testName = "")

Parameters

docx DocxDocument

The DOCX to check, already loaded with Load(Stream).

configure Action<DocxSnapshotOptions>

What to leave out or scrub, as for ToSnapshot(Action<DocxSnapshotOptions>?), and the snapshot's Name(string), Variant(string) or Directory(string).

testFile string

Filled in by the compiler with the calling test's file. Leave it out, or pass on your own [CallerFilePath] parameter from a helper.

testName string

Filled in by the compiler with the calling test's method. Leave it out, or pass on your own [CallerMemberName] parameter from a helper.

Returns

Task

VerifyDocxAsync(byte[], Action<DocxSnapshotOptions>?, string, string)

Compares the snapshot of a DOCX in a byte array with the verified one, as for a stream.

public static Task VerifyDocxAsync(byte[] docx, Action<DocxSnapshotOptions>? configure = null, string testFile = "", string testName = "")

Parameters

docx byte[]

The DOCX to check, as bytes.

configure Action<DocxSnapshotOptions>

What to leave out or scrub, as for ToSnapshot(Action<DocxSnapshotOptions>?), and the snapshot's Name(string), Variant(string) or Directory(string).

testFile string

Filled in by the compiler with the calling test's file. Leave it out, or pass on your own [CallerFilePath] parameter from a helper.

testName string

Filled in by the compiler with the calling test's method. Leave it out, or pass on your own [CallerMemberName] parameter from a helper.

Returns

Task

VerifyDocxAsync(Stream, Action<DocxSnapshotOptions>?, string, string)

Compares the DOCX's snapshot with the verified one in {name}.verified.docx.txt. On a mismatch it writes {name}.received.docx.txt and an HTML report, {name}.received.diff.html, and throws SnapshotException; when they match it deletes both if an earlier run left them.

public static Task VerifyDocxAsync(Stream docx, Action<DocxSnapshotOptions>? configure = null, string testFile = "", string testName = "")

Parameters

docx Stream

The DOCX to check. The stream is left open.

configure Action<DocxSnapshotOptions>

What to leave out or scrub, as for ToSnapshot(Action<DocxSnapshotOptions>?), and the snapshot's Name(string), Variant(string) or Directory(string).

testFile string

Filled in by the compiler with the calling test's file. Leave it out, or pass on your own [CallerFilePath] parameter from a helper.

testName string

Filled in by the compiler with the calling test's method. Leave it out, or pass on your own [CallerMemberName] parameter from a helper.

Returns

Task

VerifyFile(string, Action<FileSnapshotOptions>?, string, string)

The synchronous version of VerifyFileAsync, for a test that isn't async: on a mismatch it writes the received file and the report, and throws.

public static void VerifyFile(string path, Action<FileSnapshotOptions>? configure = null, string testFile = "", string testName = "")

Parameters

path string

The file to check.

configure Action<FileSnapshotOptions>

The snapshot's Name(string), Variant(string) or Directory(string).

testFile string

Filled in by the compiler with the calling test's file. Leave it out, or pass on your own [CallerFilePath] parameter from a helper.

testName string

Filled in by the compiler with the calling test's method. Leave it out, or pass on your own [CallerMemberName] parameter from a helper.

VerifyFileAsync(string, Action<FileSnapshotOptions>?, string, string)

Compares a file on disk with its verified snapshot, picking the kind from its extension: a .pdf as a PDF, a .docx as a Word document, a .json as JSON, and anything else as text, saved with the file's extension (.txt if it has none). Any other file whose text holds NUL characters, such as an image, isn't text, so the method throws SnapshotException. It uses the suite's default options (DefaultPdfOptions, DefaultDocxOptions, DefaultTextOptions); for other options, read the file and call the method for its kind.

public static Task VerifyFileAsync(string path, Action<FileSnapshotOptions>? configure = null, string testFile = "", string testName = "")

Parameters

path string

The file to check.

configure Action<FileSnapshotOptions>

The snapshot's Name(string), Variant(string) or Directory(string).

testFile string

Filled in by the compiler with the calling test's file. Leave it out, or pass on your own [CallerFilePath] parameter from a helper.

testName string

Filled in by the compiler with the calling test's method. Leave it out, or pass on your own [CallerMemberName] parameter from a helper.

Returns

Task

VerifyJson(string, Action<TextSnapshotOptions>?, string, string)

The synchronous version of VerifyJsonAsync, for a test that isn't async: on a mismatch it writes the received file and the report, and throws.

public static void VerifyJson(string json, Action<TextSnapshotOptions>? configure = null, string testFile = "", string testName = "")

Parameters

json string

The JSON to check.

configure Action<TextSnapshotOptions>

What else to scrub, or what to keep, and the snapshot's Name(string), Variant(string) or Directory(string). The files' extension is always .json.

testFile string

Filled in by the compiler with the calling test's file. Leave it out, or pass on your own [CallerFilePath] parameter from a helper.

testName string

Filled in by the compiler with the calling test's method. Leave it out, or pass on your own [CallerMemberName] parameter from a helper.

VerifyJsonAsync(string, Action<TextSnapshotOptions>?, string, string)

Compares JSON with the verified file after writing it the same way every time: two-space indentation, keys in the order written. Strings (values or keys) that are a GUID or an ISO 8601 timestamp, such as an id or a creation time, are scrubbed unless KeepGuids() or KeepDates() says otherwise; dates written for people, and anything inside longer text, stay unless ScrubGuids() or ScrubDates() asks for them too. Invalid JSON throws SnapshotException.

public static Task VerifyJsonAsync(string json, Action<TextSnapshotOptions>? configure = null, string testFile = "", string testName = "")

Parameters

json string

The JSON to check.

configure Action<TextSnapshotOptions>

What else to scrub, or what to keep, and the snapshot's Name(string), Variant(string) or Directory(string). The files' extension is always .json.

testFile string

Filled in by the compiler with the calling test's file. Leave it out, or pass on your own [CallerFilePath] parameter from a helper.

testName string

Filled in by the compiler with the calling test's method. Leave it out, or pass on your own [CallerMemberName] parameter from a helper.

Returns

Task

VerifyPdf(PdfUaDocument, Action<PdfSnapshotOptions>?, string, string)

The synchronous version of VerifyPdfAsync, for a test that isn't async: on a mismatch it writes the received file and the report, and throws.

public static void VerifyPdf(PdfUaDocument pdf, Action<PdfSnapshotOptions>? configure = null, string testFile = "", string testName = "")

Parameters

pdf PdfUaDocument

The PDF to check, already loaded with Load(Stream).

configure Action<PdfSnapshotOptions>

What to leave out or scrub, as for ToSnapshot(Action<PdfSnapshotOptions>?), and the snapshot's Name(string), Variant(string) or Directory(string).

testFile string

Filled in by the compiler with the calling test's file. Leave it out, or pass on your own [CallerFilePath] parameter from a helper.

testName string

Filled in by the compiler with the calling test's method. Leave it out, or pass on your own [CallerMemberName] parameter from a helper.

VerifyPdf(byte[], Action<PdfSnapshotOptions>?, string, string)

The synchronous version of VerifyPdfAsync, for a test that isn't async: on a mismatch it writes the received file and the report, and throws.

public static void VerifyPdf(byte[] pdf, Action<PdfSnapshotOptions>? configure = null, string testFile = "", string testName = "")

Parameters

pdf byte[]

The PDF to check, as bytes.

configure Action<PdfSnapshotOptions>

What to leave out or scrub, as for ToSnapshot(Action<PdfSnapshotOptions>?), and the snapshot's Name(string), Variant(string) or Directory(string).

testFile string

Filled in by the compiler with the calling test's file. Leave it out, or pass on your own [CallerFilePath] parameter from a helper.

testName string

Filled in by the compiler with the calling test's method. Leave it out, or pass on your own [CallerMemberName] parameter from a helper.

VerifyPdf(Stream, Action<PdfSnapshotOptions>?, string, string)

The synchronous version of VerifyPdfAsync, for a test that isn't async: on a mismatch it writes the received file and the report, and throws.

public static void VerifyPdf(Stream pdf, Action<PdfSnapshotOptions>? configure = null, string testFile = "", string testName = "")

Parameters

pdf Stream

The PDF to check. The stream is left open.

configure Action<PdfSnapshotOptions>

What to leave out or scrub, as for ToSnapshot(Action<PdfSnapshotOptions>?), and the snapshot's Name(string), Variant(string) or Directory(string).

testFile string

Filled in by the compiler with the calling test's file. Leave it out, or pass on your own [CallerFilePath] parameter from a helper.

testName string

Filled in by the compiler with the calling test's method. Leave it out, or pass on your own [CallerMemberName] parameter from a helper.

VerifyPdfAsync(PdfUaDocument, Action<PdfSnapshotOptions>?, string, string)

Compares the snapshot of a PDF already loaded with the verified one, as for a stream, so a test that also asserts on the document reads it once.

public static Task VerifyPdfAsync(PdfUaDocument pdf, Action<PdfSnapshotOptions>? configure = null, string testFile = "", string testName = "")

Parameters

pdf PdfUaDocument

The PDF to check, already loaded with Load(Stream).

configure Action<PdfSnapshotOptions>

What to leave out or scrub, as for ToSnapshot(Action<PdfSnapshotOptions>?), and the snapshot's Name(string), Variant(string) or Directory(string).

testFile string

Filled in by the compiler with the calling test's file. Leave it out, or pass on your own [CallerFilePath] parameter from a helper.

testName string

Filled in by the compiler with the calling test's method. Leave it out, or pass on your own [CallerMemberName] parameter from a helper.

Returns

Task

VerifyPdfAsync(byte[], Action<PdfSnapshotOptions>?, string, string)

Compares the snapshot of a PDF in a byte array with the verified one, as for a stream.

public static Task VerifyPdfAsync(byte[] pdf, Action<PdfSnapshotOptions>? configure = null, string testFile = "", string testName = "")

Parameters

pdf byte[]

The PDF to check, as bytes.

configure Action<PdfSnapshotOptions>

What to leave out or scrub, as for ToSnapshot(Action<PdfSnapshotOptions>?), and the snapshot's Name(string), Variant(string) or Directory(string).

testFile string

Filled in by the compiler with the calling test's file. Leave it out, or pass on your own [CallerFilePath] parameter from a helper.

testName string

Filled in by the compiler with the calling test's method. Leave it out, or pass on your own [CallerMemberName] parameter from a helper.

Returns

Task

VerifyPdfAsync(Stream, Action<PdfSnapshotOptions>?, string, string)

Compares the PDF's snapshot with the verified one in {name}.verified.pdfua.txt. On a mismatch it writes {name}.received.pdfua.txt and an HTML report, {name}.received.diff.html, and throws SnapshotException; when they match it deletes both if an earlier run left them.

public static Task VerifyPdfAsync(Stream pdf, Action<PdfSnapshotOptions>? configure = null, string testFile = "", string testName = "")

Parameters

pdf Stream

The PDF to check. The stream is left open.

configure Action<PdfSnapshotOptions>

What to leave out or scrub, as for ToSnapshot(Action<PdfSnapshotOptions>?), and the snapshot's Name(string), Variant(string) or Directory(string).

testFile string

Filled in by the compiler with the calling test's file. Leave it out, or pass on your own [CallerFilePath] parameter from a helper.

testName string

Filled in by the compiler with the calling test's method. Leave it out, or pass on your own [CallerMemberName] parameter from a helper.

Returns

Task

VerifyText(string, Action<TextSnapshotOptions>?, string, string)

The synchronous version of VerifyTextAsync, for a test that isn't async: on a mismatch it writes the received file and the report, and throws.

public static void VerifyText(string text, Action<TextSnapshotOptions>? configure = null, string testFile = "", string testName = "")

Parameters

text string

The text to check.

configure Action<TextSnapshotOptions>

What to scrub, such as dates or GUIDs, and the snapshot's Name(string), Variant(string), Directory(string) or Extension(string).

testFile string

Filled in by the compiler with the calling test's file. Leave it out, or pass on your own [CallerFilePath] parameter from a helper.

testName string

Filled in by the compiler with the calling test's method. Leave it out, or pass on your own [CallerMemberName] parameter from a helper.

VerifyTextAsync(string, Action<TextSnapshotOptions>?, string, string)

Compares text with the verified file exactly: whitespace counts, and the one exception is that CRLF line endings are read as LF.

public static Task VerifyTextAsync(string text, Action<TextSnapshotOptions>? configure = null, string testFile = "", string testName = "")

Parameters

text string

The text to check.

configure Action<TextSnapshotOptions>

What to scrub, such as dates or GUIDs, and the snapshot's Name(string), Variant(string), Directory(string) or Extension(string).

testFile string

Filled in by the compiler with the calling test's file. Leave it out, or pass on your own [CallerFilePath] parameter from a helper.

testName string

Filled in by the compiler with the calling test's method. Leave it out, or pass on your own [CallerMemberName] parameter from a helper.

Returns

Task