Configuring Jenkins Pipelines to Run TestComplete Tests

Applies to TestComplete 14.30, last modified on November 21, 2019

To run your TestComplete tests as part of a Jenkins Pipeline:

1. Specify nodes on which tests will run

The node where you will run tests must have TestComplete or TestExecute installed. To make sure you will run your tests on the appropriate nodes only, add code to your Pipeline script (Jenkinsfile) that will specify the needed nodes. For example, you can use labels, tags or node names to specify where the tests should run:

Show Example

For details, see the Jenkins Pipeline documentation at jenkins.io/doc/book/pipeline/syntax/.

2. Add steps that will prepare testing environments

Prepare your nodes to run TestComplete tests:

  1. Copy TestComplete project files, your tested application, and other test-related files to the nodes where the test will run.

    Note: TestComplete test project files must reside in the node’s working folder or in its subfolders.
  2. Make sure TestComplete tests can access all the files they needed during the test run.

Otherwise, Jenkins will not be able to run your test.

You can copy all the needed files to the nodes in advance, or you can add steps to your Jenkins Pipeline to perform all the preparation tasks. To learn more about the steps you can use, see jenkins.io/doc/pipeline/steps/.

3. Add script statements to run TestComplete tests

  1. If you manage your Pipeline from the Jenkins UI, open the Pipeline section of your project and locate the Script box.

    If you use SCM, open your Jenkinsfile.

  2. Add the code that will run TestComplete tests to your Pipeline script. You can write the code manually (see the Pipeline Syntax section below).

    – or –

    You can use the built-in Jenkins Snippet Generator utility to generate the code automatically:

    1. Open the Pipeline Syntax page of your Pipeline.

    2. On the resulting page, select testcomplete: TestComplete test from the Steps drop-down list:

      Jenkins Snippet Generator: Select the TestComplete Test step

      Click the image to enlarge it.

    3. Configure the step to run your TestComplete tests:

      View instructions

    4. Click Generate Pipeline Script:

      Jenkins Snippet Generator: Configure the step and generate the code

      Click the image to enlarge it.

    5. Copy the generated code, and then paste it to your Pipeline script (Jenkinsfile):

      Copy the generated code

      Click the image to enlarge it.

Examples

  • The following sample script runs a TestComplete project suite (all the enabled test items in all the enabled projects that belong to that project suite):

    testcompletetest suite: 'Projects\\JenkinsTests.pjs'
  • The following sample script runs the MyProj project of the project suite:

    testcompletetest launchType: 'lcProject', project: 'MyProj', suite: 'Projects\\JenkinsTests.pjs'
  • The following sample script runs the ProjectTestItem3 test item that is a child item of the ProjectTestItem1 test item of the MyProj project:

    testcompletetest launchType: 'lcItem', project: 'MyProj', suite: 'Projects\\JenkinsTests.pjs', test: 'ProjectTestItem1|ProjectTestItem3'
  • The following sample script runs the MyKDT keyword test of the MyProj project:

    testcompletetest launchType: 'lcKdt', project: 'MyProj', suite: Projects\\JenkinsTests.pjs', test: 'MyKDT'
  • The following sample script runs the Main script routine located in the Unit1 unit of the MyProj project:

    testcompletetest launchType: 'lcRoutine', project: 'MyProj', routine: 'Main', suite: 'Projects\\JenkinsTests.pjs', unit: 'Unit1'
  • The following sample script runs the MyProj project’s tests that match the @tag1 or (@tag2 and @tag3) tag expression:

    testcompletetest launchType: 'lcTags', project: 'MyProj', suite: 'Projects\\JenkinsTests.pjs', tags: '@tag1 or (@tag2 and @tag3)'
  • The following sample script launches TestComplete and commands it to run tests in CrossBrowserTesting.com environments:

    testcompletetest executorType: 'TC', launchType: 'lcCBT', suite: 'Projects\\JenkinsTests.pjs'
  • The following sample script opens an interactive user session on the node and runs the MyProj project:

    testcompletetest launchType: 'lcProject', project: 'MyProj', suite: 'Projects\\JenkinsTests.pjs',
    useTCService: true, userName: 'Tester', userPassword: 'password'
  • The following sample script runs the MyProj project of the project suite and exports the test results to a .mht file:

    testcompletetest generateMHT: true, launchType: 'lcProject', project: 'MyProj', suite: 'Projects\\JenkinsTests.pjs'

TestComplete Test step pipeline syntax

suite

Required. Specifies the path to the TestComplete project suite that contains the tests you want to run. The path should be relative to the node’s working folder.

Type: string

actionOnErrors

Optional. Specifies whether Jenkins should mark the entire build as failed or unstable if the test log contains errors, or whether it should not mark the build in any special way. If the parameter is not specified, Jenkins will mark the build as unstable.

Type: string

Possible values: NONE, MAKE_UNSTABLE, MAKE_FAILED

Default value: MAKE_UNSTABLE

actionOnWarnings

Specifies whether Jenkins should mark the entire build as failed or unstable if the test log contains warnings, or whether it should not mark the build in any special way. If the parameter is not specified, Jenkins will not mark the build in any special way.

Type: string

Possible values: NONE, MAKE_UNSTABLE, MAKE_FAILED

Default value: NONE

commandLineArguments

