Test runs

Test runs are an important component for tracking and managing the testing process. Our REST API provides comprehensive endpoints for handling test runs, enabling you to automate and streamline your testing workflow. With these endpoints, in a project, you can access list of test runs, create new test runs, and add test results to test runs.

Get test runs list

GET /api/v2/projects/{project_id}/test-runs

Invoking this API will fetch the list of test runs in a project associated with your username and access key. You will need the id of the project to access its list of test runs.

Request Parameters

Request

curl -u "YOUR_USERNAME:YOUR_ACCESS_KEY" \
https://test-management.browserstack.com/api/v2/projects/PR-1/test-runs

project_id^* String

Identifier of the project.

Response Attributes `200 OK` `json`

Response

{
  "success": true,
  "test_runs": [
    {
      "active_state": "active",
      "run_state": "done",
      "assignee": "john@email.com",
      "created_at": "2023-11-28T13:33:26.000Z",
      "identifier": "TR-78282",
      "name": "sample build #2",
      "project_id": "PR-1",
      "test_cases_count": 5,
    }
  ]
}

active_state String

State of the test run.
run_state String

State of the test run. The valid states are new_run, in_progress, under_review, rejected, done, and closed.
assignee String

Email of the test run assignee.
created_at String

The time the test run was created on BrowserStack servers.
Identifier String

Identifier of the test run.
name String

Name of the test run.
project_id String

Identifier of the project.
test_cases_count Integer

Count of number of test cases.

Create a test run

POST /api/v2/projects/{project_id}/test-runs

Invoking this API will create test runs programmatically, providing flexibility and automation in managing your test cycles. To create a test run, you will need the id of the project in which the test run should be created. If you need to link this test run to a test plan, you will require the id of that test plan.

You can apply filters to get only the test cases you want. Attributes-based filtering allows for selecting test cases by matching one or more attribute values passed as query parameters. When you provide multiple values for the same query parameter, any one value must match the specified attributes. This means that an OR operator applies within the query parameter. On the other hand, if you include multiple attribute values across different parameters, an AND operator is used across these different parameters. This requires all conditions to be met for a match.

Request Parameters

Request

curl -u "YOUR_USERNAME:YOUR_ACCESS_KEY" \
-X POST https://test-management.browserstack.com/api/v2/projects/PR-1/test-runs

project_id^* String

Identifier of the project.

Request Body

Request Body

{
  "test_run": {
    "name": "Test Run-29/11/2023",
    "description": "check the performance of the test run",
    "run_state": "new_run",
    "assignee": "john@email.com",
    "test_case_assignee": "john@email.com",
    "tags": [
      "Regression"
    ],
    "issues": ["TASK-309"],
    "configurations": [],
    "test_plan_id" : "TP-20",
    "test_cases": ["TC-1", "TC-3"],
    "folder_ids": [34, 54, 64],
    "include_all": false,
    "filter_test_cases": {
      "status": ["active", "draft"],
      "priority": ["medium","low" ],
      "case_type": ["regression", "smoke"],
      "owner": ["randomUser@email.com", "uniqueUser@email.com"],
      "tags": ["test", "regression"],
      "custom_fields": {
        "my_custom_field": ["sample_value_1", "sample_value_2"],
        "test": ["a1", "a2"],
        "estimate": [10, 20]
      }
    }
  }
}

name String

Name of the test run.
description String

Brief information about the test run.
run_state String

State of the test run. The valid states are new_run, in_progress, under_review, rejected, done, and closed.
assignee String

Email of the test run assignee.
test_case_assignee String

Email of the test case assignee.
Show 8 more
tags Array

Descriptive labels or keywords linked to the test run.
issues Array

List of the linked Jira issues.
configurations Array

Combination of operating system, browser, and device.
test_plan_id String

Identifier of the test plan.
test_cases Array

List of test case IDs.
folder_ids Array

