Mocks

Description

This package provides comprehensive predefined mocks for the AXUnit testing framework. It includes simple timer mocks as well as advanced configurable mocks for complex testing scenarios with multiple timers.

Install this package

apax add @simatic-ax/mocks --dev

Namespace

Simatic.Ax.Mocks;

Available Mocks

Simple Timer Mocks

⚠️Important Limitation: Simple mocks set ALL timers in your function block to the same state. Use them only when:

• You have a single timer in your function block, OR
• All timers should have the same state (all elapsed or all waiting)

For testing multiple timers with different states, use ConfigurableOnDelayMock or IdentifierBasedOnDelayMock.

System.Timer Mocks (signal/duration interface)

Name	Output	ElapsedTime	Use Case
OnDelayMock_false	FALSE	0ms	Timer not elapsed
OnDelayMock_true	TRUE	duration	Timer elapsed
OffDelayMock_false	FALSE	0ms	Timer not elapsed
OffDelayMock_true	TRUE	duration	Timer elapsed

IEC 61131-3 Standard Mocks (IN/PT interface)

Name	Q Output	ET	Use Case
TON_Mock_false	FALSE	0ms	On-Delay not elapsed
TON_Mock_true	TRUE	PT	On-Delay elapsed
TOF_Mock_false	FALSE	0ms	Off-Delay not elapsed
TOF_Mock_true	TRUE	PT	Off-Delay elapsed

Example - Single Timer (✅ Correct Usage):

