Skip to content

Katalon

Note

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

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

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

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

The functions have a katalon category prefix.

Functions

katalon/katalon@v1

Run a Katalon test suite collection or test suite.

It has the following mandatory inputs:

  • For executing a test suite collection: project and test-suite-collection-path.
  • For executing a test suite: project, test-suite-path, and browser-type.

Environment variables

The following environment variables must be defined in the execution environment:

  • KATALON_API_KEY = Katalon API license key, for example: 123a4567-123a-1ab2-1234-1234567890ab.
  • KATALON_ORG_ID = Organisation ID at Katalon, for example: 123456.

Additionally, when executing a test suite without specifying the browser-type input, the following environment variable must also be defined:

  • KATALON_BROWSER_TYPE = Default browser type, for example: Web Service.

Inputs

The function has the following inputs:

  • project (required)

    Specify the project location (include .prj file). The path from the root folder of the workspace must be used in this case. (-projectPath={path})

  • test-suite-collection-path (optional)

    Specify the test suite collection file (without extension .tsc). The relative path must be used in this case (root being project folder). (-testSuiteCollectionPath={path})

  • test-suite-path (optional)

    Specify the test suite file (without extension .ts). The relative path must be used in this case (root being project folder). (-testSuitePath={path})

  • browser-type (optional)

    Specify the browser type used for test suite execution. (-browserType={browser}) (Web Service is used for Web Service test execution.)

    • Possible values for {browser} for Linux:
      • Web Service
      • Firefox
      • Chrome
      • Remote
    • Possible values for {browser} for other OSes:
      • Web Service
      • Firefox
      • Chrome
      • IE
      • Edge
      • Edge (Chromium)
      • Safari
      • Remote
      • Android
      • iOS

    You can use this option in a test suite collection execution. The specified browser is used for all test suites in that collection.

  • execution-profile (optional)

    Specify the execution profile that a test suite executes with. (-executionProfile={profile_name})
    You can use this option in a test suite collection execution. The specified execution profile is applied to all test suites in that collection.

  • retry (optional)

    Specify the number of times running test cases in the test suite, until the test suite passes successfully. (-retry={number of retry times})

    Set {number of retry times} to 0 for no retry.

    By default, the retry input is set to 0.

  • status-delay (optional)

    System updates execution status of the test suite after the delay period (in seconds) specified. (-statusDelay={seconds})

  • send-mail (optional)

    Specify the e-mail address for receiving report files. If the e-mail address was not specified, the report files are not to be sent. (-sendMail={e-mail address})

  • report-folder (optional)

    Specify the destination folder for saving report files. You can use an absolute path or relative path (root being project folder). (-reportFolder={path})
    By default, the report-folder input is set to Katalon_reports.

  • report-file-name (optional)

    Specify the name for report files (.html, .csv, .log). (-reportFileName={name})
    If not provided, the system uses the name report (report.html, report.csv, report.log).

  • extra-options (optional)

    All other additional options.

Reports

The function generates the following reports:

  • JUnit_Report.xml

    A Surefire report (XML).
    Generated when test-suite-collection-path or test-suite-path is specified.

    The Surefire report has the application/vnd.opentestfactory.katalon-surefire+xml content type.

  • {report-folder}.tar

    A TAR archive.
    Contains all files present in the reports folder.

    Katalon_reports.tar by default or {report-folder}.tar if report-folder is specified.

    Generated when test-suite-collection-path or test-suite-path is specified.

  • {report-file-name}.html

    Report formatted in HTML.

    report.html by default or {report-file-name}.html if report-file-name is specified.

    Generated when test-suite-path is specified.

  • {report-file-name}.csv

    Report formatted in CSV.

    report.csv by default or {report-file-name}.csv if report-file-name is specified.

    Generated when test-suite-path is specified.

Examples

Execute a test suite collection in a project with the mandatory inputs:

- uses: katalon/katalon@v1
  with:
    # Project location (include `.prj` file), from the root folder of the workspace
    project: path/to/project.prj
    # Test suite collection file (without extension `.tsc`)
    test-suite-collection-path: path/to/test_suite_collection_file

Execute a test suite collection in a project with the other available inputs:

- uses: katalon/katalon@v1
  with:
    # Project location (include `.prj` file), from the root folder of the workspace
    project: path/to/project.prj
    # Test suite collection file (without extension `.tsc`)
    test-suite-collection-path: path/to/test_suite_collection_file

    # Web Service|Firefox|Chrome|Remote|IE|Edge|Edge (Chromium)|Safari|Android|iOS
    browser-type: Edge (Chromium)
    # Execution profile that a test suite or a test suite collection executes with
    execution-profile: profile42
    # number of retry times; 0 for no retry
    retry: 1
    # number in seconds
    status-delay: 0
    # e-mail address for receiving report files
    send-mail: nobody@example.com
    # Destination folder for saving report files
    report-folder: path/to/report_folder
    # Name for report files (`.html`, `.csv`, `.log`)
    report-file-name: my_report

    # (all other options)
    extra-options: additional_options

Execute a test suite in a project with the mandatory inputs:

- uses: katalon/katalon@v1
  with:
    # Project location (include `.prj` file), from the root folder of the workspace
    project: path/to/project.prj
    # Test suite file (without extension `.ts`)
    test-suite-path: path/to/test_suite_file
    #  Web Service|Firefox|Chrome|Remote|IE|Edge|Edge (Chromium)|Safari|Android|iOS
    browser-type: Web Service