Identifiers of each folder.
include_all Boolean

If the value is true, all test cases in the project are added to the test run.
filter_test_cases Object

Use this object if you want to filter test cases before appending to the test run.

▶ SHOW VALUES
- status Array
  
  Indicates the status of the test case.
- priority Array
  
  Priority of the test case.
- case_type Array
  
  Type of test case.
- owner Array
  
  Email of the owner of test case.
- tags Array
  
  Descriptive labels or keywords linked to the test case.
- custom_fields Object
  
  Contains custom field names as keys and their corresponding values as lists.

Response Attributes `200 OK` `json`

Response

{
  "success": true,
  "testrun": {
      "active_state": "active",
      "run_state": "new_run",
      "created_at": "2023-11-29T06:26:22.215Z",
      "description": "check the performance of the test run",
      "identifier": "TR-78527",
      "name": "Test Run-29/11/2023",
      "assignee": "john@email.com",
      "project_id": "PR-1",
      "tags": ["performance"],
      "test_cases_count": 1,
      "updated_at": "2023-11-29T06:26:22.215Z",
      }
  }

success Boolean

API call is executed successfully.
active_state String

State of the test run.
run_state String

State of the test run. The valid states are new_run, in_progress, under_review, rejected, done, and closed.
created_at String

The time at which the test run was created on BrowserStack servers.
description String

Brief information about the test run.
Show 7 more
Identifier String

Identifier of the test run.
name String

Name of the test run.
assignee String

Email of the test run assignee.
project_id String

Identifier of the Project.
tags Array

Descriptive labels or keywords linked to the test run.
test_cases_count Integer

Count of number of test cases.
updated_at String

The time at which the test run was updated on BrowserStack servers.

Get test run details

GET /api/v2/projects/{project_id}/test-runs/{test_run_id}

Invoking this API will fetch the details of test cases linked to a test run. You will need the id of the project and id of the test run to access the details of test cases. The sample request has PR-1 and TR-78527 as placeholders representing project ID and test run ID, respectively.

This list is paginated; for more information, refer Pagination.

Request Parameters

Request

curl -u "YOUR_USERNAME:YOUR_ACCESS_KEY" \
https://test-management.browserstack.com/api/v2/projects/PR-1/test-runs/TR-78527

project_id^* String

Identifier of the project.
test_run_id^* String

Identifier of the test run.

Response Attributes `200 OK` `json`

Response

{
  "success": true,
  "test_run": {
    "active_state": "active",
    "run_state": "new_run",
    "created_at": "2023-11-29T06:26:22.215Z",
    "description": "",
    "identifier": "TR-78527",
    "name": "Test Run-29/11/2023",
    "assignee": "john@email.com",
    "project_id": "PR-1",
    "test_cases": [
      {
        "assignee": "john@email.com",
        "case_type": "other",
        "priority": "High",
        "status": "Active",
        "description": "",
        "identifier": "TC-1",
        "name": "Assign tags to user and then re-open the modal",
        "latest_status": "Passed",
        "latest_result_id": 108767
      },
      ...
    ],
    "links": {
      "test_cases": "/api/v2/projects/PR-1/test-runs/TR-78527/test-cases"
    },
    "tags": [
      "ttt"
    ],
    "test_cases_count": 1,
    "updated_at": "2023-11-29T06:26:22.215Z",
  }
}

active_state String

State of the test run.
run_state String

State of the test run. The valid states are new_run, in_progress, under_review, rejected, done, and closed.
created_at String

The time the test run was created on BrowserStack servers.
description String

Brief information about the test run.
Identifier String

Identifier of the test run.
Show 7 more
name String

Name of the test run.
assignee String

Email of the test run assignee.
project_id String

Identifier of the project.
test_cases Array

This list has information about a specific test case.

▶ SHOW VALUES
- assignee String
  
  Email of the test run assignee.
- case_type String
  
  Gives the type of test case.
