How to Manage Test Cases with BrowserStack Test Management

To manage test cases in BrowserStack Test Management, create a project for an application or feature, organize cases into folders, choose a consistent case template, and write each scenario with enough detail for another person to execute it. Use fields such as owner, priority, type, automation status, tags, and linked requirements to make cases searchable. Keep the repository current by editing, moving, reusing, archiving, or importing cases as the product changes.

BrowserStack describes projects as the top-level containers for related test cases, test runs, test plans, reports, and project insights. Folders help organize cases within a project; metadata helps teams filter and triage them. The exact interface and available options can change, so check the BrowserStack Test Management documentation for current details.

1. Set up a project and folder structure

Start with a project whose scope is clear to the whole team, such as an application, product area, or feature with its own testing lifecycle. Add a short description so that new contributors can tell what belongs there. A project includes sections for test cases, runs, plans, reports, and insights.

Create a project in Test Management and give it a specific name and description.
Create folders around useful product or testing boundaries, such as Checkout, Account, or Regression.
Add subfolders only when the added level makes cases easier to browse. For example, a checkout folder might contain payment-method subfolders.
Keep names predictable. Agree on whether folder names represent product features, test types, or both before a repository grows.

Folders provide navigation and hierarchy; they are not a substitute for metadata. Use tags, case type, owner, priority, state, and automation status to support filtering and review. BrowserStack documents folder creation, nested folders, moving and editing folders, and folder case counts in its project and folder guide.

2. Choose a template that fits the scenario

BrowserStack documents three system templates: Text, Steps, and Gherkin (BDD). Choose based on how much structure the case needs and how your team communicates behavior.

Template	Use it when	Authoring pattern
Text	A short or relatively unstructured scenario is sufficient.	Describe the scenario, relevant setup, actions, and expected result in text.
Steps	Execution needs to be repeatable, or individual outcomes need to be clear.	Record each action with its corresponding expected result.
Gherkin (BDD)	The team expresses behavior in Given-When-Then form.	Describe the feature and one scenario per case.

There is no universally best template. Prefer the least complex format that still makes the test unambiguous. BrowserStack’s guide says a Gherkin test case supports one scenario, so create separate cases for distinct scenarios instead of combining them into one. Custom templates are also documented; availability and permissions can depend on the account plan. See Create test cases and Custom test case templates.

3. Write cases another person can execute

A useful test case makes the intended behavior and the pass condition clear without relying on the author’s memory. Include the following information as appropriate:

Title: State the behavior under test and, where useful, the important condition. For example, “Reject checkout when the payment card is expired.”
Scenario and scope: Explain what behavior is covered. Keep one independently meaningful outcome per case.
Preconditions: Record required account state, data, permissions, environment, or setup. Avoid putting hidden setup assumptions in the steps.
Steps: Give concrete actions in execution order. Avoid ambiguous directions such as “complete checkout.”
Expected result: State observable behavior, including validation messages or resulting state where relevant. With the Steps template, pair each action with its expected outcome.
Metadata: Set an owner, priority, type, automation status, tags, linked requirement, estimate, and state where they help the team find or plan the case.

Example using a Steps-style case

Title: Reject checkout when the payment card is expired
Precondition: The cart contains an in-stock item and checkout is available.

Step 1: Open checkout and enter an expired card number and valid billing details.
Expected result: The payment form accepts the field entries until submission.

Step 2: Submit the payment.
Expected result: The order is not placed, an expiration-related error is shown, and the cart remains available.

Priority: High
Type: Functional
Automation status: Not automated
Tags: checkout, payments, negative-case

Keep expected results testable: “the system works” is not a useful pass condition, while a visible error and an unchanged order state are. Avoid combining several unrelated assertions when a failure would make it unclear which behavior broke.

Example using Gherkin

Feature: Checkout payment validation
Scenario: An expired card is rejected
  Given the cart contains an in-stock item
  And the customer is on the payment step
  When the customer submits an expired card
  Then the order is not placed
  And an expiration-related error is displayed

