All you need to do is to download & install the library and provide a reference of the co♻e-library in your project.
Now you are ready and you can start to write your test code! Just follow these few simple steps;
2 Define the inputs, define the expected outputs (result),
4 Call the CoUnit-assert methods to compare the expected output to the actual output,
5 Close the test with
TEST_FINISHED() when finished.
The Unit testing results are viewable via the Device Log;
Select co♻e as Logger via the pulldown menu and press refresh, wait a few moments and the contents will be shown.
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 co♻e.
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 co♻e;
Create test suites and run the tests.
Download and install the co♻e framework package
Reference the library in your project or library,
Create test suites and run them
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 co♻e 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
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_Sum VAR_INPUT one : UINT; two : UINT; END_VAR VAR_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
FUNCTION_BLOCK FB_Sum_Test EXTENDS CoUnit.FB_TestSuite VAR END_VAR
By always adding this code, your test suite gets access to co♻e and co♻e 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
METHOD TwoPlusTwoEqualsFour VAR Sum : FB_Sum; Result : UINT; ExpectedSum : UINT := 4; END_VAR TEST('TwoPlusTwoEqualsFour'); Sum(one := 2, two := 2, result => Result); AssertEquals(Expected := ExpectedSum, Actual := Result, Message := 'The calculation is not correct'); TEST_FINISHED();
TEST() we tell co♻e 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.
ZeroPlusZeroEqualsZero it’s more or less the same code.
METHOD ZeroPlusZeroEqualsZero VAR Sum : FB_Sum; Result : UINT; ExpectedSum : UINT := 0; END_VAR TEST('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.
PROGRAM PRG_TEST VAR fbSum_Test : FB_Sum_Test; // This is our test suite END_VAR CoUnit.RUN();
Activating this solution and running it results in the following result:
====================================== Failed Tests: 1 Successful tests: 1 Tests: 2 Test suites : 1 ==========TESTS FINISHED RUNNING==========
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
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
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
FUNCTION_BLOCK FB_Sum VAR_INPUT one : UINT; two : UINT; END_VAR VAR_OUTPUT result : UINT; END_VAR result := one + two;
Running the tests again we get the expected behavior:
====================================== Failed Tests: 0 Successful tests: 2 Tests: 2 Test suites : 1 ==========TESTS FINISHED RUNNING==========
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.
Of course 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 code, unit test and experience with us here on Forge!
Good luck and we hope you will enjoy writing good tests and bug free software!