- priority String
  
  Gives the priority of the test case.
- status String
  
  Gives the state of the test case.
- description String
  
  Brief information about the test case.
- name String
  
  Gives the title of the test case.
- latest_status String
  
  Gives the status of the test case.
- latest_result_id integer
  
  The latest result id of the test case in the run.
links String

Give the api endpoint url of the test case.
tags Array

Descriptive labels or keywords linked to the test case.
test_cases_count Integer

Count of number of test cases.

Get test cases of a test run

GET /api/v2/projects/{project_id}/test-runs/{test_run_id}/test-cases

Invoking this API will fetch the details of all the test cases linked to a test run. You will need the id of the project and id of the test run to access the details of test cases. Using this endpoint, you can retrieve the first thirty test cases. This list is paginated; for more information, refer Pagination.

The sample request has PR-1 and TR-78527 as placeholders representing project ID and test run ID, respectively.

Request Parameters

Request

curl -u "YOUR_USERNAME:YOUR_ACCESS_KEY" \
https://test-management.browserstack.com/api/v2/projects/PR-1/test-runs/TR-78527/test-cases?p=1

project_id^* String

Identifier of the project.
test_run_id^* String

Identifier of the test run.

Response Attributes `200 OK` `json`

Response

{
  "success": true,
  "info": {
    "page": 1,
    "page_size": 30,
    "count": 329,
    "prev": null,
    "next": 2
  },
  "test_cases": [
    {
      "case_type": "Acceptance",
      "priority": "Low",
      "status": "Active",
      "description": "test case description of verify location access",
      "identifier": "TC-391693",
      "name": "Assign tags to user and then re-open the modal",
      "latest_status": "skipped",
      "assignee": "john@email.com",
      "folder_path": [
        3818546,
        3818547,
        3818548,
        3818549,
        3818550,
        3818551,
        3823110
      ]
    }
  ]
}

success Boolean

API call is executed successfully.
info Object

Additional pagination information.

▶ SHOW VALUES
- page Integer
  
  The current page being viewed displays a list of test cases.
- page_size Integer
  
  Number of test cases in the page.
- count Integer
  
  Total number of records across all pages.
- prev Integer
  
  Previous page number.
- next Integer
  
  Next page number.
test_cases Array

This list has information about a specific test case.

▶ SHOW VALUES
- case_type String
  
  Gives the type of test case.
- priority String
  
  Gives the priority of the test case.
- status String
  
  Gives the state of the test case.
- description String
  
  Brief information about the test case.
- identifier String
  
  Brief information about the test case.
- name String
  
  Gives the title of the test case.
- latest_status String
  
  Gives the status of the test case.
- assignee String
  
  Email of the test run assignee.
- folder_path Array
  
  It is a list of test case folder IDs, starting with the root folder at the top and ending with the last folder at the bottom.

Update a test run

POST /api/v2/projects/{project_id}/test-runs/{test_run_id}/update

Invoking this API allows you to update test runs in a given project. When you update the test run, the new test cases in the update test run request will replace all the existing test cases. To update a test run, you will need both the id of the project and the id of the test run within that project.

Request Parameters

Request

curl -u "YOUR_USERNAME:YOUR_ACCESS_KEY" \
-X POST https://test-management.browserstack.com/api/v2/projects/{project_id}/test-runs/{test_run_id}/update

project_id^* String

Identifier of the project.
test_run_id^* String

Identifier of the test run.

Request Body

Request Body

{
  "test_run": {
    "name": "Test Run-29/11/2023",
    "description": "gas",
    "run_state": "new_run",
    "assignee": "john@email.com",
    "test_case_assignee": "john@email.com"
    "tags": [
      "ttt"
    ],
    "issues": [
      "XYZ-1"
    ],
    "test_plan_id" : "TP-20",
    "configurations": []
    "test_cases": ["TC-1", "TC-3"],
    "folder_ids": [34,54,64]
  }
}

