Generating SCTUnit source code

Generating SCTUnit source code Copy link to clipboard

Executing SCTUnit tests within the Eclipse development environment as described in section "Running the test" is a nice and handy feature for the developers. However, it all happens on the modeling level, a higher abstraction level than the actual source code you are likely generating from your statechart. You will probably want to test the generated source code as well, especially in any safety critical environments.

Generating unit tests as source code comes as a solution. Source code can be inspected, compiled, and integrated wherever needed.

This section explains how you can generate your SCTUnit tests as source code with itemis CREATE. Supported programming languages are C, C++, Java, Python as well as SCXML for Qt. The SCTUnit code generators translate the SCTUnit tests into a unit test framework of the target language. For example, the generated Java test code uses JUnit as its testing framework and Mockito for mocked methods. C and C++ sources rest upon the Google Test unit testing library.

In order to use the SCTUnit code generators effectively, you should already be familiar with generating source code from statecharts, as explained in chapter "Generating state machine code". In fact, you have to generate your statechart as source code first, so that the SCTUnit tests have something to be executed upon. Below we are assuming that you have your statechart code generator model and the generated code handy. Generating SCTUnit test source code follows the same principles as generating state machine source code, so we can focus on SCTUnit specifics here.

Creating a generator model Copy link to clipboard

The first step is to create a generator model (SGen) for the SCTUnit test, similar to explanation in section "Generating state machine code".

In the main menu, select File → New → Other…. The New dialog opens.
In the New dialog, select itemis CREATE → Code generator model.
Click on Next. The itemis CREATE generator model wizard opens.
Select a project and a folder as the generator model’s location. The filename must end with .sgen.
Click on Next.
In the Generator drop-down menu, select one of the source code generators whose names begin with “SCTUnit”, e.g., “SCTUnit C Code Generator”.
In the list below, check the SCTUnit files you want to generate as source code.
Click on Finish.

As a result, the generator model file is created. Figure "A sample SCTUnit generator model" shows a generator model for the SCTUnit C generator. The target language is reflected in the generator ID “sctunit::c”. Each SCTUnit test unit is contained in a section marked with the test keyword, followed by the respective fully-qualified test unit name.

A sample SCTUnit SGen model

SCTUnit C Code Generator Copy link to clipboard

The SCTUnit C code generator transforms SCTUnit tests into C++ code that makes use of the Google Test unit testing library.

The test code generator can be controlled by the following features:

Outlet Copy link to clipboard

The Outlet feature is required and determines where the generated artifacts will be placed. Meaning is same as for the common outlet feature.

SGenModel Copy link to clipboard

The SGenModel feature allows to generate a basic generator model file for the statechart under test. The generated .sgen file will take over the FunctionInlining and IdentifierSettings features.

FunctionInlining Copy link to clipboard

In this context, the FunctionInlining feature is only relevant in combination with the SGenModel feature.

IdentifierSettings Copy link to clipboard

In order to include the proper statechart header and use the proper statechart APIs, the test code generator needs to know which identifier settings are used in the statechart’s generator model. This means, whenever the statechart generator model uses specific IdentifierSettings, the same values need to be set in the test generator model.

In addition, it is possible to specify the file extension of the generated test files with the option testFilenameExtension. The default is ‘cc’.

LicenseHeader Copy link to clipboard

The LicenseHeader features adds a license header to the generated test files. See also the common LicenseHeader feature.

OutEventAPI Copy link to clipboard

The OutEventAPI feature is not yet used. It is expected that the statechart uses getters for its out event API. The usage of observers is not yet supported. See also the common OutEventAPI feature.

JUnitWrapper Copy link to clipboard

The JUnitWrapper creates an additional JUnit test that simply runs the generated GTest. This is intended for Java based CI environments.

SCTUnit C++ Code Generator Copy link to clipboard

The SCTUnit C++ code generator transforms SCTUnit tests into C++ code that makes use of the Google Test unit testing library.

The test code generator can be controlled by the following features:

Outlet Copy link to clipboard

The Outlet feature is required and determines where the generated artifacts will be placed. Meaning is same as for the common outlet feature.

SGenModel Copy link to clipboard

