Jenkins integration

For the interaction between aqua and Jenkins, the famous open source continuous integration tool, we have developed a plugin that can be installed in Jenkins and that allows you to trigger Jenkins jobs from aqua and vice versa, meaning that you can trigger test scenarios in aqua from a Jenkins job.

Unit test results can also be written back to aqua to take advantage of aqua's powerful reporting feature. In addition, aqua links can be parsed from a repository's comments (e.g. Subversion or Git) and displayed in Jenkins. This chapter details the steps required to set up and configure integration with Jenkins.


  • Before starting the installation of the Jenkins plugin, please ensure that you have the right Jenkins plugin corresponding to your aqua installation version number and your Jenkins installation version number. If you are not sure, please contact our support team.

Installing the aqua Jenkins plugin

The Jenkins plugin is not available from the Jenkins plugin store. The Jenkins plugin file is delivered as "aquaJenkinsPlugin.hpi" and can be downloaded from the aqua homepage. To install this plugin, open the Jenkins dashboard and select Manage Jenkins on the left-hand side. Then select Manage plugins in the middle.

Now you can upload the plugin file from your computer, or paste the link to download the Jenkins plugin into the URL field.

Configuring the Jenkins plugin

To configure the plugin, please go to the Manage Jenkins and select the Configure System section.

Scroll down until the section called Aqua Plugin.

As you can see in the screenshot, the plugin requires the following information:

Agent code

An agent code that identifies the plugin in your aqua installation. Retrieve this code by opening aqua. Right-Click the corresponding project and choose “Project Configuration” => “Automation”. On the appearing window add a new agent, call it Jenkins (or similar) and save your settings.

Agent Webservice URL

The Webservice URL for aqua Agents. Retrieve this information from your administrator. You can check this URL by opening the URL in your browser. You should see a website entitled “aquaAgentWebservice”.

Agent active

This activates your Jenkins Plugin.

Main Webservice URL

The common Webservice URL for retrieving test cases. Retrieve this information from your administrator. You can check this URL by opening the URL in your browser. You should see a website entitled “MainService”. This is only used for the direction Jenkins -> aqua

aqua user name

A valid aqua user name that is used for authentication. This is only used for the direction Jenkins -> aqua


The corresponding password that is used for authentication. This is only used for the direction Jenkins -> aqua

Name of your aqua instance

When you have completed your settings, please save them by clicking Save in Jenkins. You can check if your settings have been successful by opening your aqua Client.

Jenkins Jobs Configuration

To trigger the Jenkins Jobs from aqua, open your test in Jenkins and select 'Configure' tab

Then the source code repository URL needs to be provided.

If you would like to run the maven test, please be sure the proper configuration was adjusted

To publish the JUnit test results, first make sure that the test results are displayed in Jenkins and fulfill the test report XMLs field.

aqua notifier - sending test results to aqua

Unit test results are shown in Jenkins. However, to get access to this information in aqua, you have the option to write back the results into a template test case in aqua. The first step is to create this test case in aqua. Open a new test case, give it a name, e.g. “Unit test results”, then save and close the test case. Then go to your Jenkins Job, add a new Postbuild Action called aqua Notifier” and enter the Id of your aqua test case.

When executing this Jenkins job now, your Unit test results are written to your aqua test case and stored as a new execution in this test case. Please be aware that in addition to the creation of a new test execution, the test description and all test steps are replaced with the information from Jenkins, every time the Jenkins job is executed. Therefore, any information stored in the test case description or test steps will be replaced.

Do not save the Unit test results into the same test case that triggers a Jenkins job!

You can also use a variable for the Test Case Id (e.g. $TestCaseVariable) if you have a parameterized Jenkins job and want to store the results in different test cases in aqua. For this purpose, all test cases from the variable values must exist in aqua.

Triggering Jenkins Jobs from aqua

Then open the corresponding test case in aqua. Check whether, under the test step -> 'Automation' tab, the appropriate job ID from Jenkins was inputted.

Now you can execute the given Test Case in aqua with the usage of the Jenkins agent.

A Jenkins job can be parameterised. If you want to override a specific parameter, e.g. Environment, you can parameterise your aqua test case (see the Data tab in the left-hand menu). When the given Jenkins job is triggered via aqua, the given value will be set correctly in Jenkins.

Once the execution is done you can check in aqua the information collected during it including the logs.

Triggering Test Scenario execution from Jenkins

aqua test scenarios can be triggered from Jenkins. This is a convenient way to run your automated tests in aqua after a successful build in Jenkins. To add this trigger, add a build step called aqua test scenario Trigger. This will add the following form to your Jenkins job.

If no Agent is specified in the aqua Test Scenario, then it will be taken from the Agent Name value in Jenkins. The output path creates the report in Jenkins, and then the results can be published in Jenkins - useful if you want to integrate Aqua with Jenkins and then trigger some Ranorex jobs.


  • Configuration changes to the plugin might require Jenkins restart

  • Item IDs can have at most 6 digits

  • aqua build steps for Jenkins do not support the Jenkins pipeline (please use the freestyle instead)

Last updated