name String

Name of the test run.
description String

Brief information about the test run.
run_state String

State of the test run. The valid states are new_run, in_progress, under_review, rejected, done, and closed.
assignee String

Email of the test run assignee.
test_case_assignee String

Email of the test case assignee.
Show 6 more
tags Array

Descriptive labels or keywords linked to the test run.
issues Array

List of the linked Jira issues.
test_plan_id String

Identifier of the test plan.
configurations Array

Combination of operating system, browser, and device.
test_cases Array

List of test case IDs.
folder_ids Array

Identifiers of each folder.

Response Attributes `200 OK` `json`

Response

{
  "success": true,
  "testrun": {
    "active_state": "active",
    "run_state": "new_run",
    "created_at": "2023-11-29T06:26:22.215Z",
    "description": "gas",
    "identifier": "TR-78527",
    "name": "Test Run-29/11/2023",
    "assignee": "john@email.com",
    "project_id": "PR-1",
    "test_plan": {
      "identifier": "TP-20",
      "name": "Test plan6"
    },
    "tags": [
      "ttt"
    ],
    "issues": [
      "XYZ-1"
    ],
    "test_cases_count": 2,
    "updated_at": "2023-11-29T06:26:22.215Z"
  }
}

success Boolean

API call is executed successfully.
active_state String

State of the test run.
run_state String

State of the test run. The valid states are new_run, in_progress, under_review, rejected, done, and closed.
created_at String

The time at which the test run was created on BrowserStack servers.
description String

Brief information about the test run.
Show 9 more
Identifier String

Identifier of the test run.
name String

Name of the test run.
assignee String

Email of the test run assignee.
project_id String

Identifier of the Project.
test_plan JSON Object

This list has information about a specific test plan.

▶ SHOW VALUES
- identifier String
  
  Identifier of the test plan.
- name String
  
  Name of the test plan.
tags Array

Descriptive labels or keywords linked to the test run.
issues Array

List of the linked Jira issues.
test_cases_count Integer

Count of number of test cases.
updated_at String

The time at which the test run was updated on BrowserStack servers.

Update assignee of test cases within a test run

POST /api/v2/projects/PR-5512/test-runs/TR-126509/assign

Invoking this API will update assignees of test cases within a test run. To do so, you will need the id of the project, the id of the test run, the id of test cases, and the email of assignees.

Request Parameters

Request

curl -u "YOUR_USERNAME:YOUR_ACCESS_KEY" \
-X POST https://test-management.browserstack.com/api/v2/projects/PR-5512/test-runs/TR-126509/assign

project_id^* String

Identifier of the project.
test_run_id^* String

Identifier of the test run.

Request Body

Request Body

{
  "assign_to": [
    {
      "test_case_id": "TC-337204",
      "configuration_id": 2,
      "assignee": "john@email.com"
    },
    {
      "test_case_id": "TC-337205",
      "configuration_id": 1,
      "assignee": "randomUser@email.com"
    },
    {
      "test_case_id": "TC-337203",
      "configuration_id": 1,
      "assignee": "uniqueUser@email.com"
    }
  ]
}

test_cases_id^* String

Test case ID whose assignee should be updated.
configuration_id Integer

Unique identifier for a specific operating system, browser, and device configuration. This optional parameter is required only if a test run includes configurations.
assignee^* String

Email of the assignee.

Response Attributes `200 OK` `json`

Response

{
    "success": true
}

success Boolean

API call is executed successfully.

Close a test run

POST /api/v2/projects/{project_id}/test-runs/{test_run_id}/close

Invoking this API will close test runs in a given project. To close a test run, you will need the id of test run and id of the project in which the test run exists.

Request Parameters

Request

curl -u "YOUR_USERNAME:YOUR_ACCESS_KEY" \
-X POST https://test-management.browserstack.com/api/v2/projects/PR-13/test-runs/TR-128/close

