Tutorial

hermsen
Project Members:

Quick Start

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;

1 Extend CoUnit.FB_TestSuite,
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.

Checking test results

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.

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

  1. Download and install the co♻e framework package,
  2. Reference the library in your project or library,

  3. Create test suites and run the tests.

  4. Download and install the co♻e framework package

    • Open the folder where you saved the co♻e.Package to,
    • Now doubleclick it..
    • Follow the instructions..

  5. Reference the library in your project or library,

    • In order to use co♻e 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 co♻e-group, select co♻e and click OK.

  6. 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 co♻e-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 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 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_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 CoUnit.FB_TestSuite.

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 TwoPlusTwoEqualsFour and ZeroPlusZeroEqualsZero.

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();

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

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

TwoPlusTwoEqualsFour();
ZeroPlusZeroEqualsZero();

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

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!

Regards

Project Members:

Related

Home: Home