🚀 Self Healing AI Agent now live in App Automate! Auto-fix flaky tests instantly with zero code changes. Enable now!
No Result Found
Get your setup working faster. Join our Discord for optimisation tips from elite testers. Join our DiscordJoin our Discord

Integrate Your Test Suite with BrowserStack

BrowserStack’s Appium TestNG SDK supports a plug-and-play integration. Run your entire appium based automated test suite in parallel with a few steps!

Ready to integrate your existing Java Appium test suite with BrowserStack? This document walks you through the simple steps to connect your tests to our cloud infrastructure and start running them on real devices. You’ll learn how to configure your environment, upload your app, and execute tests seamlessly on BrowserStack’s device cloud.

Prerequisites

  • An existing appium based automated test suite.
  • Ensure you’re using Java v8+. If using Gradle, Java v9+ is required.
  • Maven is installed on your machine, its environment variables are set, and its bin is added to system path, $PATH(This is only applicable to mac/linux systems).

Looking for a starter project? Get started with our TestNG sample project.

Integration steps

Based on the method you use to build your project, complete the steps in the following tabs to integrate with BrowserStack.

Install BrowserStack Plugin

On the Eclipse toolbar, click Help > Eclipse Marketplace.

In the Eclipse Marketplace, search for BrowserStack > click Install > Finish. Search for BrowserStack plugin

Upload app

Upload your Android (.apk) or iOS (.ipa) apps to BrowserStack servers using one of the following ways:


On the App Automate dashboard, click the Upload button on the top-right corner. Select the app you want to upload from your filesystem.

Screenshot showing the Upload button in the top-right corner of the App Automate Dashboard

To upload an app using the App Management UI, follow the steps below:

  1. Navigate to App Automate dashboard, on the sidebar, click App Management.

  2. On the App Management UI, click Upload App.

  3. Select the app you want to upload from your filesystem. If you are uploading the app using a public URL, paste the URL of your app in the or upload from URL box.

  4. After selecting the app, choose the App Automate framework you want to use for testing. You can optionally add flags and a custom ID.

  5. Click Upload. The app is uploaded to the BrowserStack servers. You’ll receive an App ID, which you can use to run tests.

Screenshot of the App Management UI showing the app upload interface with options to select from filesystem or enter URL

To manage your apps, refer to the documentation on managing apps using App Management UI.

To upload an app using filesystem/public URL via the REST API, use the cURL example:

Terminal
Copy icon Copy

Facing issues with app upload? Visit the Troubleshooting section at the bottom of this page.

Configure your test suite with BrowserStack SDK

BrowserStack plugin automatically adds the browserstack-java-sdk dependency to your pom.xml file and generates a browserstack.yml configuration file.

Right-click on your project folder > BrowserStack > select Integrate with App Automate SDK. Screenshot showing the navigation from the project folder to BrowserStack to the Integrate with BrowserStack SDK option

Select your Project Folder, Framework, and other BrowserStack Parameters, and then click Integrate.

Framework: testng
BrowserStack User Name: YOUR_USERNAME
BrowserStack Access Key: YOUR_ACCESS_KEY

Screenshot showing the Integrate with BrowserStack SDK screen with parameters filled in

Update your BrowserStack config file

After installing the SDK, create a browserstack.yml config file at the root level of your project. This file holds all the required capabilities to run tests on BrowserStack.

Set app to be tested

The app property determines the app to be tested. You can upload an Android app (.apk, .aab, or .xapk file) or an iOS app (.ipa file) from your local filesystem.

Supported method Description
path(Recommended) SDK uploads the app using the specified relative or absolute path.
Eg: app: ./SampleApp.apk.
Note: Check out how to create IPA files for iOS app testing on BrowserStack.
App

Set the path to your app. Or, if you have already uploaded your app, provide one of the other acceptable app property values here

You can use BrowserStack REST API to upload your app.

Following is a sample response that is generated when you upload an app using any of the mentioned methods:

 {
    "app_url":"bs://f7c874f21852ba57957a3fdc33f47514288c4ba4", 
    "custom_id":"SampleApp"
 }

