Local Testing is a BrowserStack feature that helps you test mobile apps that access resources hosted in development or testing environments during automated test execution. This page will guide you through enabling Local Testing for App Automate sessions, and then using it to test apps that retrieve data from servers on your local machine, CI/CD machines or nodes, and other private network configurations. In this guide you will learn how to :
username
and access_key
. If you haven’t created an account yet, sign up for a free trial or purchase a paid plan. After signup, you can obtain your access credentials hereMaven
installed on your system. To install Maven
, follow steps outlined in the installation guide.apk
or .aab
file) or iOS app (.ipa
file).apk
or .ipa
file and are looking to simply try App Automate Local Testing, you can download and test using our sample Android Local app or sample iOS Local app.
Upload your Android app (.apk
or .aab
file) or iOS app (.ipa
file) to BrowserStack servers using our REST API. Here is an example cURL
request to upload app on App Automate :
curl -u "YOUR_USERNAME:YOUR_ACCESS_KEY" \
-X POST "https://api-cloud.browserstack.com/app-automate/upload" \
-F "file=@/path/to/apk/file"
curl -u "YOUR_USERNAME:YOUR_ACCESS_KEY" ^
-X POST "https://api-cloud.browserstack.com/app-automate/upload" ^
-F "file=@/path/to/apk/file"
Ensure that @
symbol is prepended to the file path in the above request. A sample response for the above request is shown below:
{
"app_url" : "bs://j3c874f21852ba57957a3fdc33f47514288c4ba4"
}
Please note the app_url
value returned in the API response (bs://j3c874.....
in the above example). We will use this value to set the application under test while configuring the test later on.
cURL
command until you get the response back.Clone the TestNG sample integration code from our GitHub repository.
git clone https://github.com/browserstack/testng-appium-app-browserstack.git
Next, execute the following commands to install required dependencies:
# Test an android app
cd android/testng-examples
mvn clean
# Test an iOS app
cd ios/testng-examples
mvn clean
This will install requisite dependencies including Appium’s Java client library and Java binding for BrowserStack Local :
<dependencies>
<dependency>
<groupId>org.testng</groupId>
<artifactId>testng</artifactId>
<version>6.9.10</version>
</dependency>
<dependency>
<groupId>io.appium</groupId>
<artifactId>java-client</artifactId>
<version>7.0.0</version>
</dependency>
<dependency>
<groupId>commons-io</groupId>
<artifactId>commons-io</artifactId>
<version>1.3.2</version>
</dependency>
<dependency>
<groupId>org.seleniumhq.selenium</groupId>
<artifactId>selenium-java</artifactId>
<version>3.141.59</version>
</dependency>
<dependency>
<groupId>com.browserstack</groupId>
<artifactId>browserstack-local-java</artifactId>
<version>1.0.3</version>
</dependency>
<dependency>
<groupId>com.googlecode.json-simple</groupId>
<artifactId>json-simple</artifactId>
<version>1.1.1</version>
</dependency>
</dependencies>
Desired capabilities are a series of key-value pairs that allow you to configure your Appium tests on BrowserStack. The following capabilities are required for Local Testing :
app
capability : Its used to specify your uploaded app that will be installed on the device during test execution. Use the app_url
obtained in Upload your App section to set its value.device
capability : Its used to specify the BrowserStack device you want to run the test on.browserstack.local
capability : Its used to enable BrowserStack Local feature for your test execution.In the TestNG sample integration code, Appium’s desired capabilities are defined in the local.conf.json
file located in the testng-examples/src/test/resources/com/browserstack/run_local_test
directory :
{
"server": "hub-cloud.browserstack.com",
"username": "YOUR_USERNAME",
"access_key": "YOUR_ACCESS_KEY",
"capabilities": {
"project": "First TestNg Android Project",
"build": "TestNg Android Local",
"name": "local_test",
"browserstack.debug": true,
"browserstack.local": true,
"app": "bs://<app-id>"
},
"environments": [
{
"device": "Google Pixel 3",
"os_version": "9.0"
}
]
}
{
"server": "hub-cloud.browserstack.com",
"username": "YOUR_USERNAME",
"access_key": "YOUR_ACCESS_KEY",
"capabilities": {
"project": "First TestNg iOS Project",
"build": "TestNg iOS Local",
"name": "local_test",
"browserstack.debug": true,
"browserstack.local": true,
"app": "bs://<app-id>"
},
"environments": [
{
"device": "iPhone 11 Pro",
"os_version": "13"
}
]
}
In addition to using the browserstack.local
capability, you also need to establish a Local Testing connection from your local or CI/CD machine to BrowserStack servers. Within your test scripts, you can add a code snippet that will automatically start and stop Local Testing connection using BrowserStack’s Java binding for BrowserStack Local.
In the TestNG sample integration code, the Local Testing connection is initialised in the BrowserStackTestNGTest.java
file located in the testng-examples/src/test/java/com/browserstack/run_local_test
directory as shown below :
//...
public class BrowserStackTestNGTest {
//...
@BeforeMethod(alwaysRun=true)
public void setUp() throws Exception {
//...
local = new Local();
Map<String, String> options = new HashMap<String, String>();
options.put("key", accessKey);
local.start(options);
}
//...
@AfterMethod(alwaysRun=true)
public void tearDown() throws Exception {
//...
if(local != null) local.stop();
}
}
Once you have configured desired capabilities and established Local Testing connection, you can initialize an Appium webdriver to test remotely on BrowserStack. In order to do so, you need to use a remote BrowserStack URL along with your BrowserStack access credentials.
In the TestNG sample integration code, the remote Webdriver is initialised in the BrowserStackTestNGTest.java
file located in the testng-examples/src/test/java/com/browserstack/run_local_test
directory as shown below :
//...
// Initialize the remote Webdriver using BrowserStack remote URL access credentials
// and desired capabilities defined above
driver = new AndroidDriver (
new URL("http://"+username+":"+accessKey+"@"+config.get("server")+"/wd/hub"), capabilities
);
//...
//...
// Initialize the remote Webdriver using BrowserStack remote URL access credentials
// and desired capabilities defined above
driver = new IOSDriver<IOSElement> (
new URL("http://"+username+":"+accessKey+"@"+config.get("server")+"/wd/hub"), capabilities
);
//...
BROWSERSTACK_USERNAME
& BROWSERSTACK_ACCESS_KEY
environment variables or byusername
& access_key
parameters in local.config.json
file located in testng-examples/src/test/resources/com/browserstack/run_local_test
directory
This step will help you setup your first Local Testing test case with TestNG framework. In the TestNG sample integration code, we have provided a sample test-case in testng-examples/src/test/java/com/browserstack/run_local_test
directory for BrowserStack’s sample apps. If you are testing your own app, please modify the test case accordingly.
If you are using your own app, modify the following code as per your test case:
package com.browserstack.run_local_test;
// imports...
public class LocalTest extends BrowserStackTestNGTest {
@Test
public void test() throws Exception {
AndroidElement searchElement = (AndroidElement) new WebDriverWait(driver, 30)
.until(ExpectedConditions.elementToBeClickable(
MobileBy.id("com.example.android.basicnetworking:id/test_action")));
searchElement.click();
AndroidElement insertTextElement = (AndroidElement) new WebDriverWait(driver, 30)
.until(ExpectedConditions.elementToBeClickable(
MobileBy.className("android.widget.TextView")));
AndroidElement testElement = null;
List<AndroidElement> allTextViewElements = driver.findElementsByClassName(
"android.widget.TextView");
Thread.sleep(10);
for(AndroidElement textElement : allTextViewElements) {
if(textElement.getText().contains("The active connection is")) {
testElement = textElement;
}
}
if(testElement == null) {
File scrFile = ((TakesScreenshot)driver).getScreenshotAs(OutputType.FILE);
FileUtils.copyFile(scrFile, new File(System.getProperty("user.dir") + "screenshot.png"));
System.out.println("Screenshot stored at " + System.getProperty("user.dir") + "screenshot.png");
throw new Error("Cannot find the needed TextView element from app");
}
String matchedString = testElement.getText();
System.out.println(matchedString);
Assert.assertTrue(matchedString.contains("The active connection is wifi"));
Assert.assertTrue(matchedString.contains("Up and running"));
}
}
If you are using your own app, modify the following code as per your test case:
package com.browserstack.run_local_test;
// imports...
public class LocalTest extends BrowserStackTestNGTest {
@Test
public void test() throws Exception {
IOSElement testButton = (IOSElement) new WebDriverWait(driver, 30)
.until(ExpectedConditions.elementToBeClickable(
MobileBy.AccessibilityId("TestBrowserStackLocal")));
testButton.click();
WebDriverWait wait = new WebDriverWait(driver, 30);
wait.until(new ExpectedCondition<Boolean>() {
@Override
public Boolean apply(WebDriver d) {
String result = d.findElement(MobileBy.AccessibilityId("ResultBrowserStackLocal"))
.getAttribute("value");
return result != null && result.length() > 0;
}
});
IOSElement resultElement = (IOSElement) driver.findElement(
MobileBy.AccessibilityId("ResultBrowserStackLocal"));
String resultString = resultElement.getText().toLowerCase();
System.out.println(resultString);
if(resultString.contains("not working")) {
File scrFile = (File) ((TakesScreenshot)driver).getScreenshotAs(OutputType.FILE);
FileUtils.copyFile(scrFile, new File(System.getProperty("user.dir") + "/screenshot.png"));
System.out.println("Screenshot stored at " + System.getProperty("user.dir") + "/screenshot.png");
throw new Error("Unexpected BrowserStackLocal test result");
}
String expectedString = "Up and running";
Assert.assertTrue(resultString.contains(expectedString.toLowerCase()));
}
}
You are ready to run your first local test on BrowserStack. In the TestNG sample integration code, switch to testng-examples/
directory, and run the test using command :
# Run using maven
mvn test -P local
You can access the test execution results, and debugging information such as video recording, network and device logs on App Automate dashboard or using our REST APIs.
Congratulations! You just ran your first local test on App Automate. Next, you can learn to :
If you have any queries, please get in touch with us.
Contact our Support team for immediate help while we work on improving our docs.
Contact our Support team for immediate help while we work on improving our docs.
Thank you for your valuable feedback!