FunctionInlining Copy link to clipboard

In this context, the FunctionInlining feature is only relevant in combination with the SGenModel feature.

IdentifierSettings Copy link to clipboard

In addition, it is possible to specify the file extension of the generated test files with the option testFilenameExtension. The default is “cc”.

LicenseHeader Copy link to clipboard

The LicenseHeader features adds a license header to the generated test files. See also the common LicenseHeader feature.

OutEventAPI Copy link to clipboard

JUnitWrapper Copy link to clipboard

The JUnitWrapper creates an additional JUnit test that simply runs the generated GTest. This is intended for Java based CI environments.

GeneratorOptions feature Copy link to clipboard

The GeneratorOptions feature allows to change the behavior of the C++ generator. With the statemachineRefsAsPlainPointer option the generated code in multi-statemachine scenarios will use plain pointers instead of smart pointers for referencing statemachines, just like in the C++ statemachine code generator.

SCTUnit Java Code Generator Copy link to clipboard

The SCTUnit Java code generator transforms SCTUnit tests into JUnit tests. The generated JUnit tests make use of the Mockito framework when operation mocking is required.

The test code generator can be controlled by the following features:

Outlet Copy link to clipboard

The Outlet feature is required and determines where the generated artifacts will be placed. Meaning is same as for the common outlet feature.

Naming Copy link to clipboard

The Naming feature allows to specify a different package for the generated test class than the statechart class belongs to. If this feature is used, it is required to specify the package of the statechart class in the StatechartNaming feature as described in the next chapter.

Example:

feature Naming {
    basePackage = "light.tests"
}

This setting will generate the test class into the light.tests package.

StatechartNaming Copy link to clipboard

For Java, the generated state machine code on one hand and the SCUnit test classes on the other hand may well belong to different packages. However, in order to be able to execute the state machine, the SCTUnit tests need to know what the state machine’s package is.

This is what the StatechartNaming feature is good for. It contains all the properties you can set in the state machine’s Java code generator Naming feature.

Example:

feature StatechartNaming {
    basePackage = "bar.light_switch"
    typeName = "CustomLightSwitch"
    libraryPackage = "bar.light_switch.lib"
    libraryTargetFolder = "src-lib"
}

With these settings, The SCTUnit code generator expects the state machine class to be part the bar.light_switch package. The state machine class name is expected to be CustomLightSwitch. Library artifacts like the timer service interface are expected to be in the src-lib folder under the bar.light_switch.lib package.

LicenseHeader Copy link to clipboard

The LicenseHeader features adds a license header to the generated test files. See also the common LicenseHeader feature.

OutEventAPI Copy link to clipboard

SCTUnit Python Code Generator Copy link to clipboard

The SCTUnit Python code generator transforms SCTUnit tests into Python unittests.

The test code generator can be controlled by the following features:

Outlet Copy link to clipboard

The Outlet feature is required and determines where the generated artifacts will be placed. Meaning is same as for the common outlet feature.

Naming Copy link to clipboard

Example:

feature Naming {
    basePackage = "light.tests"
}

This setting will generate the test class into the light.tests package.

StatechartNaming Copy link to clipboard

For Python, the generated state machine code on one hand and the SCUnit test classes on the other hand may well belong to different packages. However, in order to be able to execute the state machine, the SCTUnit tests need to know what the state machine’s package is.

This is what the StatechartNaming feature is good for. It contains all the properties you can set in the state machine’s Python code generator Naming feature.

Example:

feature StatechartNaming {
    basePackage = "bar.light_switch"
    libraryPackage = "bar.light_switch.lib"
    libraryTargetFolder = "src-lib"
}

With these settings, The SCTUnit code generator expects the state machine class to be part the bar.light_switch package. Library artifacts like the timer are expected to be in the src-lib folder under the bar.light_switch.lib package.

LicenseHeader Copy link to clipboard

The LicenseHeader features adds a license header to the generated test files. See also the common LicenseHeader feature.

OutEventAPI Copy link to clipboard

JUnitWrapper Copy link to clipboard

The JUnitWrapper creates an additional JUnit test that simply runs the generated GTest. This is intended for Java based CI environments.

Table of contents