The following table explains the other acceptable app property values:

Supported method Description
app_url Uploaded app’s app_url is a valid value for app property.
Eg: app: bs://45e1c1473b17b7643aed1761f51cb5cdf3d3e334
custom_id If you’ve defined a custom_id while uploading your app, the same value can be used as app property value.
Eg: app: CalculatorApp

Check out how to specify the application under test to understand the above options better.

Set platforms to test on

Platform

Select an OS to choose the devices from below

Set the devices you want to test under the platforms object.

Parallel thread #1
Parallel thread #2
Parallel thread #3

To dynamically configure platforms across different tests, you can comment out the platforms capability while still passing platform-specific capabilities.

Set number of parallel threads per platform

The parallelsPerPlatform property determines the number of parallel threads to be executed. BrowserStack’s SDK runner will select the best strategy based on the configured value.

Example 1: If you have configured 3 platforms and set parallelsPerPlatform as 2: a total of 6 (3 x 2) parallel threads will be used on BrowserStack.

Example 2: If you have configured 1 platform and set parallelsPerPlatform as 15: a total of 15 (1 x 15) parallel threads will be used on BrowserStack.

Remove the parallelsPerPlatform capability from the configuration file.

Remove or comment out the platform capability while keeping the parallelsPerPlatform capability intact in the configuration file.

Remove or comment out the platform and parallelsPerPlatform capabilities from the configuration file.

BrowserStack Reporting

You can leverage BrowserStack’s extensive reporting features using the following capabilities:

Build Name

Set a name to your build (usually the same as the build ID that’s on your CI/CD platform).
Accepted characters: A-Z, a-z, 0-9, ., :, -, [], /, @, &, ', _. All other characters are ignored.
Character limit: 255


Project Name

Set a project name for your project

The projectName and buildName config must be static and not change across different runs of the same build. This is a deviation in approach as specified by BrowserStack Automate or App Automate as Test Reporting & Analytics will automatically identify different build runs.

Restrict the characters in your projectName and buildName to alphanumeric characters (A-Z, a-z, 0-9), underscores (_), colons (:), square brackets ([, ]), and hyphens (-). Any other character will be replaced with an underscore (_).

The sessionName and sessionStatus are the names of your test sessions and status of your test sessions respectively. They are automatically picked from your test class/spec names and statuses. They do not need to be set manually when using the BrowserStack SDK. To override the sessionName and sessionStatus capabilities, use the following in your browserstack.yml file:

You can configure local testing to start without initializing the BrowserStack binary, or even with an existing binary using a local identifier

testContextOptions:
    skipSessionName: true
    skipSessionStatus: true

Enable additional features

To enhance your testing experience on BrowserStack, you can enable additional features such as Local Testing, debugging features, visual testing, and accessibility testing by adding the respective capabilities in your browserstack.yml file.

Enable BrowserStack Local

Test apps with local/staging api servers

True
False
Test apps locally with local/staging api servers

BrowserStack’s Local Testing feature connects with locally hosted api servers to run your apps

Learn more

BrowserStack Local supports all advanced use cases and restricted networks. Contact our support team for assistance in configuring BrowserStack Local for your enterprise.

Use additional debugging features

By default, BrowserStack provides prettified session logs, screenshots on every failed command, and a video of the entire test. Additionally, you can enable the following features:

Visual logs

Enables screenshots for every command ran

True
False
Network logs

Enables network capture for the session in HAR format. Reduces session performance slightly

True
False

Use App Percy Visual Testing

App Percy is an all-in-one visual testing and review platform enabling teams to automate visual tests, detect visual bugs, and provide valuable insights into UI changes.

Percy Visual Testing

Enable visual testing to automatically identify and highlight visual UI changes.

Note: Using App Percy to perform Visual testing affects the performance of your App Automate tests.

True
False
Percy Capture Mode

Select a capture mode for your visual testing.

percyCaptureMode takes effect only if you set percy to true. If you set the capture mode to manual, ensure you use the Percy Screenshot function in your test script.

Use App Accessibility Testing

