snappy

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

During the assertion phase, Snappy performs the following steps:

1. It serializes the test result and saves it in a file that corresponds to the test-suite and test name.
2. In subsequent test executions, it re-serializes the result and compares it to the existing file.
3. 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
4. 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:

1. Exclude files:

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

     *.received.*
     

2. 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.
-a --auto-verify	no	Auto-accept any changes.
-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