Optional. Specifies arbitrary command-line arguments to be passed to TestComplete (TestExecute). To learn more about the TestComplete command line, see TestComplete Command Line.

Type: string

executorType

Optional. Specifies whether to use TestComplete or TestExecute for the test run. If both are installed and the parameter is not specified, TestExecute will be used.

Type: string

Possible values: TC, TE.

Default value: TE

Notes:

  • The specified product must be installed on the node. If the 64-bit version of the product is available on the node, it will be used to run tests. Otherwise, the 32-bit version will be used.

  • To run tests in CrossBrowserTesting environments, set the parameter to TC.

executorVersion

Optional. Specifies the TestComplete or TestExecute version to be used if several versions of the products are installed on the node. If the parameter is not specified, the latest installed version will be used.

Type: string

generateMHT

Optional. Specifies whether the test results will be exported to a .mht file. You can download this file from the Jenkins results page.

Type: boolean

Default value: false

launchType

Optional. Specifies which part of the TestComplete project suite will be run.

Type: string

Possible values:

  • lcSuite - The default value. Runs the entire project suite (that is, all the enabled test items in all the enabled projects of that project suite). The required suite parameter specifies the needed project suite.

  • lcProject - Runs a project of the project suite. To specify the project name, use the project parameter:

    project

    Required. Specifies the name of the project that contains the tests to run. TestComplete (TestExecute) will run all enabled test items of the specified project. You can view the list of test items on the Test Items page of the project.

    Type: string

  • lcRoutine - Runs a script routine. To specify the needed routine, use the following parameters:

    project

    Required. Specifies the name of the project that contains the tests to run.

    Type: string

    routine

    Required. Specifies the name of the script routine to run (without the unit name).

    Type: string

    unit

    Required. Specifies the name of the script unit that contains the script routine to run.

    Type: string

  • lcKdt - Runs a keyword test. To specify the needed test, use the following parameters:

    project

    Required. Specifies the name of the project that contains the tests to run.

    Type: string

    test

    Required. Specifies the name of the keyword test to run. For example, MyKDTest1.

    Type: string

  • lcCBT - Runs all the tests defined in CrossBrowserTesting environments.

    Your slave nodes must have TestComplete installed. TestExecute cannot run tests in CrossBrowserTesting environments.

    TestComplete on your slave nodes must be able to access the CrossBrowserTesting cloud, and your project suite must include environments and tests assigned to them. See Prepare Jenkins Nodes to Run Tests in CrossBrowserTesting Environments.

    Type: string

  • lcItem - Runs any test your project contains: a project test item, a low-level procedure, a unit test, a network suite test, and so on. To specify the items to run, use the following parameters:

    project

    Required. Specifies the name of the project that contains the tests to run.

    Type: string

    test

    Required. Specifies the full path to the project item or test item to run. The vertical pipe character ( | ) is used as a separator.

    Show Example

    The path to your test must contain collection names only. Do not include any project folders in the path.

    Type: string

  • lcTags - Runs the project’s tests that match a tag or a tag expression. To specify a project and a tag expression, use the following parameters:

    project

    Required. Specifies the name of the project that contains the tests to run.

    Type: string

    tags

    Required. A tag or a tag expression that specifies the tests to run.

    Tag expression syntax

    Type: string

publishJUnitReports

Optional. Specifies whether Jenkins will generate JUnit-style reports.

Note: This JUnit-style report slightly differs from standard JUnit reports. To generate JUnit reports, use the /ExportSummary command line argument. You can specify it using the commandLineArguments parameter.

Type: boolean

Default value: true

useTCService

Optional. Specifies whether your TestComplete test will run in an interactive session.

Note: If this option is disabled and Jenkins is running as a service, your TestComplete tests will fail.

Type: boolean

To configure the session, use the following parameters:

userName

Required. The user account that will be used to run the test.

Type: string

userPassword

Required. The password used to log in to the user account.

Type: string

useActiveSession

Optional. Specifies whether an existing user session will be used to run tests. If the parameter is not specified, TestComplete (TestExecute) will run in the current session. Otherwise, Jenkins will close all the applications, terminate the currently active session, start a new session under the specified user account, and then start the test.

Note: Jenkins will not stop the user session if another user is logged on.

Type: boolean

Default value: true

sessionScreenResolution

Optional. Specifies the screen resolution of the user session in which your tests will run.

If the useActiveSession parameter is set to true, the sessionScreenResolution parameter will be ignored, and the actual resolution of the active user session will be used.

Type: string

Default value: 1280×1024

useTimeout

Optional. Specifies whether Jenkins should wait for the test run to finish until the specified timeout is reached. If the test run is not over before the timeout is reached, Jenkins will mark the entire build as failed.

If the parameter is set to false, the waiting time is infinite.

Type: boolean

Default value: false

To specify a timeout value, use the following parameter:

timeout

Optional. Specifies the maximum test run time, in seconds.

The timeout includes both the startup time of TestComplete (TestExecute) and the test run time. If you run tests in the CrossBrowserTesting cloud, the timeout will also include the startup time of CrossBrowserTesting environments.

If the parameter is not specified, the waiting time is infinite.

Type: string

See Also

Integration With Jenkins
Preparing Jenkins for Running TestComplete Tests
Requirements

Highlight search results