repository·main·Indexed 42 days ago
https://github.com/verifytests/diffengineA foundational component for Snapshot and Approval testing libraries that manages the launching and cleanup of various diff tools across Windows, macOS, and Linux. It supports a wide range of tools including AraxisMerge, BeyondCompare, Meld, KDiff3, and Visual Studio Code, and provides a native macOS renderer for visual diffing.
If DiffEngineTray is running, the viewer will also list pending file moves and deletes in the same queue as snapshots.
Accept all will sweep through snapshots, moves, and deletes, but will still skip conflicted snapshots.DiffEngine attempts to resolve diff tools in a specific priority order. If multiple tools are installed on your system, DiffEngine will use the first one it finds in its internal priority list. The default order is as follows:
When using DiffRunner.LaunchAsync(tempFile, targetFile), the engine selects a tool based on the following priority:
DiffTool instance returned by AddTool* methods and pass it directly to DiffRunner.LaunchAsync.// Automatic resolution (uses the most recently added compatible tool)
await DiffRunner.LaunchAsync(tempFile, targetFile);
// Explicit launch (uses the specific tool instance)
var resolvedTool = DiffTools.AddToolBasedOn(...);
await DiffRunner.LaunchAsync(resolvedTool!, "PathToTempFile", "PathToTargetFile");DiffEngineViewer compares image files (.png, .jpg, .jpeg, .gif, .bmp, .webp, and .ico) as pictures rather than text.
Key behaviors:
images are identical, images differ, or only <file> exists (for new snapshots)..png, .jpg, .jpeg, .gif, .bmp, .ico.png, .jpg, .jpeg, .gif, .bmp.png extension that contains non-PNG data will report its format as unrecognized rather than attempting to render bytes as text.The macOS renderer uses ImageIO instead of NSImage to ensure it retrieves the file's actual pixels rather than a screen-sized representation.
Caching Logic:
Capturing Bitmaps:
deview_capture draws into its own bitmap context rather than using the existing view. This ensures that scale, color space, and font smoothing/subpixel settings are pinned, preventing issues where the capture would otherwise inherit the window's backing scale. This also allows capture to function without a window server, making snapshot tests more stable.When DiffEngine generates inline snapshots for C#, it follows specific rules for literal formatting based on the content and the source file's style:
\, ", control characters, and \uXXXX). Multi-line content uses raw string literals ("""). Empty content is rendered as "".""") or one more than the longest run of quotes in the content (e.g., """" if the content contains """).To produce identical text in your own tools, use the public CsStringLiteral.Render method.
// single line content
await Verify(value).Snapshot("the value");
// multi-line content
await Verify(value).Snapshot(
"""
line one
line two
""");When DiffEngineTray is running, it acts as the primary owner of the snapshot queue. The viewer interacts with the tray via a socket.
Key Behaviors:
--attach flag to connect a viewer to a running tray. The tray will start a viewer automatically whenever a new snapshot arrives if no window is currently open.obj/VerifyInline/ directory. Note that a crash or a kill command will skip this step and result in the loss of pending file moves and deletes.DiffEngine manages how external diff tools are launched based on whether a file is being verified for the first time or if a difference is detected during an ongoing verification.
When an input is verified for the first time, behavior depends on whether an EmptyFiles match for the current file extension exists:
EmptyFiles match is found: The tool launches to compare the input against that empty file.EmptyFiles match is found: No tool is launched.When a difference is detected between the input and an existing verified file, the behavior depends on whether a tool is already running:
A new tool instance will be launched.
The behavior depends on your Auto Refresh and Mdi settings:
| Auto Refresh | Mdi | Behavior |
|---|---|---|
true | true | No action. Current instance will refresh |
true | false | No action. Current instance will refresh |
false | true | Open new instance. Previous instance must be manually closed |
false | false | Kill current and open new instance |
Note: The bundled DiffEngineViewer is an exception; it queues failing pairs into a single window and does not follow the logic above.
A conflict occurs when a test run under multiple target frameworks (e.g., net8.0 and net9.0) produces different content for the same call site.
* in the pending list. The pane header will indicate the active framework (e.g., received (net8.0)).v key or the Variant button to cycle through the different framework contents.Accept all command (and Shift+A) will skip conflicted entries to avoid picking sides incorrectly. It will report how many conflicted items still require manual review.DiffEngine's behavior when launching tools depends on whether the input is being verified for the first time or if a difference has been detected during an ongoing verification.
When an input is verified for the first time, DiffEngine looks for an EmptyFiles matching the file extension.
If a difference is detected between the input and an existing verified file, behavior depends on whether a tool is already running for that specific test:
A new tool instance will be launched.
The behavior depends on your Auto Refresh and Mdi (Multiple Document Interface) settings:
| Auto Refresh | Mdi | Behavior |
|---|---|---|
| true | true | No action. Current instance will refresh |
| true | false | No action. Current instance will refresh |
| false | true | Open new instance. Previous instance must be manually closed |
| false | false | Kill current and open new instance |
Note: The bundled DiffEngineViewer is an exception; it queues every failing pair into a single window regardless of these settings.
When a patch is accepted, DiffEngine rewrites the source code. The rendering logic follows these rules:
""").""."""" if the content contains """).