project_id^* String

Identifier of the project.
test_run_id^* String

Identifier of the test run.

Response Attributes `200 OK` `json`

Response

{
  "success": true,
  "testrun": {
    "active_state": "closed",
    "run_state": "closed",
    "created_at": "2023-12-21T09:03:10.000Z",
    "description": "Login functionality under user load",
    "identifier": "TR-128",
    "name": "Test Run-05/12/2023",
    "assignee": "john@email.com",
    "project_id": "PR-13",
    "test_cases_count": 0
  }
}

active_state String

State of the test run.
run_state String

State of the test run. The valid states are new_run, in_progress, under_review, rejected, done, and closed.
created_at String

The time the test run was created on BrowserStack servers.
description String

Brief information about the test run.
Identifier String

Identifier of the test run.
Show 4 more
name String

Name of the test run.
owner String

Email of the test run owner.
project_id String

Identifier of the project.
test_cases_count Integer

Count of number of test cases.

Delete a test run

POST /api/v2/projects/{project_id}/test-runs/{test_run_id}/delete

Invoking this API will delete a test run. You will need the id of the project and id of the test run to delete a test run.

Request Parameters

Request

curl -u "YOUR_USERNAME:YOUR_ACCESS_KEY" \
-X POST https://test-management.browserstack.com/api/v2/projects/PR-1/test-runs/TR-1234/delete

project_id^* String

Identifier of the project.
test_run_id^* String

Identifier of the test run.

Response Attributes `200 OK` `json`

Response

{
    "success": true,
    "message": "Test Run TR-1234 has been deleted successfully"
}

success Boolean

API call is executed successfully.
message String

Gives the information about the performed action.

Did this page help you?

We're sorry to hear that. Please share your feedback so we can do better

Contact our Support team for immediate help while we work on improving our docs.

We're continuously improving our docs. We'd love to know what you liked

This page has exactly what I am looking for
This content & code samples are accurate and up-to-date
The content on this page is easy to understand
Other (please tell us more below)

Any additional feedback?

Thank you for your valuable feedback

Test runs

Get test runs list

Request Parameters

project_id* String

Response Attributes 200 OK json

active_state String

run_state String

assignee String

created_at String

Identifier String

name String

project_id String

test_cases_count Integer

Create a test run

Request Parameters

project_id* String

Request Body

name String

description String

run_state String

assignee String

test_case_assignee String

tags Array

issues Array

configurations Array

test_plan_id String

test_cases Array

folder_ids Array

include_all Boolean

filter_test_cases Object

status Array

priority Array

case_type Array

owner Array

tags Array

custom_fields Object

Response Attributes 200 OK json

success Boolean

active_state String

run_state String

created_at String

description String

Identifier String

name String

assignee String

project_id String

tags Array

test_cases_count Integer

updated_at String

Get test run details

Request Parameters

project_id* String

test_run_id* String

Response Attributes 200 OK json

active_state String

run_state String

created_at String

description String

Identifier String

name String

assignee String

project_id String

test_cases Array

assignee String

case_type String

priority String

status String

description String

name String

latest_status String

latest_result_id integer

links String

tags Array

test_cases_count Integer

Get test cases of a test run

Request Parameters

project_id* String

test_run_id* String

Response Attributes 200 OK json

success Boolean

project_id^* String

Response Attributes `200 OK` `json`

project_id^* String

Response Attributes `200 OK` `json`

project_id^* String

test_run_id^* String

Response Attributes `200 OK` `json`

project_id^* String

test_run_id^* String

Response Attributes `200 OK` `json`

project_id^* String

test_run_id^* String

Response Attributes `200 OK` `json`

project_id^* String

test_run_id^* String

test_cases_id^* String

assignee^* String

Response Attributes `200 OK` `json`

project_id^* String

test_run_id^* String

Response Attributes `200 OK` `json`