Link automated test runs to a Test Plan

Pass a Test Plan ID from the BrowserStack SDK or from a report upload so BrowserStack links your automated test runs to a Test Plan for you.

A Test Plan groups the test runs that cover one release or one test cycle. To add an automated run to that plan, pass the plan’s ID at run time, from your SDK configuration or from your report upload. BrowserStack does the linking for you. You do not have to open Test Management and attach each run manually after every build.

Prerequisites

Before you start, make sure you have the following:

• A Test Plan in your Test Management project, and permission to edit it.
• Your BrowserStack username and access key.
• The BrowserStack SDK set up for your framework, or an existing report upload step in your pipeline.

Copy the Test Plan ID

In Test Management, go to Test Plans. Each plan carries a Test Plan ID in the form TP-98765. Copy the ID of the plan you want to link runs to.

Link runs to a sub-test plan

To link runs to a sub-test plan, copy its ID from the same Test Plans list. A sub-test plan ID looks like STP-522. Pass it in the same parameter, in place of the Test Plan ID. There is no separate parameter for sub-test plans. The run links to the sub-test plan, whose results roll up to the parent Test Plan.

All three methods on this page accept either ID.

Pass the Test Plan ID

There are three ways to pass a Test Plan ID. Find the row that matches how your test results reach BrowserStack, then open the method it names. The parameter name changes with the method.

Pass the ID from the BrowserStack SDK

The BrowserStack SDK sends the Test Plan ID with the build it starts. Support comes from the SDK itself, so it covers every test framework your SDK version runs. You set the ID in one of three places. Use whichever fits how you run your tests.

To set the ID for every run from a repository, add a testManagementOptions block to browserstack.yml:

Pass the ID in Nightwatch

Most frameworks read the Test Plan ID from browserstack.yml. A few keep their BrowserStack settings in their own config file instead. Nightwatch is one of them. For Nightwatch, set testManagementOptions inside the @nightwatch/browserstack plugin block in nightwatch.conf.js:

On Nightwatch, the environment variable and the command-line argument work the same way they do everywhere else.

Pass the ID when you upload a report to Test Reporting & Analytics

If your tests do not run through the SDK, upload your report the way you already do. Add one more form field to the request. Set testPlanId to your Test Plan ID:

-F "testPlanId=TP-98765"

Nothing else about the upload changes. For the full request and every other field it takes, see the Upload JUnit XML Reports API.

Pass the ID when you import a JUnit report into Test Management

When you import a JUnit XML report straight into Test Management, add the test_plan_id form field to the import request:

-F "test_plan_id=TP-98765"

For the full request and the frameworks this import covers, see JUnit XML or BDD-JSON based report upload.

Verify the link in Test Management

Run your tests, or upload your report. Then open the Test Plan in Test Management and check that the new run appears under it. The link is made after BrowserStack finishes processing the run, so the run might not appear the moment your build ends. Wait a few seconds and refresh the page.

Reasons a run is not linked to a Test Plan

A wrong or missing ID never fails your tests. Your results still reach BrowserStack. BrowserStack skips the link when any of the following is true:

• You did not pass a Test Plan ID.
• The Test Plan ID is invalid, or its format is wrong.
• The Test Plan ID does not exist in the project the run reports to.
• You do not have permission to edit that Test Plan.
• The Test Plan is not active.

In each case, BrowserStack creates the build without a Test Plan attached. Your test output stays clean. BrowserStack records why it skipped the link on the build in Test Reporting & Analytics. If a run does not appear under your plan, check that message. Correct the ID, then run your tests again.

Next steps

• Add Test Runs to Test Plan
• Automated test runs
• Create Sub-Test Plans