Skip to main content
Version: 26.1

Rerun developers guide

important

Starting from ReportPortal 26.1, reporting API endpoints use project key (projectKey) instead of project name.

You can find the project key in Project settings → General.

What is rerun​

Let's imagine we have some set of tests:

After run we can see few failed items:

We are fixing issues and want to launch tests again. But running all the tests can take a lot of time. So it would be better to run only failed tests from previous launch.

Now we have the following:

So what do we have here? Two launches with the same tests that was just be started again, but they are have difference in passed and failed items. And it is hard to find which test was fixed and which was not.

The main idea of reruns is to restart the same launch and trace changes between them not creating new launch every time.

Let's try to report the same launches using rerun.

We have only one launch with last run data

On the step view we can see that items with names getActivitiesForProject, getActivityPositive and getTestITemActivitiesPositive have retries. Items getActivityPositive and getTestITemActivitiesPositive was fixed and getActivitiesForProject is still failing.

How to start rerun​

Latest launch​

Using API​

To start launch rerun you should call default start launch endpoint adding "rerun": true parameter in the request body.

{
"name": "launch_name",
"description": "some description",
"mode": "DEFAULT",
"rerun": true
}

And response will contain found launch id for asynchronous endpoint or id and number for synchronous.

{
"id": "89f6d409-bee0-428e-baca-4848f86c06e7",
"number": 4
}

Using agent​

To start launch rerun add rp.rerun=true to reportportal.properties file. No need to change anything else (name, project, etc.).

rp.endpoint=https://rp.com
rp.apiKey=caccb4bd-f6e7-48f2-af3a-eca0f566b3bd
rp.launch=rerun_test_example
rp.project=reporting-test
rp.reporting.async=true
rp.rerun=true

Handling​

System tries to find the latest launch on the project with the same name as in the request.

If launch found - system updates the following attributes (when present in the request):

  • Mode
  • Description (replaced if provided)
  • Attributes (added to existing ones)
  • UUID (replaced if provided)
  • Status = IN_PROGRESS

If system cannot find a launch with the same name - system throws error with 404 code (LAUNCH_NOT_FOUND).

Specified launch​

Using API​

To start launch rerun you should call default start launch endpoint adding "rerun": true and "rerunOf": "launch_uuid" parameters in the request body. Where launch_uuid is UUID of launch that have to be rerun.

{
"name": "launch_name",
"description": "some description",
"mode": "DEFAULT",
"rerun": true,
"rerunOf": "79446272-a439-45f9-8073-5ca7869f140b"
}

And response will contain found launch id for asynchronous endpoint or id and number for synchronous.

{
"id": "79446272-a439-45f9-8073-5ca7869f140b",
"number": 4
}

Using agent​

To start a launch rerun using the agent, set rp.rerun=true and rp.rerun.of=launch_uuid in the reportportal.properties file. In the latest versions of ReportPortal server always returns the same launch UUID in the response for rerun launch, so no need to set anything else if you want to preserve it.

Here's an example of what your reportportal.properties file might look like:

rp.endpoint=https://rp.com
rp.apiKey=caccb4bd-f6e7-48f2-af3a-eca0f566b3bd
rp.launch=rerun_test_example
rp.project=reporting-test
rp.reporting.async=true
rp.rerun=true
rp.rerun.of=79446272-a439-45f9-8073-5ca7869f140b

In this example, 79446272-a439-45f9-8073-5ca7869f140b is the UUID of the launch you want to rerun.

Handling​

System looks up the launch by rerunOf UUID within the project.

If launch found - the same updates are applied as for latest launch:

  • Mode
  • Description (replaced if provided)
  • Attributes (added to existing ones)
  • UUID (replaced if provided)
  • Status = IN_PROGRESS

If launch with the given UUID is not found on the project - system throws error with 404 code (LAUNCH_NOT_FOUND).

Test Items behavior​

There are no differences in API calls for starting and finishing items inside rerun launch. But such items handling is different.

Rerun matching is based on test case identity within the same launch:

  • If testCaseId is provided in the start item request, it is used to build the identity hash.
  • Otherwise the hash is generated from the item structure (including name and parameters).
  • Root items are also matched by name.
  • Child items are matched under the same parent.

Nested steps (hasStats=false) are not handled by rerun logic: a new item is always created.

Container types (has children)​

System tries to find an existing item with the same test case identity under the same parent (or as a root item with the same name).

If such item found - the following attributes will be updated:

  • Description
  • Attributes (overwritten; system attributes are preserved)
  • UUID (replaced if provided in the request)
  • Status = IN_PROGRESS

If not - new item will be created.

Step types (without children)​

System tries to find an existing item with the same test case identity under the same parent.

If such item found - a retry of the item will be created.

If not - new item will be created.

Example​