UPact Headless

Create UPact (headless) Project

To run tests in this style, an additional project is needed where the test classes can be generated. For this use the wizard:

1. Right click on the package/folder where the project shall be created, then choose New > Other...
2. Select the UPact (headless) wizard and follow the instructions.

Note

• The content of the project, created by the wizard, must not be altered manually.
• If the project is deleted the reports folder is lost!
• If the project appears to be broken, it can be scrapped and created again with the UPact (headless) wizard (without reports!).
• see also UP Knowledge Base: search term: UPact Run Styles

Run within UPstudio

1. Make sure the target system is running and reachable within your network.
2. Right click on ant.up.build.upact.xml, then choose Run As (/Debug As) > Ant Build...
3. Choose targets with the tick boxes.
   • The default target "build" will generate, compile and run all test suite instances on all configured test target configurations.
4. Add the necessary properties (see Notes below) under the Properties tab.
   • Unckeck the box: Use global properties as specified in the Ant runtime preferences
5. Hit Run

Note (B&R and Siemens only)

If the target system is B&R or Siemens, OPC-UA username and password must be passed as the properties test_target_configuration.opc.username and test_target_configuration.opc.password at the target call. ex.

A Siemens simulation target does not support OPC-UA password authentification. 'Anonymous' must be set as user, any string as password.

To protect the code from invalid characters, the properties must be passed as Base64 encoded strings.

Just google Base64 encode to find free en-/decoding tools.

Check encoding with "ServiceUiUser" ==> "U2VydmljZVVpVXNlcg==".

Example for username property: BR_Config_Simulation.opc.username = "U2VydmljZVVpVXNlcg=="

Note

The wizard creates default values in ant.up.build.upact.xml for the following properties, but they may vary in your pipeline.

• up.version - version number of UPstudio
• up.bundle.directory - path to plugins folder of UPstudio
• up.workspace - path to root folder of your projects
• project.name - name of UPact Headless project
• project.location - path to UPact Headless project
• project.dependency.location - path to the UP project wherein the test suites are configured

Report

The execution creates the folder reports with report files.

Note

Running the same configuration overwrites the previous report!

Jenkins Pipeline Example (B&R)

To run the tests within a CI/CD pipeline, the file ant.up.build.upact.xml of the UPact (headless) Project provides Ant targets. The results are returned in JUnit style. A Jenkins pipeline can make use of that. Below a sample pipeline of a simple sample project:

Setup

1. Import swiss.avm.up.samples.handling into the workspace. It is an UP sample project where controller and tests are already defined.

   • Read the README.md of the repository for correct cloning.

2. Create the UPact (headless) Project with the wizzard. swiss.avm.up.samples.handling.test.headless is an example of such a project. It can be imported and used directly, as well.

   • Make sure the project dependency is set to the UP sample project swiss.avm.up.samples.handling.

3. Import swiss.avm.up.samples.handling.test.jenkins into the workspace. It contains a Jenkinsfile which defines the steps for a Jenkins pipeline which executes the UPact tests on a B&R ARSim.

4. Create an entry at Jenkins credentials manager with OPC-UA username and password of the ARSim under the credentialsId "upact-opcua-samples".

5. Add a pipeline to your Jenkins with Jenkinsfile: swiss.avm.up.samples.handling.test.jenkins/Jenkinsfile.

Pipeline Stages of the Jenkinsfile

1. fetch UPstudio

   • The current version of UPstudio is loaded from the nexus server.
   • If the avm nexus is not available, remove the first stage and provide an UP at swiss.avm.up.samples.handling.test.

2. init submodules

   • target folder platform/br is included as git submodule platform and thus is updated here.

3. generate PLC application

   • Corresponds to Force Generate Code of platform/br.
   • PLC code is generated out of the UP project into the B&R project in platform/br.
   • The stage calls the default Ant target of swiss.avm.up.samples.handle/asbuild.xml.
   • asbuild.xml can be / was generated in UP with Export...: Ant BuildFile Export and added to the project.

4. run PLC application

   • The stage calls the "run" Ant target of swiss.avm.up.samples.handling/platform/br/build.xml.
   • This compiles and starts an ARSim headlessly.

5. test application with UPact

   • withCredentials() gets user and password from Jenkins Credentials Manager for UPact to connect by OPC-UA with the ARSim.
   • The stage calls the "build" Ant target of swiss.avm.up.samples.handling.test.headless/ant.up.build.upact.xml.
     • ant -f ant.up.build.upact.xml build -DBR_Config_Simulation.opc.username=${UPACT_OPC_CREDS_USR.bytes.encodeBase64().toString()} -DBR_Config_Simulation.opc.password=${UPACT_OPC_CREDS_PSW.bytes.encodeBase64().toString()}
     • groovy is used to encode username and password property strings
   • The output of the reports is defined at reports/**/*.xml, so Jenkins evaluates those reports.
   • To customize the pipeline more, this stage can split into multiple steps by using subtargets instead of "build".
     • see Calling targets individually

6. (Post) kill ARsim

   • "kill-arsim" Ant target of swiss.avm.up.samples.handling/platform/br/build.xml is called to tear down the PLC simulation.

Have closer look at the Jenkinsfile and build-xmls for more insight.

Calling targets individually

The default target "build" will generate, compile and run all test suite instances on all configured test target configurations.

Instead of default target "build", the Ant targets provided by ant.up.build.upact.xml may be called individually. To choose from test suite instances and test target configurations instead of running all of them, the ANT targets must be called individually.

For that call the targets "UPbuild_internal_UPact_Headless", "copy-jars", "compile", "run-tests-testtarget-config" in this order.

• "UPbuild_internal_UPact_Headless" - generate java test classes from modeled tests.
• "copy-jars" - update libraries
• "compile" - java test classes are compiled
• "run-tests-testtarget-config" - test runner is started and test classes are executed

The choice of test suite instances and test target configurations is defined as set properties:

• property name = "activeSuiteInst.test_target_configuration.test_suite_instance"
• Ex.: <property name="activeSuiteInst.BR_Config_Simulation.testSuite1" value="true" />

Also the test target config must be defined in property testtarget.config:

• Ex.: <property name="testtarget.config" value="BR_Config_Simulation" />

Note

The order of the activeSuiteInst... properties has no influence on the execution order. The execution order is defined by the order of the test target configurations (first priority) and the order of the test suite instances (second priority) in the UPact configuration.

Note

The wizard creates default values in ant.up.build.upact.xml for the following properties, but they may vary in your pipeline.

• up.version - version number of UPstudio
• up.bundle.directory - path to plugins folder of UPstudio
• up.workspace - path to root folder of your projects
• project.name - name of UPact Headless project
• project.location - path to UPact Headless project
• project.dependency.location - path to the UP project wherein the test suites are configured

Make sure to provide all properties at each target call.

Note (B&R only)

If the target system is B&R, OPC-UA username and password must be passed as the properties test_target_configuration.opc.username and test_target_configuration.opc.password at the target call.

To protect the code from invalid characters, the properties must be passed as Base64 encoded strings.

Example:

ant -f ant.up.build.upact.xml build -DBR_Config_Simulation.opc.username=${UPACT_OPC_CREDS_USR.bytes.encodeBase64().toString()} -DBR_Config_Simulation.opc.password=${UPACT_OPC_CREDS_PSW.bytes.encodeBase64().toString()}

Just google Base64 encode to find free en-/decoding tools.

Check encoding with "ServiceUiUser" ==> "U2VydmljZVVpVXNlcg==".