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.
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.
Snappy consists of two parts:
- A dotnet CLI tool, called
TcHaxx.Snappy.CLI
, - and the TwinCAT library
snappy
.
- Verify - Supported Tool is installed.
To install the CLI tool execute following command:
dotnet tool install -g TcHaxx.Snappy.CLI
To update to the latest version from Nuget, run:
dotnet tool update -g TcHaxx.Snappy.CLI
dotnet tool uninstall -g TcHaxx.Snappy.CLI
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
Before any tests are being run, TcHaxx.Snappy.CLI
hast to be started, prior.
Run manually via dotnet tools or TwinCAT deployment.
Run snappy
-CLI with following command:
TcHaxx.Snappy.Verify verify [OPTIONS]
See Command verfiy for more options.
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\" |
When dealing with source control, consider the following guidelines for handling Received and Verified files:
-
Exclusion:
- Exclude all files with the pattern
*.received.*
from source control. - To achieve this, add the following line to your
.gitignore
file:*.received.*
- Exclude all files with the pattern
-
Commitment:
- On the other hand, commit all files with the pattern
*.verified.*
to source control.
- On the other hand, commit all files with the pattern
See Verify/README
Snappy.CLI has following CLI commands and options.
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. |
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. |
- 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.