Unit testing and behavior analysis framework for Beckhoff TwinCAT 3.
Build repeatable tests for your TwinCAT libraries. TC3 UnitTest is a Structured Text framework for testing PLC logic and analyzing its behavior in the PLC runtime.
- Verify logic and data: check function results, limits, tolerances, arrays, and text.
- Analyze cyclic behavior: observe signal changes, edges, sequences, and stability over defined intervals.
- Reuse test scenarios: bind tests to different component instances and parameters, then repeat them after code changes.
- Use the same tests in development and CI: PLCSIM.UnitTest provides the WPF workbench for interactive runs and debugging, plus the CLI for automated regression testing.
- Develop tests with AI assistance: the optional authoring skill helps analyze PLC blocks, select meaningful scenarios, and implement them with TC3 UnitTest.
- A Test Case describes one scenario. Preparations establish its starting conditions; Assertions evaluate its expectations.
- Suites and Run Control compose the application. Suites collect related Test Cases, and Run Control coordinates those Suites through the supplied orchestration.
- A shared Event Buffer connects the tests to the PC. Framework blocks publish lifecycle events, findings, and results for the PC application to evaluate.
The Framework Model describes how these components cooperate and where each responsibility belongs.
Complete API documentation
The offline HTML reference covers blocks, interfaces, methods, and properties, with shared search and linked authoring guides and integration examples.
The same TestCaseBase supports immediate value checks and scenarios spanning
many PLC cycles:
- You define: stimuli, Assertions, phase completion, and resource cleanup.
- The base provides: the lifecycle Sequencer, Start/Reset/Abort handling, timeout supervision, result aggregation, and event reporting.
flowchart LR
P["Preparation state(s)<br/>optional"] --> T["Test State(s)"]
T --> R["Result"]
| Test scenario | Typical use |
|---|---|
| Static checks | Evaluate a calculation, value, or data structure. |
| Single Test State | Observe one condition over time, such as stable feedback or an edge count. |
| Multiple Test States | Apply successive stimuli and evaluate a different expectation in each phase. |
Preparation is optional. Each Test State can finish after one evaluation or remain active across the PLC cycles needed for its observation window.
Preparations make the required starting condition part of the test. Reusable
resource setup, optionally based on PreparationBase, gives repeated runs a
consistent starting point.
Choose typed Assertions for the behavior or data you want to verify:
| Check family | Coverage |
|---|---|
| Boolean and numeric | Conditions, comparisons, limits, ranges, tolerances |
| Floating-point classification | Finite values, NaN, infinity; scalar and array checks |
| Bits and masks | Individual flags and bitfield expectations |
| Arrays | Equality, contained values and patterns, unchanged snapshots |
| Text and tokens | Strings, character codes, array/text checks, token positions and counts |
| Signals and sequences | No-change checks, edges, edge counts, ordered values |
| Time and dates | Durations, calendar values, time of day |
Each check has a name and a retained result, so failed expectations remain identifiable. The Assertion catalogue helps select the matching family and datatype.
TestSuiteBasecollects related Test Cases, schedules their execution, and aggregates their results.RunControlBasecombines Suites into the complete test application and connects it to external run commands.
Both bases include lifecycle Sequencers and collection Orchestrators. Choose Serial, Parallel, or ParallelSlots to run children in order, overlap independent tests, or arrange concurrent groups.
You declare, register, and cyclically call the children. The framework schedules them in one PLC task; you coordinate shared resources.
- Automatic reporting: the base blocks and Assertions generate and publish their standard events. Normal tests need no manual event creation.
- Independent storage: a shared Event Buffer retains the events for PC readout. Wire it once in the application; individual tests need no buffer management or transport code.
- Ready-made constructors: supplied functions create event payloads for custom extensions, including triggers, state transitions, results, and diagnostics. See the event function catalogue.
The companion PLCSIM.UnitTest application reads and acknowledges the events through its TwinCAT profile and turns them into test results:
- WPF workbench: repeat scenarios during library development, inspect failed checks, and follow lifecycle events as an additional debugging workflow.
- CLI automation: execute the same PLC tests in CI, with exit codes for the job result and JUnit XML for reporting. The CI starters cover runner preparation and integration.
Authoring examples and integration strategies cover every level, from an individual Test Case to a complete application with command and Event Buffer wiring.
Consider an opening test with two requirements: open feedback must arrive within 500 ms and then remain stable for 2 s. Preparation and two Test States express that scenario:
| Phase | Scenario logic | Expected observation |
|---|---|---|
| Preparation | Establish the closed starting condition. | ClosedFeedback = TRUE and OpenFeedback = FALSE. |
| Test State 1 | Set OpenCommand := TRUE and measure the response. |
OpenFeedback becomes TRUE within 500 ms. |
| Test State 2 | Keep the command active and observe the feedback for 2 s. | OpenFeedback remains TRUE throughout the interval. |
The Test Case defines the command sequence and observation windows. Two named
Assertions, OpensWithinDeadline and OpenFeedbackStable, distinguish a missed
deadline from feedback that drops out during the hold interval.
- Reuse the scenario: bind separate test instances to other valves and timing parameters.
- Repeat it after changes: add the case to a Suite for WPF development runs and CLI regression checks. Results reach the PC application through the shared Event Buffer.
Use the optional authoring skill with Codex to develop tests using the framework:
- Understand the subject: analyze interfaces, relevant dependencies, retained state, and cyclic behavior.
- Choose useful scenarios: derive boundary, timing, failure, and recovery checks from requirements, making unclear expectations explicit.
- Implement agreed tests: use Assertions, Preparations, and reusable Test Cases with matching lifecycle and call-order guidance.
The package bundles the matching authoring guides, contracts, and API snapshots. You review the proposed expectations and resulting tests.
Download the skill · Installation and compatibility
- Release: 1.0.0, library version
1.0.0.0. - Downloads: Framework-only
.compiled-libraryand.librarypackages plus offline HTML help are available with the release. - Authoring skill: 1.0.0, an optional standalone package with matching framework guidance and API snapshots.
- Source: the solution includes Framework, SelfTests, and Runtime.
- Target: TwinCAT 3.1 Build 4026; documented consumer validation covers Windows Usermode Runtime / x64. See the build workflow for dependencies and verification scope.
- Test Case guide, Preparations, and Assertions: implementation examples and check selection.
- Test Suites and Run Control: collections, orchestration, and complete PLC/PC integration.
- Library installation and offline HTML help: consuming the library and reading its API documentation.
- Architecture, public contracts, and selftest strategy: design and verification details.
- AI-assisted authoring: block analysis, test planning, and implementation with the framework patterns.
- Authoring skill: optional assistance with installation and compatibility guidance.
Sponsorship helps maintain and improve Lorenz Software's open-source PLC testing frameworks and tools. Become a sponsor.
Created by Lorenz Software and available under the MIT license.