/snappy

A Snapshot Testing framework for TwinCAT 3

Primary LanguageC#MIT LicenseMIT

CI/CD NuGet version (TcHaxx.Snappy.CLI)

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:

Prerequisites

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.
-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