Make each Gherkin case describe one scenario. If the same feature has valid-card, expired-card, and declined-card behavior, represent those as separate cases.

4. Use metadata and reuse without losing clarity

Consistent metadata makes a large repository easier to filter and maintain. Decide on a small shared vocabulary for tags and types. For instance, use stable tags for product area or risk, and avoid creating near-duplicates such as payments, payment, and pay for the same concept.

Owner: Identify who is responsible for reviewing or maintaining a case.
Priority: Use the same team definition of priority across projects.
Type: Classify the purpose, such as functional, acceptance, or regression, according to the categories enabled for your project.
Automation status: Distinguish automated, not automated, and other relevant states supported by your configuration.
Tags: Add useful filter terms, not a copy of every word from the title.
Requirements or issues: Link relevant work so teams can navigate between coverage and product requirements.
Estimate and state: Use where they help plan work and distinguish active, draft, or archived content.

BrowserStack also documents shared steps. Reuse them when repeated instructions would otherwise drift, but keep the test case’s unique setup and pass criteria explicit. Review the result after changing shared content because one edit can affect multiple cases.

5. Create, edit, and maintain cases

In the interface, create a case from the dashboard or within a folder, provide its title, choose a template, fill in the relevant details and metadata, then save it. After creation, treat the case as maintained documentation rather than a one-time artifact.

BrowserStack’s documented management activities include editing, deleting, copying, moving, exporting, filtering, shared steps, column preferences, and archiving or restoring cases. Use these actions with a clear maintenance policy:

Review on product changes. When a requirement, UI, or workflow changes, identify affected cases through links and tags.
Update steps and expected results together. A case with current actions and stale outcomes is misleading.
Copy when the new case is meaningfully different. Then remove copied assumptions and assign the correct metadata.
Move cases when ownership or organization changes. Avoid duplicating a case merely to make it appear in another folder.
Archive obsolete cases when history should remain available. Prefer archive over permanent deletion when the team may need the case later.
Export when a portable snapshot is needed. Confirm the format and included fields in the current interface.

See BrowserStack’s Manage test cases guide for the current interface actions.

6. Import existing cases carefully

BrowserStack documents project imports from TestRail and Zephyr Scale, as well as CSV import into an existing project. Its import materials also describe CSV and BDD feature-file workflows. Before a migration, inspect the current instructions for required columns, supported data, and mapping behavior; do a small representative import before moving the full repository.

Inventory the source. Identify projects, folders, templates, statuses, owners, tags, requirements, attachments, and duplicate cases.
Map fields. Decide where each source field belongs in the destination and record fields that will not transfer directly.
Normalize data. Standardize status labels, priorities, owner addresses, tags, and titles before import where possible.
Trial a small sample. Include ordinary cases and edge cases such as long descriptions, multiple steps, links, and missing optional values.
Validate after import. Compare case counts and inspect representative cases, links, formatting, and folder placement.
Plan cutover. Decide which system is authoritative during migration and how edits made during the transition will be reconciled.

The CSV/feature-file import guide specifies constraints such as file size and simultaneous file count that may affect a migration. Check the live CSV and feature-file import documentation before preparing files. Do not assume every source field or attachment will map identically.

7. Automate case administration with the API

Use the Test Management API when cases are generated from another system, need repeatable bulk creation, or must be audited in a script. The documented case endpoints require project and folder identifiers for creation. Authenticate with your BrowserStack username and access key; store credentials in environment variables or a secret manager, not in source control. Confirm current request schemas, enums, and limits in the API reference.

cURL: create a case

export BROWSERSTACK_USERNAME='YOUR_USERNAME'
export BROWSERSTACK_ACCESS_KEY='YOUR_ACCESS_KEY'
export PROJECT_ID='PR-1'
export FOLDER_ID='19590'