Execute a test suite in a project with the other available inputs:

- uses: katalon/katalon@v1
  with:
    # Project location (include `.prj` file), from the root folder of the workspace
    project: path/to/project.prj
    # Test suite file (without extension `.ts`)
    test-suite-path: path/to/test_suite_file
    # Web Service|Firefox|Chrome|Remote|IE|Edge|Edge (Chromium)|Safari|Android|iOS
    browser-type: iOS

    # Execution profile that a test suite or a test suite collection executes with
    execution-profile: acceptance
    # number of retry times; 0 for no retry
    retry: 0
    # (number in seconds)
    status-delay: 12
    # e-mail address for receiving report files
    send-mail: me@example.com
    # Destination folder for saving report files
    report-folder: path/to/report_folder
    # Name for report files (`.html`, `.csv`, `.log`)
    report-file-name: summary

    # (all other options)
    extra-options: additional_options

katalon/execute@v1

An execute function for use by generators.

Info

The result of each executed Squash TM test case is calculated by taking into account the individual results of each test case belonging to the test suite collection or to the test suite, of the Katalon project file (.prj) processed:

  • If at least one test has an Error status (in case of a technical issue), the status of the execution will be Blocked.
  • If at least one test fails functionally and none of the other has an Error status, the status of the execution will be Failed.
  • If all tests succeed, the status of the execution will be Success.

Environment variables

The following environment variables must be defined in the execution environment:

  • KATALON_API_KEY = Katalon API license key, for example: 123a4567-123a-1ab2-1234-1234567890ab.
  • KATALON_ORG_ID = Organisation ID at Katalon, for example: 123456.

Additionally, when executing a test suite without specifying the browser-type input, the following environment variable must also be defined:

  • KATALON_BROWSER_TYPE = Default browser type, for example: Web Service.

Finally, the following environment variable can also optionally be defined:

  • KATALON_EXECUTION_PROFILE = Execution profile to be used, for example: "production".

Test Reference format

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

  • {project}/{prjfile}#{collection}#{suite}#[{testcase}]

With:

  • {project} (required): name of the project on the source code repository.
  • {prjfile} (required): path to the name of the Katalon project file (with its .prj extension), from the root of the project.
  • {collection} (exclusive): relative path from the Katalon project folder to the name of the test suite collection. This parameter is exclusive with respect to {suite}.
  • {suite} (exclusive): relative path from the Katalon project folder to the name of the test suite. This parameter is exclusive with respect to {collection}.
  • {testcase} (optional): relative path from the Katalon project folder to the name of the specific test case to be parsed for which you want to obtain a particular result.

Automated test reference and execution

The relative path from the Katalon project folder to the name of the specific test case precision ({testcase} in the test reference) has no impact on the execution, but only on test result determination.

So, even when defining the specific level of the specific test case, all test cases defined in the test suite collection or in the test suite will be executed (this means, for example, that if several Squash TM test cases point toward the same test suite collection or toward the same test suite, but toward different test cases, then all the test cases will be executed several times).

The test reports include the traces of all executed requests. But, only the Error / Failed / Success status corresponding to the specific test case is used to determinate the test case result.

Exclusive choice of test suite collection or test suite

The {collection} and {suite} sections are mutually exclusive: either the test suite collection or the test suite must be populated, but not both. In the end, the test reference must contain three characters #.

Inputs

The function has the following inputs:

  • test (required)

    The test reference.

Reports

The function generates the following reports:

  • JUnit_Report.xml

    A Surefire report (XML).
    Generated when a test suite collection or test suite is executed.

    The Surefire report has the application/vnd.opentestfactory.katalon-surefire+xml content type.

  • Katalon_reports.tar

    A TAR archive.
    Contains all files present in the reports folder.

    Generated when a test suite collection or test suite is executed.

  • report.html

    Report formatted in HTML.
    Generated when a test suite is executed.

  • report.csv

    Report formatted in CSV.
    Generated when a test suite is executed.

Examples

Execute a test suite collection in the project.prj project:

- uses: katalon/execute@v1
  with:
    test: repo/path/to/project.prj#relative_path/to/testSuiteCollection##relative_path/to/testCase

Execute a test suite in the project.prj project: 

- uses: katalon/execute@v1
  with:
    test: repo/path/to/project.prj##relative_path/to/testSuite#relative_path/to/testCase

katalon/params@v1

A 'params' function for use by generators.

Order of priority in case of variable homonymy

The same variable can be defined in various places. In this case, when a test is run with the katalon/execute@v1 action and this test uses the variable, the order of precedence is (in decreasing order):

  1. Test parameter defined by the katalon/params@v1 action,
  2. Global parameter defined by the katalon/params@v1 action,
  3. Global variable coming from the profile defined by the KATALON_EXECUTION_PROFILE environment variable,
  4. Global variable coming from the default profile.

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: katalon/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: Katalon Inception
resources:
  files:
  - report1
jobs:
  my_specific_job:
    runs-on: inception
    - uses: actions/prepare-inception@v1
      with:
        JUnit_Report.xml: ${{ resources.files.report1 }}
    - uses: katalon/execute@v1
      with:
        test: katalonProject/src/project.prj

You can use the following command to run it:

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

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