App Accessibility evaluates and reports app accessibility issues through comprehensive testing and reporting on real devices, ensuring compliance and reaching a wider audience.

App Accessibility Testing

Enable accessibility testing to automatically identify and highlight accessibility issues with your app.

Note: Using App Accessibility testing affects the performance of your App Automate tests.

True
False

Update browserstack.yml file

Update browserstack.yml file in the root folder of your test suite and add the adjacent code to it.

browserstack.yml
Copy icon Copy

Use our Capability Generator to select from a comprehensive set of options you can use to customize your tests.

Run your test suite

You can continue running your tests as you have been previously.

To find out the location of the BrowserStack SDK log files, refer to BrowserStack SDK Log Files. If you are looking for more information, see FAQ documentation.

Facing issues with your project? Try running a sample build here.

Advanced features and use cases

Here’s a list of features and capabilities you may find useful.

The acceptInsecureCerts capability suppresses warning about self-signed certificates usually found in staging environments.

Capability Expected values
acceptInsecureCerts A boolean. Default is False.
True if you want to accept all SSL certificates.
browserstack.yml
Copy icon Copy

The deviceOrientation capability changes the default mobile screen orientation for your tests on BrowserStack infra.

  • If the parameter is set at the root level, its applicable to all the devices in the test.
  • If you wish to apply it to a specific device, set it at the platform level which has the device details.
Capability Description Expected values
deviceOrientation Set the orientation of your app before beginning your test A string. Default orientation is portrait.

Supported orientations:
portrait and landscape.
browserstack.yml
Copy icon Copy

The geoLocation capability lets you test your app across different countries.

Note that this capability is supported on the Enterprise plan only. You can contact sales to get an Enterprise plan for your account.

Capability Description Expected values
geoLocation Set the country code you want your test to detect A string. An ISO 2 country code

FR for France,
CN for China

Check out the complete list of 45+ countries we support.
browserstack.yml
Copy icon Copy

The networkProfile capability lets you test your app under different network conditions.

Capability Description Expected values
networkProfile Set the network profile to start the test with A string.

2g-gprs-good, 4g-lte-advanced-lossy

Check out the complete list of all pre-defined network profiles under device features section.
browserstack.yml
Copy icon Copy

Following are a few additional links to documentation pages that might help with your test scenarios:

Troubleshooting

Here’s a list of troubleshooting options you may find useful.

When you upload your app to BrowserStack, make sure that the app file and its path or URL are valid. If you see an error during app upload, first check the following:

  • The file path is correct and the app file exists on your machine.
  • The app URL is publicly accessible and not behind a firewall or authentication.
  • The app file type is supported by BrowserStack. You can upload your app from the App Automate dashboard, App Management UI, or by using the REST API. For detailed information on uploading and managing apps, refer to Uploading and managing apps.

If you face errors related to invalid device OS combinations, ensure that the device and OS version combinations you are trying to run your tests on are supported on BrowserStack.

  • Uploading an unsigned version of an Android app will require us to sign it with our certificates before installing it on our devices. In the same manner, any uploaded .aab files will be converted into a universal APK and signed with our certificates.

  • If BrowserStack resigns the apps, third-party library integrations such as Google Firebase services, Google Maps SDK, Facebook SDK, etc., may not function properly if the use of API keys is restricted based on the SHA-1 certificate fingerprint of the app’s signing key.

  • To prevent this issue, it’s recommended to sign the APK with your own certificates before uploading it to BrowserStack.

  • If you upload an iOS app, we will re-sign the app with our own provisioning profile to be able to install your app on our devices during test execution.
  • However, if your app is signed using the Apple Developer Enterprise Program, you can disable this behavior to test features such as push notifications on BrowserStack devices.
Capability Expected values
resignApp A boolean. To disable re-signing, set the browserstack.resignApp capability to false in your Appium test scripts.
browserstack.yml
Copy icon Copy

Next steps

Once you have successfully integrated your test suite with BrowserStack, you might want to check the following:

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

Is this page helping you?

Yes
No

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!

Talk to an Expert
Download Copy Check Circle