Configuring the external diff tool

By default, the test framework opens a visual diff tool when an aspect test fails—when the expected snapshot differs from the actual output. This feature uses the open-source DiffEngine library, which automatically detects and launches installed diff tools.

Metalama test runner settings

To configure the test runner settings:

Install the metalama tool as described in Installing the Metalama command line tool.
Run the following command to open the configuration file in your default editor:
Full screen
```
metalama config edit testRunner
```

This opens the testRunner.json file with the following default content:

Full screen

{
  "LaunchDiffTool": true,
  "MaxDiffToolInstances": 1
}

Available settings:

Setting	Default	Description
`LaunchDiffTool`	`true`	Set to `false` to disable automatic diff tool launching. Useful for CI/CD pipelines.
`MaxDiffToolInstances`	`1`	Maximum number of diff tool instances that can be opened simultaneously.

Supported diff tools

DiffEngine automatically detects installed diff tools. Supported tools include:

Free: Visual Studio Code, WinMerge, P4Merge, KDiff3, Meld, Vim, Neovim
Commercial: Beyond Compare, Araxis Merge, Kaleidoscope (macOS), DeltaWalker, Rider
Integrated: Visual Studio, TortoiseGit variants

For the complete list, see the DiffEngine documentation.

Selecting the diff tool

DiffEngine checks for tools in a predefined order. To prioritize a specific tool, set the DiffEngine_ToolOrder environment variable:

Full screen

# Windows PowerShell - prioritize Visual Studio Code
$env:DiffEngine_ToolOrder = "VisualStudioCode"

# Or specify multiple tools in order of preference
$env:DiffEngine_ToolOrder = "BeyondCompare,VisualStudioCode,WinMerge"

To permanently set this, add the environment variable to your system or user environment variables.

Using DiffEngineTray (Windows)

For a better workflow, install DiffEngineTray, a Windows system tray application that tracks pending snapshot changes:

Full screen

dotnet tool install -g DiffEngineTray
diffenginetray

DiffEngineTray provides:

Accept/Discard buttons: Quickly accept or discard pending changes from the system tray
Batch operations: Accept or discard all pending changes at once
Keyboard shortcuts: Configurable hotkeys for common operations
Auto-start: Option to run at Windows startup

Disabling diff tools for CI/CD

On build servers, you typically want to disable diff tool launching. DiffEngine automatically detects common CI environments (GitHub Actions, Azure DevOps, Jenkins, TeamCity, etc.) and disables itself.

To explicitly disable, use one of these methods:

Set the Metalama setting in testRunner.json:
Full screen
```
{ "LaunchDiffTool": false }
```
Set the DiffEngine environment variable:
Full screen
```
$env:DiffEngine_Disabled = "true"
```

ReSharper and Rider

When running tests in ReSharper or Rider with diff tools enabled, you may see an "orphaned processes" dialog when tests complete while diff tools are still open. To prevent this:

Open Tools → Options → Unit Testing (ReSharper) or Settings → Unit Testing (Rider)
Disable Check for orphaned processes spawned by test runner