Ranorex

Note

This plugin is available only in the Ultimate version of Squash.

This plugin provides functions that handle Ranorex tests. It has been validated with Ranorex 9.5 and should work with any recent version of Ranorex.

It can be used directly in a workflow, or indirectly via generators (such as those providing access to test case managers).

A working Ranorex installation must be available in the targeted execution environments.

The functions have a ranorex category prefix.

Functions

ranorex/ranorex@v1

Run a Ranorex test suite.

If the function is used more than once in a job, it is up to the caller to ensure no previous test execution results remain before executing a new test.

Before launching tests in the execution environment, the function will check three conditions and return a specific error code if one is not properly fulfilled:

definition of SQUASH_MSBUILD_PATH environment variable (Return Code 91).
existence of MSBuild.exe file in the SQUASH_MSBUILD_PATH folder (Return Code 92).
existence of executable test file generated with MSBuild.exe (Return Code 93).

Inputs

The function has the following inputs:

solution (required)

The path to the solution to execute.
solution_file (required)

The name of the solution's .sln file.
project (required)

The name of the project to execute.
test_suite (optional)

The name of the test suite to execute, without its .rxtst extension (/ts:YourTestSuite.rxtst option).
test_container (optional)

The name of the test container to execute (/tc:YourTestContainer option).

Can only be used if test_suite is provided.
global_params (optional)

Parameters to be passed as global parameters to the executed project (/pa:YourGlobalKey=YourGlobalValue option for each provided parameter).
test_container_params (optional)

Parameters to be passed to the executed test container, if a test container has been specified. Will be ignored if no test_container param is provided (/tcpa:YourTestContainer:YourContainerKey=YourContainerValue option for each parameter you filled).
extra_options (optional)

Extra parameters to be passed to the executed project (free form). Injected as is in the command line.

For a list of available parameters, see the Ranorex documentation.

Reports

The function generates the following reports:

ranorex-report.rxlog.data

A Surefire report (XML).

The Surefire report has the application/vnd.opentestfactory.ranorex-data+xml content type.
ranorex-report.rxzlog

A TAR archive.
Contains the *.rxlog.data XML report file and all external files referenced by the report file.

Example

- uses: ranorex/ranorex@v1
  with:
    solution: my\ranorex\solution
    solution_file: solution.sln
    project: name
    test_suite: name
    test_container: name
    global_params:
      name1: value1
      name2: value2
    test_container_params:
      name1: value1
      name2: value2
    extra_options: value

ranorex/execute@v1

An 'execute' function for use by generators.

The function will check three conditions and return a specific error code if one is not properly fulfilled:

definition of SQUASH_MSBUILD_PATH environment variable (Return Code 91).
existence of MSBuild.exe file in the SQUASH_MSBUILD_PATH folder (Return Code 92).
existence of executable test file generated with MSBuild.exe (Return Code 93).

Test Reference format

The test reference format used by ranorex/execute@v1 is as follows:

{project}/{slnfile}#{ranorex_project}#{testsuite}[#{testcontainer}]

With:

{project} (required): name of the project on the source code repository.
{slnfile} (required): path to the name of the solution file (with its .sln extension), from the root of the project source repository.
{ranorex_project} (required): the Ranorex project name to execute.
{testsuite} (required): Ranorex test suite name to execute.
{testcontainer} (optional): Ranorex test case name to execute.

Inputs

The function has the following inputs:

test (required)

The test reference.

Reports

The function generates the following reports:

ranorex-report.rxlog.data

A Surefire report (XML).

The Surefire report has the application/vnd.opentestfactory.ranorex-data+xml content type.
ranorex-report.rxzlog

A TAR archive.
Contains the *.rxlog.data XML report file and all external files referenced by the report file.

Example

- uses: ranorex/execute@v1
      with:
        test: my/ranorex/solution/solution.sln#project#testSuite#testContainer

ranorex/params@v1

A 'params' function for use by generators.

Inputs

The function has the following inputs:

data (required)

The data to use for the automated test.
format (required)

The format to use for the automated test data.

Example

- uses: ranorex/params@v1
  with:
    data:
      global:
        key1: value1
        key2: value2
      test:
        key1: value3
        key3: value4
    format: format

format must so far be SQUASHTM_FORMAT (tm.squashtest.org/params@v1).

data can have two keys:

global for defining global parameters.
test for defining test parameters.

Using with inception

Please refer to "Inception" for more information on what is inception.

Preload the inception environment with at least the tests execution report data.

Example

my_workflow.yaml

metadata:
  name: Ranorex Inception
resources:
  files:
  - report1
jobs:
  my_specific_job:
    runs-on: inception
    steps:
    - uses: actions/prepare-inception@v1
      with:
        ranorex-report.rxlog.data: ${{ resources.files.report1 }}
    - uses: ranorex/execute@v1
      with:
        test: my/ranorex/solution/solution.sln#project#testSuite#testContainer

You can use the following command to run it:

BashCMDPowerShell

opentf-ctl \
    run workflow my_workflow.yaml \
    -f report1=output_1.xml

opentf-ctl ^
    run workflow my_workflow.yaml ^
    -f report1=output_1.xml

opentf-ctl `
    run workflow my_workflow.yaml `
    -f report1=output_1.xml

Configuration

Hooks can be defined for the provided functions. This can be done in workflow definitions or at the orchestrator level so that they apply to all your workflows.

Configuration at the orchestrator level is done by setting the RANOREX_PROVIDER_HOOKS environment variable or by adding the hook definitions in the /app/conf/ranorex.yaml service configuration file.

Please refer to "Hooks for plugin providers" in OpenTestFactory documentation for more information.