Agilitest

Note

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

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

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

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

The functions have an agilitest category prefix.

Functions

agilitest/agilitest@v1

Run an Agilitest test suite.

The path to ATS script is relative to the step's working directory. If not specified, this is the job's working directory, in which case it must include the repository name.

In most cases, this path should be:

repositoryName/src/main/ats/otherDir/testCase.ats

Inputs

The function has the following inputs:

test (required)

The ATS script to use.
test_parameters (optional)

A set of parameters at the test suite level. If a parameter is not specified, its value is given the default value. If a parameter is specified, a custom value must be given.
atsSuiteDescription (optional)

A custom description of the test suite, visible in reports. Default value is Squash generated testsuite.
visualReport (optional)

The quality of the visual report. Possible values are 1, 2, 3, or 4 in order of quality and size. Default value is 2.
atsLogLevel (optional)

Level of reporting. Possible values from least to most verbose are silent, error, info, warning, and all. Default value is all.
reportsDirectory (optional)

Where to put reports, relative to the project. Defaults to target/ats-output.
environment_variables (optional)

A set of keys-values to feed variables in the script.

Reports

The function generates the following reports:

TEST-{ats_script}.xml

A Surefire report (XML).
{ats_script} is the name of an ATS script.

The Surefire report has the application/vnd.opentestfactory.agilitest-surefire+xml content type.
ats-reports.tar

A TAR archive.
Contains all files present in the target folder, excluding the junitreports and ats-output subfolders.

Examples

This first example runs the bar.ats ATS script located in a foo directory with default values for all test parameters and no environment variables:

- uses: agilitest/agilitest@v1
  with:
    test: agilitestProject/src/main/ats/foo/bar.ats

This second example runs the bar.ats ATS script located at the root of all scripts, with default value for atsLogLevel, the highest quality setting for the visual report, and a custom description for the test suite. It also defines the value of the variable my_env_var used in the script.

- uses: agilitest/agilitest@v1
  with:
    test: agilitestProject/src/main/ats/bar.ats
    test_parameters:
      atsSuiteDescription: MyTestSuite
      visualReport: 4
    environment_variables:
      my_env_var: 42

agilitest/execute@v1

An execute function for use by generators. Runs a test script.

Test Reference format

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

{project}/{script}

With:

{project} (required): name of the project on the source code repository.
{script} (required): path and name of the ActionTestScript test, from the root of the project (with the .ats extension).

Note

Please note that the ATS script must be located in src/main/ats/*, as in any regular ATS architecture.

Inputs

The function has the following inputs:

test (required)

The test reference.

Reports

The function generates the following reports:

TEST-{ats_script}.xml

A Surefire report (XML).
{ats_script} is the name of an ATS script.

The Surefire report has the application/vnd.opentestfactory.agilitest-surefire+xml content type.
ats-reports.tar

A TAR archive.
Contains all files present in the target folder, excluding the junitreports and ats-output subfolders.

Example

The path to ATS script is relative to the step's working directory.

In most cases this path should be:

repositoryName/src/main/ats/{...}/testCase.ats

- uses: agilitest/execute@v1
  with:
    test: agilitestProject/src/main/ats/testCase.ats

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

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

- uses: agilitest/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: Agilitest Inception
resources:
  files:
  - report1
jobs:
  my_specific_job:
    runs-on: inception
    steps:
    - uses: actions/prepare-inception@v1
      with:
        TEST-testCase.xml: ${{ resources.files.report1 }}
    - uses: agilitest/execute@v1
      with:
        test: agilitestProject/src/main/ats/testCase.ats

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 AGILITEST_PROVIDER_HOOKS environment variable or by adding the hook definitions in the /app/conf/agilitest.yaml service configuration file.

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