FUNCTION_BLOCK SingleTimerController
VAR
startupTimer : OnDelay;
END_VAR
startupTimer(signal := enable, duration := T#5s);
END_FUNCTION_BLOCK
{Test}
METHOD PUBLIC Test_StartupComplete
// ✅ CORRECT: Only one timer - simple mock works perfectly
AxUnit.Mocking.Mock(NAME_OF(OnDelay), NAME_OF(OnDelayMock_true));
controller(enable := TRUE);
Equal(expected := TRUE, actual := controller.isReady);
END_METHOD

Example - All Timers Same State (✅ Correct Usage):

FUNCTION_BLOCK MultiTimerAllSame
VAR
timer1, timer2, timer3 : OnDelay;
END_VAR
// All timers must be elapsed
IF timer1.output AND timer2.output AND timer3.output THEN
allReady := TRUE;
END_IF;
END_FUNCTION_BLOCK
{Test}
METHOD PUBLIC Test_AllTimersElapsed
// ✅ CORRECT: All timers need same state (all TRUE)
AxUnit.Mocking.Mock(NAME_OF(OnDelay), NAME_OF(OnDelayMock_true));
controller(enable := TRUE);
Equal(expected := TRUE, actual := controller.allReady);
END_METHOD

Example - Mixed Timer States (❌ Wrong Usage):

FUNCTION_BLOCK MixedTimerStates
VAR
timer1, timer2, timer3 : OnDelay;
END_VAR
// Need: timer1=TRUE, timer2=FALSE, timer3=TRUE
END_FUNCTION_BLOCK
{Test}
METHOD PUBLIC Test_MixedStates
// ❌ WRONG: Simple mocks cannot create mixed states!
// All timers will be TRUE or all FALSE
AxUnit.Mocking.Mock(NAME_OF(OnDelay), NAME_OF(OnDelayMock_true));
// ✅ SOLUTION: Use ConfigurableOnDelayMock or IdentifierBasedOnDelayMock instead!
END_METHOD

📖 See SimpleMocks_RealWorld_Test.st for complete examples.

Advanced Configurable Mocks

ConfigurableOnDelayMock Family

Best for: Sequential timers with consistent call order and different states

• Supports up to 4 timer instances with individual states
• Call-order based identification (1st call = T1, 2nd call = T2, etc.)
• Works with timers having identical durations
• Simple configuration
• Available for: OnDelay, OffDelay, TON, TOF

📖 Full Documentation

Available Mocks:

• ConfigurableOnDelayMock + ConfigurableOnDelayMockPayload - For OnDelay
• ConfigurableOffDelayMock + ConfigurableOffDelayMockPayload - For OffDelay
• ConfigurableTONMock + ConfigurableTONMockPayload - For TON
• ConfigurableTOFMock + ConfigurableTOFMockPayload - For TOF

payload.ResetCounter();
// Timer 1: elapsed
payload.T1_Enabled := TRUE;
payload.T1_Output := TRUE;
payload.T1_ElapsedTime := T#1s;
// Timer 2: waiting (different state!)
payload.T2_Enabled := TRUE;
payload.T2_Output := FALSE;
payload.T2_ElapsedTime := T#500ms;
// Timer 3: elapsed
payload.T3_Enabled := TRUE;
payload.T3_Output := TRUE;
payload.T3_ElapsedTime := T#5s;
AxUnit.Mocking.Mock(
mockeeFn := NAME_OF(OnDelay), mockFn := NAME_OF(ConfigurableOnDelayMock),
payload := payload
);

IdentifierBasedOnDelayMock Family

Best for: Conditional timer logic (e.g., IF mode=1 THEN timer2 ELSE timer3)

• Supports up to 4 timer instances with individual states
• Position-based identification with explicit call positions
• Perfect for conditional timer usage
• Duration-independent
• Available for: OnDelay, OffDelay, TON, TOF

📖 Full Documentation

Available Mocks:

• IdentifierBasedOnDelayMock + IdentifierBasedOnDelayMockPayload - For OnDelay
• IdentifierBasedOffDelayMock + IdentifierBasedOffDelayMockPayload - For OffDelay
• IdentifierBasedTONMock + IdentifierBasedTONMockPayload - For TON
• IdentifierBasedTOFMock + IdentifierBasedTOFMockPayload - For TOF

payload.ResetCounter();
// Position 1: Always called
payload.T1_Enabled := TRUE;
payload.T1_CallPosition := 1;
payload.T1_Output := TRUE;
// Position 2: Called in mode 1
payload.T2_Enabled := TRUE;
payload.T2_CallPosition := 2;
payload.T2_Output := FALSE;
// Position 2: Called in mode 2 (same position, different timer!)
payload.T3_Enabled := TRUE;
payload.T3_CallPosition := 2;
payload.T3_Output := TRUE;
AxUnit.Mocking.Mock(
mockeeFn := NAME_OF(OnDelay), mockFn := NAME_OF(IdentifierBasedOnDelayMock),
payload := payload
);

Quick Start Examples

Example 1: Simple Single Timer Mock

USING System.Timer;
USING AxUnit.Assert;
NAMESPACE Simatic.Ax.Mocks
FUNCTION_BLOCK FunctionBlockWhichUsesTimer
VAR_INPUT
enable : BOOL;
END_VAR
VAR_OUTPUT
timerStatus : STRING;
END_VAR
VAR
ton : OnDelay;
END_VAR
ton(signal := enable, duration := T#10s);
IF (ton.output) THEN
timerStatus := 'ELAPSED';
ELSIF (ton.signal AND NOT ton.output) THEN
timerStatus := 'RUNNING';
ELSIF (NOT ton.signal) THEN
timerStatus := 'IDLE';
END_IF;
END_FUNCTION_BLOCK
{TestFixture}
CLASS TestFunctionBlockWhichUsesTimer
VAR
testInstance : FunctionBlockWhichUsesTimer;
END_VAR
{Test}
METHOD PUBLIC FunctionBlockReturnsElapsedWhenEnabledAndTimeHasElapsed
// ✅ CORRECT: Single timer - simple mock is perfect
AxUnit.Mocking.Mock(NAME_OF(OnDelay), NAME_OF(OnDelayMock_true));
testInstance(enable := TRUE);
Equal(expected := 'ELAPSED', actual := testInstance.timerStatus);
END_METHOD
END_CLASS
END_NAMESPACE

Example 2: Multiple Timers with Different States

{Test}
METHOD PUBLIC TestMultipleTimersWithDifferentStates
VAR
payload : ConfigurableOnDelayMockPayload;
END_VAR
payload.ResetCounter();
// T1: elapsed
payload.T1_Enabled := TRUE;
payload.T1_Output := TRUE;
payload.T1_ElapsedTime := T#10s;
// T2: waiting (different state!)
payload.T2_Enabled := TRUE;
payload.T2_Output := FALSE;
payload.T2_ElapsedTime := T#5s;
// T3: elapsed
payload.T3_Enabled := TRUE;
payload.T3_Output := TRUE;
payload.T3_ElapsedTime := T#30s;
AxUnit.Mocking.Mock(
mockeeFn := NAME_OF(OnDelay), mockFn := NAME_OF(ConfigurableOnDelayMock),
payload := payload
);
// Test your function block
myFB(enable1 := TRUE, enable2 := TRUE, enable3 := TRUE);
Equal(expected := TRUE, actual := myFB.OutputT1);
Equal(expected := FALSE, actual := myFB.OutputT2); // Different state!
Equal(expected := TRUE, actual := myFB.OutputT3);
END_METHOD

Example 3: Conditional Timers

{Test}
METHOD PUBLIC TestConditionalTimers
VAR
payload : IdentifierBasedOnDelayMockPayload;
END_VAR
payload.ResetCounter();
// Position 1: Always called
payload.T1_Enabled := TRUE;
payload.T1_CallPosition := 1;
payload.T1_Output := TRUE;
// Position 2: Called in mode 1 OR mode 2 (different timers, same position)
payload.T2_Enabled := TRUE;
payload.T2_CallPosition := 2;
payload.T2_Output := TRUE; // Mode 1 result
AxUnit.Mocking.Mock(
mockeeFn := NAME_OF(OnDelay), mockFn := NAME_OF(IdentifierBasedOnDelayMock),
payload := payload
);
// Test mode 1
myFB(mode := 1, enable := TRUE);
END_METHOD

Choosing the Right Mock

Scenario	Recommended Mock
Single timer	OnDelayMock_true / OnDelayMock_false ✅
Multiple timers, all same state	OnDelayMock_true / OnDelayMock_false ✅
Multiple timers, different states	ConfigurableOnDelayMock ✅
Conditional timer logic (IF/CASE)	IdentifierBasedOnDelayMock ✅
IEC 61131-3 standard timers	TON_Mock_true / TOF_Mock_false ✅

Testing Best Practices

Use Stateless Pattern

Always use the stateless pattern to ensure test isolation:

{TestFixture}
CLASS MyTests
VAR
myFB, myFBStateless : MyFunctionBlock;
payload, payloadStateless : ConfigurableOnDelayMockPayload;
END_VAR
{TestSetup}
METHOD PUBLIC TestSetup
payload := payloadStateless;
myFB := myFBStateless;
END_METHOD
END_CLASS

Reset Counter Before Each Test

For call-order based mocks, always reset the counter:

{Test}
METHOD PUBLIC MyTest
payload.ResetCounter(); // ← Essential!
// ... configure and test ...
END_METHOD

Documentation

• ConfigurableOnDelayMock - Call-order based mock for multiple timers
• IdentifierBasedOnDelayMock - Position-based mock for conditional logic
• TimerMocks-Overview - Complete overview and decision guide

Tests

All mocks include comprehensive test coverage. See the test/ directory for examples:

Simple Mocks:

• SimpleMocks_RealWorld_Test.st - Real-world examples showing when to use simple mocks
• IEC_TON_Mocks_Test.st - IEC TON timer tests
• IEC_TOF_Mocks_Test.st - IEC TOF timer tests
• System_OnDelay_Mocks_Test.st - System OnDelay tests
• System_OffDelay_Mocks_Test.st - System OffDelay tests

Configurable Mocks:

• ConfigurableOnDelayMockTest.st - OnDelay configurable mock
• ConfigurableOffDelayMockTest.st - OffDelay configurable mock
• ConfigurableTONMockTest.st - TON configurable mock
• ConfigurableTOFMockTest.st - TOF configurable mock

Identifier-Based Mocks:

• IdentifierBasedOnDelayMockTest.st - OnDelay identifier-based mock
• IdentifierBasedOffDelayMockTest.st - OffDelay identifier-based mock
• IdentifierBasedTONMockTest.st - TON identifier-based mock
• IdentifierBasedTOFMockTest.st - TOF identifier-based mock

Real-World Examples:

• FooFB_ConfigurableMock_Test.st - Real-world configurable example
• FooFB_IdentifierMock_Test.st - Real-world identifier-based example

Contribution

Thanks for your interest in contributing. Anybody is free to report bugs, unclear documentation, and other problems regarding this repository in the Issues section or, even better, propose changes using Merge Requests.

License and Legal information

Please read the Legal information