Skip to main content
Table of Contents

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 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.

  • 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.

  • 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"
      },
      ...
    ],
    "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.

  • 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.

  • 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 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.

  • 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.

  • 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 https://test-management.browserstack.com/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" \
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.

Add test result to test run

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

Invoking this API allows you to add test results to test runs in a given project. To add a test result to a specific 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}/results
  • project_id* String

    Identifier of the project.

  • test_run_id* String

    Identifier of the test run.

Request Body

Request Body

{
  "test_result": {
    "status": "passed",
    "description": "Login functionality under high user load",
    "issues": [
      "TR-2",
      "XYZ-2"
    ],
    "custom_fields": {
      "custom_fields_name": "value"
    }
  },
  "test_case_id": "TC-13",
  "configuration_id": 116
}
  • status* String

    The status field is mandatory. Use either a system value (e.g., ”Passed,” “Failed,” etc.) or a custom value defined in Test Management. Attempting to define new status values via this API will result in an error response.

  • description String

    Brief information about the test run.

  • issues Array

    List of the linked Jira issues.

  • custom_fields Object

    List of the custom fields and their corresponding values.

  • test_case_id* String

    Identifier of each test case.

  • configurations_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.

Response Attributes 200 OK json

Response


{
  "success": true,
  "test-result": {
    "id": 66782871,
    "created_at": "2023-11-29T06:30:36.000Z",
    "description": "Test passed successfully, but with some issues noted",
    "status": "passed",
    "issues": [
      "TR-2",
      "XYZ-2"
    ]
  }
}
  • success Boolean

    API call is executed successfully.

  • id Integer

    Identifier for the test result.

  • created_at String

    Tht time at which the test result was created on BrowserStack servers.

  • status String

    Gives the status of the test result.

  • description String

    Brief information about the Test Run.

  • issues Array

    List of the linked Jira issues.

Add multiple test results in a test run

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

Invoking this API allows you to add multiple test results in a test run in a given project. To do so, you will need the id of the project, the id of the test run within that project, status of the test result and the id of the test case.

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}/results
  • project_id* String

    Identifier of the project.

  • test_run_id* String

    Identifier of the test run.

Request Body

Request Body

{
  "results": [
    {
      "test_result": {
        "status": "passed",
        "description": "Login functionality under high user load",
        "issues": [
          "TR-2",
          "XYZ-2"
        ],
        "custom_fields": {
          "custom_fields_name": "value"
        }
      },
      "test_case_id": "TC-337204",
      "configuration_id": 116
    },
    {
      "test_result": {
        "status": "skipped",
        "description": "Sensitive data is masked or encrypted",
        "issues": [
          "TR-23",
          "XYZ-27"
        ],
        "custom_fields": {
          "custom_fields_name": "value"
        }
      },
      "test_case_id": "TC-337205",
      "configuration_id": 126
    },
    ...
  ]
}
  • test_result Object

    This list has information about test results.

    SHOW VALUES
    • status* String

      The status field is mandatory. Use either a system value (e.g., ”Passed,” “Failed,” etc.) or a custom value defined in Test Management. Attempting to define new status values via this API will not record those statuses.

    • description String

      Brief information/notes about the test result.

    • issues Array

      List of the linked Jira issues.

    • custom_fields Object

      List of the custom fields and their corresponding values.

  • test_case_id* String

    Identifier of each test case.

  • 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.

Response Attributes 200 OK json

Response


{
    "success": true
}
  • success Boolean

    API call is executed successfully.

Close 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.

  • 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 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" \
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.

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






Thank you for your valuable feedback