All you need to do is to download & install the library and provide a reference of the CfUnit-library in your project.
Now you are ready and you can start to write your test code! Just follow these few simple steps;
1 Extend CfUnit.FB_TestSuite,
2 Define the inputs, define the expected outputs (result),
4 Call the CfUnit-assert methods to compare the expected output to the actual output,
5 Close the test with TEST_FINISHED() when finished.
Checking test results
The Unit testing results are viewable via the Device Log;
Select CfUnit as Logger via the pulldown menu and press refresh, wait a few moments and the contents will be shown.
Introduction user guide
It’s highly recommended to also read unit testing concepts (google is your friend), in order to have a basic understanding of the concepts of unit testing and CfUnit. The framework gives you the possibility to easily write unit tests for your PLC software, and having the results reported in a human-readable format for review. All unit test code is written in the same program/library as the rest of your code, but because it is only used in a separate test-program, it does not affect the production code/executables. With unit test-code provided with the rest of the code, you can see these additions as living documentation of the code. For a more thorough/detailed example please see the simple programming example or the Unit Verifier.
This guide is a short tutorial in which we will go through the different steps that are necessary to use CfUnit;
Download and install the CfUnit framework package,
Reference the library in your project or library,
Create test suites and run the tests.
Download and install the CfUnit framework package
Open the folder where you saved the CfUnit.Package to,
Now doubleclick it..
Follow the instructions..
Reference the library in your project or library,
In order to use CfUnit you need to add a reference to the library in your project.
Open your CODESYS project, and right-click on the References under the PLC-project and click on Add library…
Add library reference
Next go to the CfUnit-group, select CfUnit and click OK.
Create test suites and run them
For every function block (or function) that you have defined, create a test function block counterpart (a test suite), which has the responsibility to:
Instantiate the FB under test,
Define the inputs,
Define the expected outputs (result),
Call the CfUnit-assert methods to compare the expected output to the actual output for every test,
It’s entirely up to you, the user, how to organize the different tests, so what follows is a suggestion;
On the same level as the POUs folder, create a folder called Test. It is in this folder that we will create all our test FBs as well as the program that will run the CfUnit framework.
In this example we have a total of five FBs. For every FB we have created a test-FB, i.e. for FB_DiagnosticMessageDiagnosticCodeParser we have FB_DiagnosticMessageDiagnosticCodeParser_Test. Note that the framework in no way enforces to use any standard for the naming, this is entirely up to the user. For various reasons you might find it not even be possible to add the test-FBs in the same project (for instance, if this is your main executable), and in this case just put the tests in a separate project and include the main project in the test project as a library. Generally it’s better to structure the code in various library projects each responsible for a certain set of requirements/functionality. It’s important to see the tests as an important part of your code.
The general structure here is that PRG_TEST is the program in where the test-FBs (test suites) are instantiated. Each test suite is responsible of testing one FB or function, and can have one or more tests to do so. Let’s assume we want to create the simplest possible FB that takes two unsigned integers and sums them. We can create the header for the FB, but the actual implementation can (and should) wait after we’ve done the unit tests.
FUNCTION_BLOCK FB_SumVAR_INPUT one : UINT; two : UINT;END_VARVAR_OUTPUT result : UINT;END_VAR
Now let’s create the test suite for this FB (we still do not implement the FB itself!)
This FB needs to extend CfUnit.FB_TestSuite.
By always adding this code, your test suite gets access to CfUnit and CfUnit will have a handle to your test suites.
Now it’s time to create our tests. There are many ways to structure your tests, and there are several guidelines for this as well. What we’ll be doing is to create a method for every test, and name it in such a way that it’s clear what the test does. Remember that the unit tests are part of the documentation of your code, and although you might find the code trivial at this moment, there might be other developers reading your code now (or many years in the future). For them well-named tests are invaluable.
We’ll be creating two tests called TwoPlusTwoEqualsFour and ZeroPlusZeroEqualsZero.
METHODTwoPlusTwoEqualsFourVARSum:FB_Sum;Result:UINT;ExpectedSum:UINT:=4;END_VARTEST('TwoPlusTwoEqualsFour');Sum(one:=2,two:=2,result=>Result);AssertEquals(Expected:=ExpectedSum,Actual:=Result,Message:='The calculation is not correct');TEST_FINISHED();
By calling TEST() we tell CfUnit that everything that follows is a test. Remember that we did EXTEND FB_TestSuite in our test-suite? This gives us access to assert-methods to check for all the data types available in IEC61131-3, including the ANY-type. The Message parameter is optional and is used in case the assertion fails, the text is appended to the error output. We finish the method by calling TEST_FINISHED(). This gives the flexibility to have tests that span over more than one PLC-cycle.
An example is provided in the package to demonstrate this.
For ZeroPlusZeroEqualsZero it’s more or less the same code.
METHODZeroPlusZeroEqualsZeroVARSum:FB_Sum;Result:UINT;ExpectedSum:UINT:=0;END_VARTEST('ZeroPlusZeroEqualsZero');Sum(one:=0,two:=0,result=>Result);AssertEquals(Expected:=ExpectedSum,Actual:=Result,Message:='The calculation is not correct');TEST_FINISHED();
Next we need to update the body of the test suite (FB_Sum_Test) to make sure these two tests are being run.
Last but not least, we need to have a program PRG_TEST defined in a task that we can run in our PLC.
Note that this program is only created to run the unit-tests, but should not run on the production target PLC(!)
Being part of the library project we only want a convenient way to test all the FBs part of our library, and thus need this program to execute the test suites.
PRG_TEST needs to instantiate all the test suites, and only execute one line of code. In this case we only have one test suite.
There is one test that has failed, and the reason for this is that we have not written the implementation of the FB yet, but only the header of the function block FB_Sum. But what is the reason that we have one test succeeding? As we can see, the test TwoPlusTwoEqualsFour failed, which means that the one that succeeded was the other test ZeroPlusZeroEqualsZero. The reason this succeeds is that the default return value for an output-parameter is zero, and thus it means that even if we haven’t written the body of FB_Sum the test will succeed.
Let’s finish by implementing the body of FB_Sum.
Obviously this is a very simple example and the purpose of this was to show how to use the framework itself rather to come up with a real-world example. Simple functionality that does not require any state would be better suited to be implemented as a function, or in this case just using the “+” operator.
Offcourse the verifier and other examples can provide you with hints on how to write your own tests. Also, we would like to encourage you on sharing your (open source) code, unit test and experience with us here on cForge! We hope you will enjoy writing good tests and bug free software!
Good luck and have fun writing and debugging your code!