BrowserStack

BrowserStack App Automate is a popular cloud-based device farm that provides access to thousands of real mobile devices for testing. This guide shows you how to run Patrol tests on BrowserStack.

Overview

BrowserStack App Automate allows you to run your Patrol tests on real Android and iOS devices in the cloud. You can test across different device models, OS versions, and configurations without maintaining physical devices.

BrowserStack offers both real devices and emulators/simulators. For the most accurate testing, we recommend using real devices.

Prerequisites

Create BrowserStack account

Get your credentials

Retrieve your username and access key from BrowserStack’s account page.

Set environment variable

Export your credentials as an environment variable:

export BS_CREDENTIALS="YOUR_USERNAME:YOUR_ACCESS_KEY"

Add this to your shell profile (~/.zshrc or ~/.bashrc) to persist it:

echo 'export BS_CREDENTIALS="YOUR_USERNAME:YOUR_ACCESS_KEY"' >> ~/.zshrc
source ~/.zshrc

Setup for Android

Update test runner

Modify your app-level build.gradle or build.gradle.kts file to use the BrowserStack-specific test runner:

android {
  // ...
  defaultConfig {
    // ...
    testInstrumentationRunner "pl.leancode.patrol.BrowserstackPatrolJUnitRunner"
  }
  // ...
}

The BrowserstackPatrolJUnitRunner is a specialized test runner that integrates with BrowserStack’s infrastructure and provides better test reporting.

Sync Gradle

After making this change, sync your Gradle files:

cd android && ./gradlew --refresh-dependencies

That’s it for Android! You can now proceed to running tests.

Setup for iOS

Before configuring BrowserStack for iOS, you must complete the Setup for physical iOS devices guide.

BrowserStack requires tests to use Xcode test plans. Follow these steps to convert your project:

Open Xcode

Open your iOS project in Xcode:

open ios/Runner.xcworkspace

Edit the scheme

Click on the scheme selector in the toolbar and select Edit Scheme…

Convert to test plans

In the scheme editor:

Go to the Test tab
Click Convert to use Test Plans…

Create from scheme

Select Create from Scheme when prompted:

Name the test plan

Important: Name the test plan exactly “TestPlan” (case-sensitive) and save it to the project root: Rename to TestPlan

The test plan must be named “TestPlan” to work with the bs_ios script.

Make sure your project name is “Runner” and the scheme is named “Runner” - these are the default names for Flutter projects and are expected by BrowserStack.

Running Tests

You have two options for running tests on BrowserStack: using automated scripts (recommended) or manually via API.

Using Scripts (Recommended)
Manual API Usage

Install mobile-tools

LeanCode provides convenient scripts (bs_android and bs_ios) for scheduling test runs on BrowserStack. These scripts are part of the mobile-tools package.Install via Homebrew:

brew tap leancodepl/tools
brew install mobile-tools

After installation, reload your shell:

exec $SHELL

Configure environment variables

The scripts use the BS_CREDENTIALS environment variable that you set earlier. You can also configure optional variables:

# Required
export BS_CREDENTIALS="YOUR_USERNAME:YOUR_ACCESS_KEY"

# Optional
export BS_PROJECT="AwesomeApp"  # Project name in BrowserStack dashboard
export BS_ANDROID_DEVICES='["Google Pixel 4-10.0"]'  # Target devices

Run tests

The scripts forward all arguments to patrol build, so you can use all the same flags:

bs_android \
  --target integration_test/example_test.dart \
  --verbose \
  --dart-define 'API_KEY=your_key_here'

Example output

Here’s what a successful test execution looks like:

$ bs_android --target integration_test/app_test.dart
• Building apk with entrypoint test_bundle.dart...
✓ Completed building apk with entrypoint test_bundle.dart (11.0s)
  % Total    % Received % Xferd  Average Speed   Time    Time     Time  Current
                                 Dload  Upload   Total   Spent    Left  Speed
100 87.4M  100   235  100 87.4M      7  2857k  0:00:33  0:00:31  0:00:02 2052k
Uploaded app, url: bs://fb61a714e1a0c60e2578d940dad52b74da244d54
Uploaded test, url: bs://a715b1231d41ac627bd683f1b16c28476babd72e
{"message":"Success","build_id":"a30440db559fcab65554ab0273437f3bd45d761b"}
Scheduled test execution

The “Success” message means your test was scheduled successfully. You can view progress in the BrowserStack dashboard.

Manual workflow

If you prefer to use BrowserStack’s REST API directly, or if you’re integrating with a CI/CD system, follow these steps:

Build test artifacts

Build your app and test instrumentation app using Patrol:

patrol build android --target integration_test/example_test.dart

See the patrol build documentation for more options.

Upload app under test

Upload your app to BrowserStack:

