Trigger on-demand automated test runs
This topic explains how to integrate with your testing framework. You can then select automated tests from your testing framework, and run them in the context of a test suite.
Overview
This integration enables you to run on-demand tests in your testing framework using your CI server.
This is useful in a number of scenarios. For example, suppose your CI server ran automated nightly tests, and the OpenText Core Software Delivery Platform pipeline shows that a specific test failed. After pushing a fix, you can run the specific test directly from OpenText Core SDP, rather than running the full pipeline which can be time-consuming.
The testing framework integration includes the following steps:
-
Create a job in your CI server. To set up the integration, create a job on your CI server to run tests on your testing framework.
-
Create a test runner. Create a test runner entity that corresponds to this job on your CI server.
-
Run tests. Create a test suite that includes tests that you want to run in your testing framework, and run the suite. The test runs are triggered using the job in the CI server.
-
Analyze release and product quality. Track the test results as part of the overall data in the backlog, quality, and dashboard modules.
Prerequisites
Ensure the following prerequisites are met:
-
You must be connected to a CI server. For details, see Set up CI/CD integration.
-
Create a pipeline to inject tests from your testing framework using your CI server. For details, see Create and configure pipelines.
-
The integration supports various frameworks such as JUnit and TestNG tests over Maven, Protractor, and Gradle. The full list of preconfigured options can be found in the plugin documentation.
Using the Jenkins plugin version 5.9 or later, you can trigger automated runs in additional frameworks using the Custom option, as described below.
To add test frameworks or CI servers, contact Support.
Tip: You can integrate with GitLab to run OpenText Functional Testing tests in GitLab on-demand. For details, see Run tests on-demand using GitLab.
Step 1: Create a job on the CI server
To run tests in your testing framework, create a job on your CI server.
To create a job:
-
On your CI server, create a job that runs specific tests on your testing framework.
-
In addition to the command to run tests on your framework, this job must include the testsToRun parameter, which receives a lists of tests that the job should run. The parameter contains the following test details for each test:
- package
- class name
- test name
- run ID
- external test ID (optional)
- custom parameters coming from the Test execution parameters field
There are two formats for testsToRun value: textual and JSON.
Textual format:The format passes test details in the form of key=value. Each set is separated with the pipe symbol ( | ) and different tests are separated with a semicolon ( ; ).
The first three details are predefined and have the value package name|class name|test name.
Copy codeExample: Textual formatv1:com.simple.tests|AppTest|testAppB|externalTestId=bbb|runId=1081|param1=value1|param2=value2;com.simple.tests|AppTest|testAppA|externalTestId=aaa|runId=1082
JSON format:The textual format uses the characters | ; and = as special characters. If your test details might contain these characters, parsing on the CI server side will have errors. In this case you should switch to JSON format. This can be done by defining the site/space parameter TESTS_TO_RUN_PARAMETER_JSON_FORMAT = true.
Copy codeExample: JSON format{
"version": "v2",
"testsToRun": [{
"packageName": "com.simple.tests",
"className": "AppTest",
"testName": "testAppB",
"parameters": {
"externalTestId": "bbb",
"runId": "1077",
"param1": "value1",
"param2": "value2"
}
}, {
"packageName": "com.simple.tests",
"className": "AppTest",
"testName": "testAppC",
"parameters": {
"externalTestId": "ccc",
"runId": "1078"
}
}
]
}To define a custom parameter, see Use custom execution parameters.
You then need to convert the contents of this parameter to a syntax that can be used by your testing framework.
-
(Optional) In addition to the testsToRun parameter, your job can receive additional parameters from OpenText Core SDP. Add parameters with desired name to the job. Possible values:
-
suiteId
-
suiteRunId
-
octaneWorkspaceId
-
octaneSpaceId
-
octaneEnvironment
Note: This parameter is only received when all the runs related to a specific test runner share the same environment definition.
-
-
Make the configurations necessary for your framework. These configurations convert testsToRun raw data to your relevant framework format.
Team CityIf you are using Team City, add a parameter called Testing_framework, and enter one of the following values: mvnSurefire (for JUnit), protractor, or custom.
For Team City with Gherkin, see Publish Gherkin test results in Team City.
GitLabIf you are using GitLab:
-
Add a parameter called testRunnerFramework and assign it one of the following values:
-
mvnSurefire for JUnit
-
uft for OpenText Functional Testing when using FTToolsLauncher
-
custom for any common testing framework
-
-
Configure the testRunnerBranch, the name of the branch that holds the TestRunner pipeline.
-
For custom frameworks, add testRunnerCustomPattern. Its value should be a JSON object containing a pattern to convert the automated test from OpenText Core SDP to the framework's required format. This is supported for GitLab 23.3.1 or later. For an example, see Structure of the testRunnerCustomPattern json.
For additional details, see the Test Framework documentation.
Jenkins or BambooIf you are using Jenkins or Bamboo, add the OpenText Core Software Delivery Platform testing framework converter build step/task to your job.
This converts the testsToRun raw data to your relevant framework format. To help you do this, you can use the OpenText Core SDP testing framework converter in the Jenkins plugin version 5.5.2 or later, or in the Bamboo plugin version 1.6 or later.
The converter creates a testsToRunConverted parameter, which you then use in the test run. Make sure that the converter step runs before the test run step.
Azure DevOpsThe following testing frameworks are supported for use with Azure DevOps: JUnit, TestNG, Cucumber – JVM over Maven, and BDD Scenario.
-
If you are using Azure DevOps, create the following additional empty variables: executionId, suiteRunId, testsToRun.
-
In Azure project settings, set Limit variables that can be set at queue time to OFF.
-
By default, you cannot set the following variables: executionId, suiteId, octaneTestRunnerFramework, octaneSpaceId, octaneEnvironment, suiteRunId, octaneWorkspaceId, octaneRunByUsername. If you want to set these variables, edit the pipeline in Azure, and select Settable at queue time on the pipeline editor's Variables tab.
-
Add an ALM Octane Test Runner Job Start task to the pipeline in Azure DevOps. This creates a test runner during the first pipeline run, and you do not need to manually create a test runner later.
Tip: To maintain synchronization between parameters of the test runner and the Azure DevOps pipeline, use the sync CI server option in the test runner.
The first pipeline run on Azure DevOps creates a CI server.
Custom testing frameworkYou can define conversation formats for any custom testing framework, for the following plugin versions:
-
Jenkins version 5.9 or later
-
Bamboo version 1.10.2 or later
To define your custom conversation format:
- In the OpenText Core Software Delivery Platform testing framework converter build step/task, select Custom.
- In the Custom conversion format field, describe how to convert tests from raw format to your testing framework's format.
- After conversion, the result is stored in the testsToRunConverted parameter.
You can use the dropdown to display a template containing a sample configuration. You can then modify the template text according to your specific testing framework syntax.
For details, click the help button on the field.
-
Examples of how to use testsToRunConverted
-
Windows batch build step:
mvn clean -Dtest=%testsToRunConverted% test
-
Linux shell build step:
mvn clean -Dtest=$testsToRunConverted test
-
WorkflowJob (Windows):
bat 'mvn clean -Dtest=${params.testsToRunConverted} test'
-
WorkflowJob (Linux):
sh 'mvn clean -Dtest=${params.testsToRunConverted} test'
-
Windows batch build step:
mvn clean -Dit.test=%testsToRunConverted% verify
-
Linux shell build step:
mvn clean -Dit.test=$testsToRunConverted verify
-
WorkflowJob (Windows):
bat 'mvn clean -Dit.test=${params.testsToRunConverted} verify'
-
WorkflowJob (Linux):
sh 'mvn clean -Dit.test=${params.testsToRunConverted} verify'
-
Windows batch build step:
protractor conf.js --grep="%testsToRunConverted%"
-
Linux shell build step:
protractor conf.js --grep="$testsToRunConverted"
-
WorkflowJob (Windows):
bat(/protractor conf.js --grep="${params.testsToRunConverted}"/)
-
WorkflowJob (Linux):
sh(/protractor conf.js --grep="${params.testsToRunConverted}"/)
-
Windows batch build step:
gradle test %testsToRunConverted%
-
Linux shell build step:
gradle test $testsToRunConverted
-
WorkflowJob (Windows):
bat 'gradle test ${params.testsToRunConverted}'
-
WorkflowJob (Linux):
sh 'gradle test ${params.testsToRunConverted}'
-
mvn clean -Dcucumber.options=%testsToRunConverted% test
Note: You can also automate BDD scenarios.
-
Windows batch build step:
mvn clean -Dfeatures="%testsToRunConverted%" test
-
Linux shell build step:
mvn clean -Dfeatures="$testsToRunConverted" test
-
Pipeline:
bat(/mvn clean -Dfeatures="${testsToRunConverted}" test/)
-
Windows batch build step:
mvn clean -Dtest=%bamboo_testsToRunConverted% test
-
Linux shell build step:
mvn clean -Dtest=$bamboo_testsToRunConverted test
-
Windows batch build step:
mvn clean -Dit.test=%bamboo_testsToRunConverted% verify
-
Linux shell build step:
mvn clean -Dit.test=$bamboo_testsToRunConverted verify
-
Windows batch build step:
protractor conf.js --grep="%bamboo_testsToRunConverted%"
-
Linux shell build step:
protractor conf.js --grep="$bamboo_testsToRunConverted"
-
Windows batch build step:
gradle test %bamboo_testsToRunConverted%
-
Linux shell build step:
gradle test $bamboo_testsToRunConverted
Step 2: Create a test runner
To run tests in your testing framework, create a test runner.
Note: If you are integrating with Azure DevOps, include a task in your pipeline to automatically create a test runner when running the pipeline. For details, see Step 1: Create a job on the CI server.
To create a test runner:
-
Open the Settings menu , click Spaces, and select a workspace.
-
Select the DevOps > Test Runners tab.
-
Click + Test Runner.
-
Define a name for the test runner, for example JUnit Runner.
-
Select your testing framework, for example JUnit.
-
Select your CI server.
-
Select the job that you created in the CI server to run the tests in your testing framework. The list displays the jobs that have the testsToRun parameter.
-
(Optional) In the Build Report URL box, enter a URL or a URL template to use to create a link to reports generated for your builds.
If you include
{job_name}
and{build_number}
placeholders in the template, they are replaced in the URL with the relevant job name and build number when creating the link.Copy codeExample: URL to create a link to reports generated for your buildshttp://myServer:myPort/jenkins/job/{JobName}/{BuildNum}/reports/logs/jenkins-test-reports.html
The links are added to the test runs that are created as part of this pipeline step and to the build that is the result of this step.
-
(Optional) In the Test Run Report URL box, enter a URL or a URL template to use to create a link to reports generated for your test runs.
Note: If you have defined an External Report URL in your CI server, that URL setting overrides the OpenText Core SDP URL definition.
If you include placeholders in the template such as
{test_class}
and{test_name}
, they are replaced in the URL with the relevant entity when creating the link.Copy codeExample: URL to create a link to reports generated for your test runshttp://myServer:myPort/{root_job_name}/{job_name}/{build_number}/{test_component}/{test_package}/{test_class}/{test_name}/{root_job_build_number}/reports/logs/jenkins-test-reports.html
The links are added to the test runs that are created as part of this pipeline step.
Tip: You can select the Override test run report URL inheritance checkbox so that the current job does not inherit the URL format from its parent in the topology.
-
If your job is parameterized, you can define sets of parameter values that can be used when running tests using a test runner. For details, see Use parameter sets in the test runner job.
-
Click Save. A test runner is created to trigger the job that runs your tests.
Repeat the above steps to create additional test runners.
Note: Each job can only be used for one test runner.
Step 3: Run tests
Assign test runners to tests in the Quality module. You can then add the tests to test suites, and run them.
Test runs are triggered through the job on the CI server that is specified in the test runner. After adding tests to a suite, you can select a different test runner for a test in the suite. In addition, after planning a suite you can select a different test runner for a test run.
A suite can include automated tests using multiple test runners. When a suite includes both manual tests and automated tests, the automated tests run in the background while you perform the manual tests.
When you run a test, its status is Planned until the test runner starts to run the tests in the CI server. The test's status changes to In Progress, until the test results are returned.
Manage test runners
After you associate a test with a test runner, you might want to make changes at a later stage.
For example, suppose you delete a CI server or the test runner's related job, and you want to keep the association between the tests and the test runner. In this case, edit the test runner within DevOps > Test Runners, and specify a different CI server or job for the tests associated with this test runner.
Similarly, if you delete a CI server in OpenText Core SDP, the test runner associated with this CI server is not deleted, and its tests remain associated with the test runner. However, you are not able to run any of the tests associated with the test runner.
Use parameter sets in the test runner job
If your CI server job is parameterized, you can define different sets of parameter values that can be used when running tests using a test runner. Each test runner can have multiple sets of parameter values.
For example, suppose you want to run one test suite on one deployed environment, and another on a different one. You can create one parameter set (Set 1) using the default URL and port, and another (Set 2) with a different URL and port. You can then run the same suite a few times using different settings.
To configure parameters in the test runner:
- When creating a test runner, you select a job to run tests. If this job is parameterized, a table appears showing the parameters configured in the CI server, with their default values.
- In the column headings, add columns to define additional sets of parameter values.
- You can rename each column heading as needed.
- You can edit parameter values in each set of parameters as needed.
- To delete a column or restore its default values, select the relevant menu item in the column.
- Click Save.
Note:
- Only boolean and string parameters are supported. If a parameter contains no value or an incorrect value (for example if the parameter is boolean but the value entered is string), it is skipped during the test run.
- Parameters are not supported for OpenText Functional Testing test runners.
To select parameters when running a test:
You define a parameter set for suite run execution when tests are in Planned state. All of the tests using a specific runner run using the selected parameter values.
- In a test suite with automated tests, select Plan Suite > Suite Run > Runs.
- In the Test Runners tab, select the settings on a test runner.
-
From the list of parameter sets that have been defined for this test runner, select a set to use in the test execution.
The Test runner parameters field can be added to the Runs grid to see the parameter set that was selected for this suite run.
-
Run the test suite.
The test suite runs using one or more sets of parameter values that you selected.
A tooltip on the Test runner parameters field shows the parameter values that were used by the job.
Use custom execution parameters
When planning a suite run using the testing framework, you can specify one or more sets of custom parameters to be used by your testing tool.
Custom execution parameters are supported with the Jenkins plugin version 6.3 or later.
To define custom execution parameters:
- In the test suite's Planning tab, add the Test execution parameters field.
- Enter one or more items using the format <key>=<value>
- Use semicolons (;) or line breaks to separate between parameters.
- To define parameters for OpenText Functional Testing tests (with Jenkins plugin 6.5 and later), use the format <key>=(<type-optional>)<value>. Type is an optional field. Supported types are String, Number, Boolean, Date, Any.
The value of this field is parsed to extract parameters. Valid values are passed in the testsToRun parameter to the CI server job, for test execution.
To define iterations of parameters for OpenText Functional Testing tests:
This functionality uses the Iteration model. For details, see IterationMode Property.
The following steps assume that you already have defined several sets of parameters in the data table of your test.
-
In the test suite's Planning tab, add the Test execution parameters field.
-
Enter one of the following in the Test execution parameters for your test.
Action Enter Run a range of iterations iterations=rngIterations,<start of range>,<end of range>
Example: To run iterations 1 through 5, enter
iterations=rngIterations,1,5
Run all iterations iterations=rngAll;
Run the first iteration only (default) iterations=oneIteration
Stop automated tests in a suite run
Note: This feature is supported on Jenkins and Bamboo test runners.
If you are running a test suite with automated tests you can stop them before the suite is done.
To stop all test runs under a suite run:
-
In the test suite's Suite Runs tab, select a suite run that you want to stop. (You can only stop one suite run at a time.)
-
In the Suite Runs grid, or in the suite run's Details view, click Stop suite run.
This stops all automated test runs that are currently running.
-
The status of the stopped runs is set to Skipped. If all the runs under the suite are skipped, the suite run's status is also set to Skipped.
Note: The Stop suite run button is only available when you have at least one automated run under the suite run, and when you have permissions to run a test suite.
To stop a specific test runner under a suite run:
-
In the test suite's Suite Runs tab, select the specific suite run that you want to stop.
-
Within the suite run, select the Runs tab.
-
In the Test Runners pane, click Stop in each of the test runners whose activity you want to stop.
This stops the specific instance of the test runner's execution, and the test runs related to this runner's instance are therefore stopped. When you refresh the view, the status of the related test runs changes to Skipped.
Rerun automated tests
If you ran a test suite in an automated run, and you want to run it again (for example, if a test failed) you can rerun it without having to create a new suite run.
Note: A rerun is only possible after the previous run has finished.
To rerun an entire test suite:
-
Open a test suite from your list of tests and select the Suite Runs tab. The page displays a list of suite runs.
-
In the list, select a suite run, and click Run. All automated tests included in the test suite begin their run on the integrated server.
Alternatively, you can rerun a test suite by clicking the ID of a suite run in the list, and then clicking Run in the suite run Details tab.
Note: When you run a test suite in an automated run, the previous results are overwritten.
To rerun a specific run of a test suite:
- Open a test suite from your list of tests and select the Suite Runs tab. The page displays a list of suite runs.
- In the list, click on the ID of a suite run. The suite run Details tab opens.
- Select the Runs tab to see a view of the runs for this test suite.
- Select one or more runs.
- Click Run. The selected runs are rerun.
Manage automated tests per test runner
Use the Test Runners tab to separately manage the run for specific test runner tests.
From the Test Runners tab, you can perform the following operations on individual test runners.
Action | Description |
---|---|
Run |
Click the Run button to perform an initial run for tests associated with the selected test runner. |
Rerun |
Click the Rerun button to rerun the automated run for tests associated with the selected test runner. |
Stop |
Click the Stop button to abort the automated run that is currently running or in queue to run. |
The following table describes the status of the test for which each operation applies.
Operation | Test status |
---|---|
Run | Planned |
Stop | Initialize |
Stop | Running |
Rerun | Finished |
Rerun | Aborted |
Rerun | Failure |
Note: When you click on a test runner, the runs are automatically filtered for that test runner.
Run Gherkin tests using Cucumber-JVM over Maven
The Cucumber test runner enables you to run Gherkin tests on Jenkins, using Cucumber-JVM over Maven. When you run a Gherkin test, you run the full feature file, including all scenarios. This is supported by the Jenkins plugin version 6.2 and later.
You can also automate BDD scenarios.
Prerequisite: To enable running Gherkin tests on Jenkins using the test runner mechanism, first automate Gherkin tests and run them from the pipeline. For details, see Prepare Gherkin tests for automation.
To create a Cucumber test runner:
-
Create a job in Jenkins and set up a Cucumber test runner. For details, see Run Gherkin tests using Cucumber-JVM over Maven.
-
Create a Gherkin suite.
You can include tests from a pipeline, and tests that you created in OpenText Core SDP.
Caution: If you run a test manually, and then automate it using a test runner, the manual run's history in the Last runs column is overwritten. It is replaced with the automated run's history.
-
In the Test runner column, select the test runner that you created.
-
In the Run mode column, specify whether each test should run manually or automatically. The default is manual, just like regular manual tests. (This column is not relevant for other types of tests.)
To use the test runner, set run mode to Automatically.
-
Run the suite.
The Suite run > Runs tab displays details of the test runner that is running the automated tests.
-
Manually run any tests that you did not define as automatic.
Tip: If you created a manual test and copied the code to run it in an IDE, you can now use this testing framework to run the test.
Run Gherkin tests using JBehave
To run JBehave tests using the testing framework, your embedder should be able to receive a parameter that indicates what feature files it should run.
To run Gherkin tests using JBehave:
-
Add OctaneGherkinReporter to your running configuration as a reporter. For details, see Automate Gherkin tests.
-
In your embedder, override storyPaths as follows:
Copy code@Override
protected List<String> storyPaths() {
String include = "**/*.feature";
String featuresProperty = System.getProperty("features"); // -Dfeatures
if (featuresProperty != null) {
include = featuresProperty;
}
return new StoryFinder().findPaths(
codeLocationFromClass(embeddableClass),include,"");
} -
Implement the test runner mechanism. For details, see Run Gherkin tests using Cucumber-JVM over Maven.
Use the JBehave test runner to execute your tests. For examples of the Jenkins test runner syntax, see Examples of how to use testsToRunConverted.
Publish Gherkin test results in Team City
After running Gherkin tests, you can publish the test results in Team City.
To publish Gherkin test results in Team City:
-
In your project settings, define an artifact path to the Gherkin result.
In the above example, Team City creates the
gherkin
folder in the artifact directory, and moves to it all files that fit the patterngherkin-results/*_OctaneGherkinResults.xml
. -
Add a configuration parameter gherkin_artifact_folder_for_octane with the value of the folder you used in step 1 (in this case
gherkin
). -
In the test runner, use the following:
-
Maven command:
clean test "-Dcucumber.options=%testsToRun%"
-
Parameter:
Testing_framework : cucumber_jvm
-
Next steps: