How to Use BrowserStack SDK with App Automate

To use BrowserStack SDK with App Automate, add the SDK integration for your test language and framework, configure credentials, your uploaded app, and target devices in browserstack.yml, then run the suite using that integration. The SDK connects the existing tests to BrowserStack and applies configuration at runtime. Choose the setup guide for your language and framework; there is no single install command that applies to every project.

This guide covers the shared configuration and run workflow. Use the official BrowserStack SDK overview and the relevant language and framework integration guide for current dependency and runner commands.

1. Choose the integration for your project

BrowserStack documents SDK integrations for Java, Node.js, C#, and Python, with framework examples including TestNG, WebdriverIO, NUnit, Pytest, JUnit, and Behave. Support depends on the specific language/framework combination, so confirm that exact pairing in the integration documentation before adding a dependency.

Identify the language and test runner already used by the suite.
Open the matching App Automate SDK integration guide.
Follow its install and runner instructions. Keep the project’s existing test assertions and organization unless that guide calls for an integration change.
Prepare an app upload and copy its BrowserStack app identifier, commonly formatted like bs://…, into the configuration.

The SDK guides provide language-specific package names and commands. Avoid copying an install command from a different framework: dependency names, configuration hooks, and launch commands differ.

2. Create browserstack.yml

Place browserstack.yml where the selected integration expects to find it, typically at the project root. The shared configuration below shows the important shape. Replace the sample values with your account credentials, uploaded app ID, and device targets.

userName: YOUR_BROWSERSTACK_USERNAME
accessKey: YOUR_BROWSERSTACK_ACCESS_KEY
framework: YOUR_SUPPORTED_FRAMEWORK
app: bs://YOUR_UPLOADED_APP_ID

platforms:
  - platformName: iOS
    deviceName: iPhone 14
    platformVersion: "16"
  - platformName: iOS
    deviceName: iPhone 13
    platformVersion: "15"

# Uncomment when the app or a test dependency needs a private network route.
# browserstackLocal: true

# Optional: number of parallel test threads on each platform.
# parallelsPerPlatform: 2

The device names and OS versions above are illustrative configuration values, not a promise that every device/version combination is currently available. Check the device list in your BrowserStack account and the current integration documentation. Protect credentials with your project’s secret-management mechanism; do not commit real access keys to a public repository.

Configuration fields

Field	Purpose	Notes
`userName`, `accessKey`	Authenticate the SDK with BrowserStack.	Supply secrets through protected configuration for your environment.
`framework`	Select the supported test framework integration.	Use the value and setup prescribed by the guide for your language/framework.
`app`	Identify the uploaded mobile app to install for the run.	Use the returned app identifier, such as a `bs://` ID.
`platforms`	List the device and OS combinations for the suite.	The suite runs on every listed platform. Platform-specific test selection belongs in test code.
`browserstackLocal`	Ask the SDK to manage BrowserStack Local for private resources.	Enable when tests need localhost or an internal development/staging endpoint.
`parallelsPerPlatform`	Set test threads per configured platform.	Actual concurrency depends on account entitlement and availability.

3. Put capabilities in the right place

BrowserStack recommends keeping capabilities in the configuration file. Root-level values apply across platforms; a value inside one platform entry can specialize that target. When a capability is set both in browserstack.yml and in test code, the configuration file takes precedence. This can explain why editing the test’s desired capabilities appears to have no effect. See How BrowserStack SDK works.

For example, App Automate capability examples include deviceOrientation for landscape runs and networkLogs: true for capturing network traffic and request/response details in HAR format. Add only settings your test needs and follow the exact naming and nesting expected by your integration:

platforms:
  - platformName: iOS
    deviceName: YOUR_DEVICE
    platformVersion: "YOUR_OS_VERSION"
    deviceOrientation: landscape
    networkLogs: true

Network logging is an opt-in diagnostic capability in this example; do not assume it is enabled by default. Consult the App Automate capabilities reference for available values and framework-specific formatting.

4. Run the suite through the SDK

After installing the integration and saving the configuration, run tests with the command or runner hook from the matching SDK guide. The exact command is intentionally language-specific. A successful setup should make the run appear in App Automate with the selected app and each configured target device.

Start with one platform to validate authentication, app selection, and test discovery.
Check the session in App Automate and inspect its logs if setup fails.
Add additional platform entries after the first target is stable.
Enable parallel threads separately when you need faster suite throughput and your account supports that concurrency.

5. Decide whether to use BrowserStack Local

Enable browserstackLocal: true when the app or test must reach localhost, a private API, or an internal development/staging service that is not publicly reachable. The SDK can manage the tunnel. BrowserStack also documents configurations involving an existing Local binary and local identifiers; follow those instructions when your network setup requires them. See App Automate Local testing.