curl -u "$BS_CREDENTIALS" \
  -X POST "https://api-cloud.browserstack.com/app-automate/espresso/v2/app" \
  -F "file=@build/app/outputs/apk/debug/app-debug.apk"

Response will contain an app_url like bs://abc123...

See BrowserStack docs: Android | iOS

Upload test suite

Upload your test instrumentation app:

curl -u "$BS_CREDENTIALS" \
  -X POST "https://api-cloud.browserstack.com/app-automate/espresso/v2/test-suite" \
  -F "file=@build/app/outputs/apk/androidTest/debug/app-debug-androidTest.apk"

Response will contain a test_suite_url like bs://def456...

See BrowserStack docs: Android | iOS

Execute tests

Start the test execution with your preferred device configuration:

curl -u "$BS_CREDENTIALS" \
  -X POST "https://api-cloud.browserstack.com/app-automate/espresso/v2/build" \
  -d '{"devices": ["Google Pixel 4-10.0"], "app": "bs://abc123...", "testSuite": "bs://def456...", "project": "MyProject"}' \
  -H "Content-Type: application/json"

See BrowserStack docs: Android | iOS

Viewing Results

After scheduling a test execution, view the results in the BrowserStack App Automate Dashboard. The dashboard provides:

Live test execution videos
Device logs
Network logs
Screenshots at each step
Crash reports
Performance metrics

Available Devices

To see all available devices and OS versions, check the BrowserStack Devices List. Popular device configurations:

Android Devices

[
  "Google Pixel 7 Pro-13.0",
  "Google Pixel 6-12.0",
  "Samsung Galaxy S23-13.0",
  "Samsung Galaxy S21-11.0",
  "OnePlus 9-11.0"
]

iOS Devices

[
  "iPhone 14 Pro-16",
  "iPhone 14-16",
  "iPhone 13-15",
  "iPhone 12-14",
  "iPad Pro 12.9 2022-16"
]

Best Practices

Use Real Devices

Always test on real devices rather than simulators for the most accurate results.

Target Popular Devices

Focus your testing on the most popular devices among your user base.

Organize with Projects

Use the BS_PROJECT environment variable to organize tests by project in the dashboard.

Review Videos

Always review test execution videos to understand failures quickly.

CI/CD Integration

Integrate BrowserStack into your CI/CD pipeline:

name: BrowserStack Tests

on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      
      - name: Setup Flutter
        uses: subosito/flutter-action@v2
        
      - name: Install mobile-tools
        run: |
          brew tap leancodepl/tools
          brew install mobile-tools
          
      - name: Run Android tests
        env:
          BS_CREDENTIALS: ${{ secrets.BS_CREDENTIALS }}
          BS_PROJECT: ${{ github.repository }}
        run: bs_android --target integration_test/app_test.dart

Troubleshooting

Authentication failed

Verify your credentials are correct:

echo $BS_CREDENTIALS

Make sure it’s in the format USERNAME:ACCESS_KEY with no extra spaces or quotes.

Device not available

The device you specified might not be available in your BrowserStack plan or might be busy. Check:

The devices list for correct device names
Your BrowserStack plan’s device access
Try a different device or wait and retry

Upload failed

If app upload fails:

Check that the APK/IPA file exists at the specified path
Ensure the file size is under BrowserStack’s limits (currently 4GB)
Verify your BrowserStack plan allows app uploads

Tests don't start

If tests are uploaded but don’t execute:

Verify you’re using the correct test runner (BrowserstackPatrolJUnitRunner for Android)
For iOS, ensure the test plan is named “TestPlan”
Check the BrowserStack dashboard for error messages

CI/CD

Integrations

Feature Guides

Best Practices

Overview

Prerequisites

Setup for Android

Setup for iOS

Running Tests

Install mobile-tools

Configure environment variables

Run tests

Example output

Manual workflow

Viewing Results

Available Devices

Best Practices

Use Real Devices

Target Popular Devices

Organize with Projects

Review Videos

CI/CD Integration

Troubleshooting

Next Steps

Firebase Test Lab

LambdaTest

Resources

Build docs developers (and LLMs) love

CI/CD

Integrations

Feature Guides

Best Practices

​Overview

​Prerequisites

​Setup for Android

​Setup for iOS

​Running Tests

​Install mobile-tools

​Configure environment variables

​Run tests

​Example output

​Manual workflow

​Viewing Results

​Available Devices

​Best Practices

Use Real Devices

Target Popular Devices

Organize with Projects

Review Videos

​CI/CD Integration

​Troubleshooting

​Next Steps

Firebase Test Lab

LambdaTest

​Resources

Build docs developers (and LLMs) love

Overview

Prerequisites

Setup for Android

Setup for iOS

Running Tests

Install mobile-tools

Configure environment variables

Run tests

Example output

Manual workflow

Viewing Results

Available Devices

Best Practices

CI/CD Integration

Troubleshooting

Next Steps

Resources