Skip to main content

Element: IEC Unit Test

Symbol: _tm_icon_iec_unit_test.png

Function: The IEC Unit Test element is used for automatically searching the (preparatory) loaded test project for test POUs and test tables during test execution, and then creating a test application from them. Then this test application is loaded, started, and the tests are performed. Finally, the results are saved in a test report.

The requirement is that the test project contains test POUs or test tables.

Title

Title of the IEC unit test as it appears in the test report

The title may contain spaces.

Example: IEC Unit Test of Feature A

Device read timeout (ms)

Maximum waiting time (in ms) during communication with the controller

If the time is exceeded, then error handling is started and an error is issued. For example, the timeout is monitored when variables are monitored.

Example: 5000

Note: During the test run, the timeout is monitored continuously: usually when logging in, when the application status is read out. Then for each single test case execution (at least once), when status and results are read.

Login retries

Number of login attempts

If the number is exceeded, then error handling is started and an error is issued.

Table 14. Libraries to test

Multiline input field for the libraries containing test POUs

These library POUs are instantiated, executed, and evaluated automatically in the test application during the test run.

Every library must be integrated in the test project by at least one Library Manager. The referencing type must match the information in the Library Manager.

Multiple libraries are separated by a semicolon (;) or a line break. Both separators can be combined. However, the following should be taken into consideration to avoid inconsistencies:

  • Do not use line breaks as separators within a test script variable; use semicolons instead.

  • In certain cases, the separators can be used however you want as long as two conditions are fulfilled: each test script variable contains only one library or parts of a library – for example, the version – and the separators are only inserted via the configurator of the IEC Unit Test element. In these cases, the CODESYS Test Manager handles the consistency of line breaks.

Placeholder library

Syntax: #<library name>

Requirement: The library is also referenced by means of placeholders in the Library Manager.

Example: #Test Collection Feature ABC

A test script variable (in braces) is also possible for <library name>.

Example: {TestLibABC}

Library

Syntax: <library name>, <library version>, (<company name>)

A test script variable is also possible in each case for <library name>, <library version>, and <company name>.

Values for <library version>:

  • Absolute version information

    Requirement: The library is also referenced absolutely in the Library Manager.

  • *

    Asterisk referencing to always reference the latest version

    Requirement: The library is also referenced in the Library Manager by means of an asterisk.

Examples

Test Collection Feature ABC, 4.0.0.0 (Company ABC)

Test Collection Feature ABC, * (Company ABC)

{TestLibABC}, {TestLibABCVersion} ({TestLibABCCompany})

Test Collection Feature ABC, {TestLibABCVersion} (Company ABC)

Test script variable

Syntax: {<variable name>}

The value of the test script variable contains one or more library names. Multiple library names are separated by a semicolon or a line break. At the same time, each variable value must correspond to the name of a placeholder library or a library. In the case of test script variables, semicolons (;) should be used because they are clearer than line breaks. Reason: For example, when a user writes the string of a test script variable into an external text editor and then copies the string into the CODESYS Test Manager, the type of line break (LF or CRLF) depends on the settings of the text editor.

Important

The feature to specify one or more library identifiers in a single test script variable and to enter only this variable in the IEC unit test configurator will only be supported as of CODESYS Test Manager version 5.2.0.0 and it is not backwards compatible. For CODESYS Test Manager version 5.1.0.0 and earlier, this means that the possibility to specify libraries will not be supported and test cases from corresponding libraries will not be performed.

Example: In a test script, 2 libraries are assigned to the test script variable TestLibs:

TestLibs := "#Test Collection Feature ABC; Test Collection Feature XYZ, * (Company ABC)"

The test script variable {TestLibs} will be entered in the Libraries to test text field.



Table 15. Selected categories and Excluded categories

Both input fields are used to restrict the selection of POUs to be included in the test run. You can specify Selected categories explicitly and/or Excluded categories of POUs explicitly.

If no explicitly selected category is specified, then the test POUs of all categories are selected implicitly. The list of excluded categories is then applied to this selection.

Excluded function blocks are not instantiated, executed, or evaluated during the test run.

This allows you to customize the test case at script level, for example to use it for controllers with different hardware.

Requirement: The test POUs or test tables contained in the test project have declared test categories. A test POU is categorized by the pragma {attribute 'testcategory' := '<name1, name2>'}. Example: {attribute 'testcategory' := 'BasicTests'}

Double-click on the left in the top free row to open an input field.

You can specify the name of one or (comma-separated) multiple POU categories per line. Example: BasicTests, ExtTests

A dynamic configuration of the POU categories to be included or excluded is possible by means of placeholders. The placeholder consists of the name of a test variable enclosed in braces. This test variable is assigned one or more category names and/or POU names by means of an assignment in the test script.

Example: In the test script, you assign a POU category BasicTests to the test variable TMCatVar: TMCatVar := "BasicTests". In the Selected categories field of the IEC Unit Test test element, you specify the placeholder: {TMCatVar}. As a result, only the POUs of the BasicTests category are included explicitly in the test run.

Example of a combined input in the Selected categories field: {TMCatVar}, {TMExtTests}, CTD



Table 16. Selected functions and Excluded functions

Both input fields are used to restrict the selection of POUs to be included in the test run. Specify either Selected functions explicitly or Excluded functions explicitly. These lists are evaluated in addition to the Selected categories and Excluded categories lists described above.

You can specify the POU name or the test case name, which has been defined with the compiler directive {attribute 'testcasename' := '<name>'} as the input. Uppercase and lowercase are not taken into consideration. In addition, the following wildcards are possible: '*' for any number of characters; '?' for a single character.

Example: All of the following input will result in the execution of the POU with the name TestCase_01.

Selected functions:

TestCase_01
tc1
tc?
TestCase_0*
*_01

Declaration:

{attribute 'test'}
{attribute 'testcasename':='tc1'}
{attribute 'testcasetimeout' := '60000'}
FUNCTION_BLOCK TestCase_01 EXTENDS TM.Testcase
VAR_INPUT
END_VAR
VAR_OUTPUT
END_VAR
VAR
END_VAR

super^();

Excluded function blocks are not instantiated, executed, or evaluated during the test run.

In this way, you can control the execution of the test case at the script level. For example, you can control the execution of a test case for controllers with different hardware.

For input and input syntax, see the section above: Selected categories and Excluded categories.

Important

In the case of multitests, values of the wsTestCaseName variable can be specified in the Excluded functions input field. As a result, the test cases of all POUs with these variable values are excluded from the test.

Example: The test cases with the variable value "TestStep #0: Initial value" are not executed

Excluded functions:

TestStep #0: Intial value

Implementation:

CASE diTestCaseIndex OF
   0: // Test Case #0 - tests the same as CTD_InitialValue        
      IF THIS^.xGetTestInfo THEN
          // Test case header
          THIS^.wsTestCaseName := "TestStep #0: Intial value";
          THIS^.wsTestCaseCategories := "Multitest";
          THIS^.diTestCaseTimeout := 200;
          xDone := TRUE;
      ELSE
          ...


Single application mode

standard icon: In the test project, the device Backup is generated instead of an application Backup.

On some devices, especially embedded devices, only one application is permitted. They are not able to process multiple applications. Similarly, only one application per device is permitted in the device tree of the test project. To generate a compilable test project, a backup device is created for these devices instead of a backup application (backup copy of the original application named Backup). Then there is a copy of the device named Backup in the device tree. The changes required for test generation changes are made in the project only after that.

Note: Select this option also for devices whose application name cannot be changed. Then the device in the project is renamed, not the applications.