snappy

Snappy is a Snapshot Testing framework, like Verify, designed for TwinCAT 3.

During the assertion phase, Snappy performs the following steps:

It serializes the test result and saves it in a file that corresponds to the test-suite and test name.
In subsequent test executions, it re-serializes the result and compares it to the existing file.
If the two snapshots do not match, the test fails.
This discrepancy could indicate either an unexpected change or the need to update the reference snapshot to reflect the new result
The validated files can the be added to source control.

Example using `TcUnit`

FUNCTION_BLOCK FB_TcUnitExample EXTENDS FB_TestSuite
VAR
	hr				: HRESULT;		
	fbTcUnitAdapter : FB_TcUnitAdapter;
	
	stActual		: ST_DemoDataType;
	{attribute 'analysis' := '-33'}
	stResult		: ST_VerificationResult;
END_VAR

TEST('Test some stuff with TcHaxx.Snappy');

// ARRANGE

// ACT
stActual := F_CreateDemoData();

// ASSERT
hr := fbTcUnitAdapter.Verify(anyArg:= stActual);

IF NOT PENDING(hr) THEN
	TEST_FINISHED_NAMED('Test some stuff with TcHaxx.Snappy');
END_IF

Find more examples in the examples PLC project.

Install

Snappy consists of two parts:

A dotnet CLI tool, called TcHaxx.Snappy.CLI,

See How to manage .NET tools
and the TwinCAT library snappy.

Prerequisites

Verify - Supported Tool is installed.

TcHaxx.Snappy.CLI

To install the CLI tool execute following command:

dotnet tool install -g TcHaxx.Snappy.CLI

Update

To update to the latest version from Nuget, run:

dotnet tool update -g  TcHaxx.Snappy.CLI

Uninstall

dotnet tool uninstall -g TcHaxx.Snappy.CLI

Run install command

To install the required TwinCAT libraries, simply run the following command:

TcHaxx.Snappy.CLI install

This command will install all required dependencies:

************************************************************************************************************************
                                               TcHaxx.Snappy.CLI V0.1.0.0
                                           Copyright (c) 2024 densogiaichned
                                            https://github.com/TcHaxx/snappy
************************************************************************************************************************

[00:00:01 INF] Using TwinCAT profile "C:\TwinCAT\3.1\Components\Plc\Profiles\TwinCAT PLC Control_Build_4024.55.profile"
[00:00:01 INF] Installing TwinCAT libraries ...
[00:00:20 INF] RepTool.exe: Repository Tool
Copyright © 1994-2020 by 3S-Smart Software Solutions GmbH. All rights reserved.

Arguments:  --profile='TwinCAT PLC Control_Build_4024.55' --installLibsRecursNoOverwrite "%USERPROFILE%\.dotnet\tools\.store\tchaxx.snappy.cli"

Library installed: %USERPROFILE%\.dotnet\tools\.store\tchaxx.snappy.cli\0.1.0\tchaxx.snappy.cli\0.1.0\content\.dist\rplc.library
Library installed: %USERPROFILE%\.dotnet\tools\.store\tchaxx.snappy.cli\0.1.0\tchaxx.snappy.cli\0.1.0\content\.dist\snappy.library

Usage

Before any tests are being run, TcHaxx.Snappy.CLI hast to be started, prior.
Run manually via dotnet tools or TwinCAT deployment.

dotnet tools

Run snappy-CLI with following command:

TcHaxx.Snappy.Verify verify [OPTIONS]

See Command verfiy for more options.

TwinCAT 3 PLC Deployment

See Category Deployment

To automatically start TcHaxx.Snappy.CLI you may want to add following event to your PLC project properties:

Event	Command Type	Parameter 1	Parameter 2
Activate Configuration	Execute	`cmd /c start TcHaxx.Snappy.CLI verify -d \"%SOLUTIONPATH%.snappy-verified\"`

Source control: Received and Verified files

When dealing with source control, consider the following guidelines for handling Received and Verified files:

Exclude files:
- Exclude all files with the pattern *.received.* from source control.
- To achieve this, add the following line to your .gitignore file:
```
*.received.*
```
Commit files:
- Commit all files with the pattern *.verified.* to source control.

See Verify/README

Commands and Options

Snappy.CLI has following CLI commands and options.

Command `install`

This command installs all dependencies, such as rplc.library and of course snappy.library.

TcHaxx.Snappy.CLI install [OPTIONS]

Option	Required	Default	Description
`--tc-profile`	`no`	`latest`	TwinCAT profile to use, e.g. `latest` or specific version `TwinCAT PLC Control_Build_4024.54`, defaults to `latest`.
`--tool-path`	`no`	`%USERPROFILE%\.dotnet\tools\.store\tchaxx.snappy.cli`	Directory, where `TcHaxx.Snappy.CLI` was installed, e.g. `dotnet tool install -g TcHaxx.Snappy.CLI`.
`-l` `--log-level`	`no`	`Information`	Minimum `LogEventLevel`, defaults to `Information`.
`--help`	`no`		Display help screen.
`--version`	`no`		Display version information.

Command `verify`

TcHaxx.Snappy.CLI verify [OPTIONS]

Option	Required	Default	Description
`-d` `--dir`	`no`	`./TcHaxx.Snappy.Verified`	Directory of verified snapshot files.
`-c` `--compact-diff`	`no`	`true`	Diff output as compact as possible.
`-p` `--port`	`no`	`25000`	AmsPort of the Server (snappy).
`-f` `--fpp`	`no`	`5`	Floating point precision for `REAL`/`LREAL` values.
`-l` `--log-level`	`no`	`Information`	Minimum `LogEventLevel`, defaults to `Information`.
`--help`	`no`		Display help screen.
`--version`	`no`		Display version information.

Acknowledgments

TcUnit - A unit testing framework for Beckhoff's TwinCAT 3
CommandLineParser - A command line parsing library for .NET applications.
Verify - A library used for snapshot testing.
Serilog - A logging library for .NET applications.
TF6000_ADS_DOTNET_V5_Samples - Sample code for the Version 6.X series of the TwinCAT ADS .NET Packages

TcHaxx/snappy