If all test dependencies are publicly reachable, Local may not be needed. When a tunnel is required but the target is still unreachable, verify the Local setup and identifier against the project’s configuration before changing test logic.

6. Understand device coverage and parallelism

The platforms list controls which device combinations receive the suite. It does not map individual tests to individual platforms: by default, all tests run on every listed platform. If only some tests apply to a device or OS, handle that selection in the test scripts.

parallelsPerPlatform controls test threads per platform and is separate from the number of platform entries. BrowserStack’s example arithmetic is three configured platforms multiplied by two parallels per platform, for six parallel threads. That is configuration arithmetic, not a guarantee that a given account can run six sessions concurrently. Check your account’s concurrency allowance and available capacity.

7. Troubleshooting

Symptom	Likely cause	What to check
Authentication fails	Username or access key is missing, incorrect, or not reaching the runner.	Check secret injection and the values visible to the process without printing secrets into logs.
The wrong app launches or no app installs	The app field has a stale or malformed identifier.	Confirm the upload completed and use its exact returned app ID.
Tests run on unexpected devices	The platform list contains different targets than intended, or all tests are fanned out to every target.	Review each platform entry and add test-side filtering where only selected tests should run.
A capability change in code has no effect	The same capability is also defined in `browserstack.yml`, which takes precedence.	Update or remove the duplicate in the configuration file.
Private API or staging host is unreachable	BrowserStack Local is disabled or its setup does not match the network path.	Enable the SDK-managed tunnel or follow the documented existing-binary/local-identifier setup.
More sessions do not start concurrently	Configured parallelism exceeds account concurrency or current available capacity.	Reduce `parallelsPerPlatform` or confirm concurrency entitlement.
SDK cannot find tests or framework	The package or runner setup does not match the project’s language/framework integration.	Return to the exact integration guide and verify its dependency, config location, and invocation steps.
Network diagnosis lacks request details	Network logging was not enabled, or the capability is not configured in the integration’s expected format.	Set the documented network logging capability and inspect the session artifacts.

8. Performance, reliability, and cost considerations

Use a small target matrix while validating setup, then expand device coverage deliberately. More platform entries increase the number of device runs; more parallel threads increase requested concurrency. Neither setting alone guarantees a shorter wall-clock run because session availability and suite workload also matter. The cited setup documentation provides configuration guidance, not independent performance benchmarks.

For reliability, keep credentials outside source control, make app identifiers explicit, and ensure each target represents a device/OS combination available to the account. For private dependencies, validate the tunnel path early. Enable network logs when they help diagnose request behavior; extra diagnostic data is most useful when tied to a concrete issue.

Budget planning should account for the device coverage and concurrency your team needs, but consult your current BrowserStack plan and usage information for applicable limits and costs. The reviewed setup material does not establish a universal price or concurrency entitlement.

Or skip the browser setup

If you need screenshots of web pages rather than mobile app test sessions, ScreenshotNeo is a website screenshot API and MCP server for developers. One GET request returns a PNG, JPEG, WebP, or PDF. Its capture flow accepts cookie banners and removes more than 60 known consent platforms, newsletter popups, and chat widgets before the shot; each step can be turned off. Bot checks, blank pages, failed loads, timeouts, and cache hits are not billed, and response headers identify the page verdict and billing status. An MCP server provides take_screenshot, get_page_info, and capture_pdf for AI agents.

See the ScreenshotNeo API documentation. This runnable cURL example saves a WebP screenshot:

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

Python:

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)

Node.js:

const q = new URLSearchParams({
  access_key: 'YOUR_API_KEY',
  url: 'https://stripe.com'
});
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);
if (!res.ok) throw new Error(`Screenshot request failed: ${res.status}`);
await Bun.write('shot.webp', res);

Cookie banners, popups, and chat widgets are removed before the shot. Bot checks, blank pages, and failed loads are never billed. The MCP server lets AI agents take screenshots. The free plan includes 1,000 screenshots a month with no card; paid plans start at $5 for 3,000. Sign up for 1,000 free screenshots a month, no card required.

FAQ

Can I keep my existing Appium test scripts?

The SDK is designed to integrate at runtime and apply configuration without requiring test-script changes for the basic cloud connection. Follow the selected integration guide for any framework-specific setup.

Does a platform entry run only the tests meant for that device?

No. The configured suite runs on every listed platform unless the test scripts select or skip tests by platform.

Should I turn on network logs for every run?

Enable them when request and response evidence will help diagnose a test. They are an explicit capability in the documented example, not a default assumed by this guide.

Is ScreenshotNeo a replacement for App Automate?

No. App Automate runs mobile app tests on cloud devices; ScreenshotNeo captures web pages as image or PDF output.