curl --fail-with-body --user "$BROWSERSTACK_USERNAME:$BROWSERSTACK_ACCESS_KEY" \
  --request POST \
  "https://test-management.browserstack.com/api/v2/projects/$PROJECT_ID/folders/$FOLDER_ID/test-cases" \
  --header 'Content-Type: application/json' \
  --data '{
    "test_case": {
      "name": "Reject checkout when the payment card is expired",
      "template": "test_case_steps",
      "priority": "High",
      "case_type": "Functional",
      "preconditions": "The cart contains an in-stock item.",
      "test_case_steps": [
        {"step": "Submit an expired card at checkout", "result": "The order is not placed and an expiration error is shown"}
      ],
      "tags": ["checkout", "payments"]
    }
  }'

The exact accepted fields and enum values depend on the current API schema and project configuration. Keep the payload aligned with the reference. This example uses the API’s documented endpoint and a representative case structure.

Python: create a case

import os
import requests

username = os.environ["BROWSERSTACK_USERNAME"]
access_key = os.environ["BROWSERSTACK_ACCESS_KEY"]
project_id = os.environ["PROJECT_ID"]
folder_id = os.environ["FOLDER_ID"]

url = (
    "https://test-management.browserstack.com/api/v2/projects/"
    f"{project_id}/folders/{folder_id}/test-cases"
)
payload = {
    "test_case": {
        "name": "Reject checkout when the payment card is expired",
        "template": "test_case_steps",
        "priority": "High",
        "case_type": "Functional",
        "preconditions": "The cart contains an in-stock item.",
        "test_case_steps": [
            {
                "step": "Submit an expired card at checkout",
                "result": "The order is not placed and an expiration error is shown",
            }
        ],
        "tags": ["checkout", "payments"],
    }
}

response = requests.post(
    url,
    auth=(username, access_key),
    json=payload,
    timeout=30,
)
response.raise_for_status()
print(response.json())

Node.js: create a case

const username = process.env.BROWSERSTACK_USERNAME;
const accessKey = process.env.BROWSERSTACK_ACCESS_KEY;
const projectId = process.env.PROJECT_ID;
const folderId = process.env.FOLDER_ID;

if (!username || !accessKey || !projectId || !folderId) {
  throw new Error('Set BrowserStack credentials, PROJECT_ID, and FOLDER_ID');
}

const credentials = Buffer.from(`${username}:${accessKey}`).toString('base64');
const url = `https://test-management.browserstack.com/api/v2/projects/${projectId}/folders/${folderId}/test-cases`;
const response = await fetch(url, {
  method: 'POST',
  headers: {
    Authorization: `Basic ${credentials}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    test_case: {
      name: 'Reject checkout when the payment card is expired',
      template: 'test_case_steps',
      priority: 'High',
      case_type: 'Functional',
      preconditions: 'The cart contains an in-stock item.',
      test_case_steps: [
        {
          step: 'Submit an expired card at checkout',
          result: 'The order is not placed and an expiration error is shown',
        },
      ],
      tags: ['checkout', 'payments'],
    },
  }),
});

const responseText = await response.text();
if (!response.ok) {
  throw new Error(`BrowserStack API ${response.status}: ${responseText}`);
}
console.log(responseText);

Bulk creation and safe retries

The API reference documents bulk creation at POST /api/v2/projects/{project_identifier}/folders/{folder_id}/test-cases/bulk. It accepts 1 to 10,000 cases per request; requests with 30 or fewer run synchronously, while larger requests return an asynchronous response with a unique ID to track. The reference says background processing proceeds in batches and continues even if a batch fails. Inspect the operation result and reconcile partial failures before retrying.

For a large import, split data into manageable chunks, retain a source-to-destination mapping, and log each request and response without logging secrets. Do not blindly retry a timed-out create request: the server may have created the case even if the client did not receive the response. First query or reconcile the result to avoid duplicates. For asynchronous bulk operations, follow the current API reference for tracking the returned ID and handling errors.

8. Connect cases to runs, plans, and reporting

A case repository describes scenarios and expected outcomes; execution is a related workflow. BrowserStack presents test cases alongside test runs, test plans, reports, and project insights. Keep case authoring distinct from run results: a case states what should be checked, while a run records an execution and its outcome. Link requirements and defects where supported so coverage and follow-up work can be navigated. Check current documentation and account configuration for integration details.

9. Troubleshooting common problems

Symptom	Likely cause	What to do
Case is difficult to find	Folder placement is unclear, or tags and fields are inconsistent.	Use a predictable folder scheme and shared metadata vocabulary; filter on owner, state, type, tags, or priority.
Different people execute the case differently	Steps omit setup, use vague actions, or lack observable expected results.	Add preconditions, precise actions, and explicit outcomes. Use the Steps template when per-step results matter.
BDD case covers several behaviors	Multiple scenarios were combined in one Gherkin case.	Split them into separate cases; BrowserStack documents one scenario per Gherkin test case.
Import rejects a file or fields appear missing	File format, size, columns, or field mapping does not match the current import requirements.	Review the live import guide, reduce the sample, validate headers and mappings, then retry with a small file.
API responds with an authorization error	Credentials are missing, incorrect, or not being sent with the expected authentication method.	Check the username and access key, Basic authentication, and account access. Keep credentials out of logs and code repositories.
API says project or folder was not found	An identifier is wrong or the folder does not belong to the selected project.	Confirm both identifiers against the account and use the folder inside that project.
API rejects a field or template	A field name, enum, or template identifier does not match the current schema.	Compare the request with the live API reference; validate values supported by the project.
Bulk operation does not return created cases immediately	More than 30 cases were sent, so the documented flow is asynchronous.	Save the returned unique ID, track the operation using the current reference, and review partial failures before retrying.
Updating one API field clears another	The update payload included a field without a value; the reference warns that such a field can be set to null.	Send only fields that need changing and omit all other fields from the update request.

10. Performance, reliability, and cost considerations

For teams, the main scaling costs are repository upkeep, import cleanup, and the time required to make cases consistently executable. A modest folder hierarchy, stable metadata, shared steps for genuinely repeated instructions, and clear ownership reduce search and maintenance overhead. Avoid creating a new tag or folder for every one-off variation.

For API workflows, respect documented bulk behavior, use bounded request sizes, handle non-success responses, and reconcile uncertain outcomes before retrying writes. Large bulk requests can complete asynchronously and may have partial failures, so retain input data and inspect results. Protect access keys as secrets. BrowserStack’s documentation describes the product workflows, but this guide makes no independent claim about execution speed, coverage improvement, service availability, or account pricing.

Or skip the browser setup

If you also need clean website screenshots for test evidence, page review, or automation workflows, ScreenshotNeo is a website screenshot API and MCP server. Its API takes a URL and returns an image or PDF; see the ScreenshotNeo API documentation.

curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webp

import requests
r = requests.get("https://api.screenshotneo.com/v1/shot", params={"access_key": "YOUR_API_KEY", "url": "https://stripe.com"}, timeout=90)
open("shot.webp", "wb").write(r.content)

const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://stripe.com' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);

Cookie banners are accepted and removed before capture; known consent platforms, newsletter popups, and chat widgets can also be removed.
Bot checks, blank pages, failed loads, timeouts, and cache hits are not billed; response headers report the page verdict and billing status.
An MCP server provides take_screenshot, get_page_info, and capture_pdf tools for Claude, Cursor, and other MCP clients.
1,000 screenshots per month are free with no card; paid plans start at $5 for 3,000 screenshots.

FAQ

Should every test case have an owner?

Assign an owner when someone needs to maintain or review the case. A clear owner is especially useful for cases tied to frequently changing features.

Should I archive or delete an obsolete case?

Archive it when the team may need its history or context. Delete only when permanent removal is intended; the API documentation warns that deletion cannot be undone.

Can test cases be created without the interface?

Yes. BrowserStack documents API endpoints for listing, creating, updating, and bulk creating cases. Check the current API reference for authentication, schema, and limits.

Does a test case prove that a requirement is covered?

A linked case can help trace a requirement to a validation scenario, but teams still need to review whether the scenario and its expected result adequately cover the requirement.