App automate demo combined with Automate

app-automate/README.md

@@ -0,0 +1,132 @@
+# Cross-Device Automation Agent Demo (BrowserStack App Automate)
+
+[TestNG](http://testng.org) Integration with BrowserStack App Automate for Android and iOS.
+
+![BrowserStack Logo](https://d98b8t1nnulk5.cloudfront.net/production/images/layout/logo-header.png?1469004780)
+
+## What Does This Repo Do?
+
+This repository showcases the use of **BrowserStack's Cross-Device Automation Agent** for mobile app automation using TestNG and Appium. The key feature is the ability to write test steps in **Natural Language (Plain English)**, moving away from explicit Appium locators and actions.
+
+It contains demo scripts:
+* **Android - `AppiumTest.java`**: Runs test objectives on the Wikipedia Android app using simple English commands like searching for articles and validating results.
+* **iOS - `AppiumTest.java`**: Runs test objectives on the BBC News iOS app using simple English commands like navigating to Culture tab and validating page headings.
+
+---
+
+## How It Works
+
+1.  **Enablement:** The feature is enabled by declaring the capability `aiAuthoring: true` in your `browserstack.yml` configuration file.
+2.  **The Command:** Inside the test scripts, the test uses a standard Selenium `JavascriptExecutor` to pass the Natural Language instruction to the BrowserStack environment:
+    ```java
+    // Example for Android: Search for "india" on Wikipedia app
+    jse.executeScript("browserstack_executor: {\"action\": \"ai\", \"arguments\": [\"Tap on the \\\"Search\\\" option from below navigation bar and type \\\" india\\\" on the search bar and tap on the first suggestion\"]}");
+
+    // Example for iOS: Navigate to Culture tab
+    jse.executeScript("browserstack_executor: {\"action\": \"ai\", \"arguments\": [\"Tap on culture tab from the top navigation bar\"]}");
+    ```
+3.  **Execution:** The BrowserStack Cross-Device Automation Agent intercepts this command, interprets the natural language, and executes the equivalent low-level Appium actions on the mobile app.
+
+---
+
+## Setup
+
+### Requirements
+
+1. Java 8+
+    - If Java is not installed, follow these instructions:
+        - For Windows, download latest java version from [here](https://java.com/en/download/) and run the installer executable
+        - For Mac and Linux, run `java -version` to see what java version is pre-installed. If you want a different version download from [here](https://java.com/en/download/)
+
+2. Maven (Only required if using Maven as the build tool)
+   - If Maven is not downloaded, download it from [here](https://maven.apache.org/download.cgi)
+   - For installation, follow the instructions [here](https://maven.apache.org/install.html)
+
+3. Gradle (Only required if using Gradle as the build tool)
+  - If Gradle is not downloaded, download it from [here](https://gradle.org/releases/)  
+  - For installation, follow the instructions [here](https://gradle.org/install/)
+
+---
+
+## Running the Tests
+
+### For Android
+
+#### Using Maven
+
+-   Clone the repository
+-   Navigate to the Android directory: `cd app-automate/android`
+-   Replace `YOUR_USERNAME` and `YOUR_ACCESS_KEY` with your BrowserStack access credentials in `browserstack.yml`.
+-   Declare capability **`aiAuthoring: true`** in `browserstack.yml` file (if not already present).
+-   Install dependencies `mvn compile`
+-   To run the test suite having cross-platform with parallelization, run `mvn test -P sample-test`.
+-   To run local tests, run `mvn test -P sample-local-test`.
+
+#### Using Gradle
+
+-   Clone the repository
+-   Navigate to the Android directory: `cd app-automate/android`
+-   Replace `YOUR_USERNAME` and `YOUR_ACCESS_KEY` with your BrowserStack access credentials in `browserstack.yml`.
+-   Declare capability **`aiAuthoring: true`** in `browserstack.yml` file (if not already present).
+-   Install dependencies `gradle build`
+-   To run the test suite having cross-platform with parallelization, run `gradle sampleTest`.
+-   To run local tests, run `gradle sampleLocalTest`.
+
+### For iOS
+
+#### Using Maven
+
+-   Clone the repository
+-   Navigate to the iOS directory: `cd app-automate/ios`
+-   Replace `YOUR_USERNAME` and `YOUR_ACCESS_KEY` with your BrowserStack access credentials in `browserstack.yml`.
+-   Declare capability **`aiAuthoring: true`** in `browserstack.yml` file (if not already present).
+-   Install dependencies `mvn compile`
+-   To run the test suite having cross-platform with parallelization, run `mvn test -P sample-test`.
+-   To run local tests, run `mvn test -P sample-local-test`.
+
+#### Using Gradle
+
+-   Clone the repository
+-   Navigate to the iOS directory: `cd app-automate/ios`
+-   Replace `YOUR_USERNAME` and `YOUR_ACCESS_KEY` with your BrowserStack access credentials in `browserstack.yml`.
+-   Declare capability **`aiAuthoring: true`** in `browserstack.yml` file (if not already present).
+-   Install dependencies `gradle build`
+-   To run the test suite having cross-platform with parallelization, run `gradle sampleTest`.
+-   To run local tests, run `gradle sampleLocalTest`.
+
+Understand how many parallel sessions you need by using our [Parallel Test Calculator](https://www.browserstack.com/automate/parallel-calculator?ref=github).
+
+---
+
+## Integrate Your Test Suite
+
+### Maven Integration
+
+* Add maven dependency of `browserstack-java-sdk` in your `pom.xml` file:
+    ```xml
+    <dependency>
+        <groupId>com.browserstack</groupId>
+        <artifactId>browserstack-java-sdk</artifactId>
+        <version>LATEST</version>
+        <scope>compile</scope>
+    </dependency>
+    ```
+* Modify your build plugin to run tests by adding `argLine -javaagent:${com.browserstack:browserstack-java-sdk:jar}` in the Surefire plugin configuration.
+* Install dependencies `mvn compile`.
+
+### Gradle Integration
+
+* Add `compileOnly 'com.browserstack:browserstack-java-sdk:latest.release'` in dependencies in your `build.gradle`.
+* Fetch Artifact Information and add `jvmArgs` property in tasks.
+* Install dependencies `gradle build`.
+
+---
+
+## Notes
+
+* You can view your test results on the [BrowserStack App Automate dashboard](https://www.browserstack.com/app-automate).
+* For detailed documentation on Appium and Java setup with BrowserStack App Automate, please refer to the [official documentation](https://www.browserstack.com/docs/app-automate/appium).
+
+## Getting Help
+
+If you are running into any issues or have any queries, please check [Browserstack Support page](https://www.browserstack.com/support/app-automate) or [get in touch with us](https://www.browserstack.com/contact?ref=help).

app-automate/android/.gitignore

@@ -0,0 +1,12 @@
+*.png
+target/
+local.log
+.idea
+*.iml
+**/logs/*
+.DS_Store
+build
+gradle
+.gradle
+gradlew*
+log

app-automate/android/README.md

@@ -0,0 +1,91 @@
+# testng-appium-app-browserstack
+
+This repository demonstrates how to run Appium tests in [TestNG](http://testng.org) on BrowserStack App Automate using BrowserStack SDK.
+
+![BrowserStack Logo](https://d98b8t1nnulk5.cloudfront.net/production/images/layout/logo-header.png?1469004780)
+
+## Setup
+
+### Requirements
+
+1. Java 8+
+
+    - If Java is not installed, follow these instructions:
+        - For Windows, download latest java version from [here](https://java.com/en/download/) and run the installer executable
+        - For Mac and Linux, run `java -version` to see what java version is pre-installed. If you want a different version download from [here](https://java.com/en/download/)
+
+2. Maven (Only required if using Maven as the build tool)
+   - If Maven is not downloaded, download it from [here](https://maven.apache.org/download.cgi)
+   - For installation, follow the instructions [here](https://maven.apache.org/install.html)
+
+3. Gradle (Only required if using Gradle as the build tool)
+  - If Gradle is not downloaded, download it from [here](https://gradle.org/releases/)  
+  - For installation, follow the instructions [here](https://gradle.org/install/) 
+
+### Install the dependencies
+
+To install the dependencies for Android tests, run :
+```sh
+cd android/testng-examples
+mvn clean
+```
+
+Or,
+
+To install the dependencies for iOS tests, run :
+
+```sh
+cd ios/testng-examples
+mvn clean
+```
+
+## Getting Started
+
+Getting Started with Appium tests in TestNg on BrowserStack couldn't be easier!
+
+### **Run Sample test :**
+
+- Switch to one of the following directories: [Android examples](android/testng-examples) or [iOS examples](ios/testng-examples)
+- **For Maven:** Run the following command to execute tests in the Maven environment:  
+    ```sh
+    mvn test -P sample-test
+    ```
+- **For Gradle:** Run the following command to execute tests in the Gradle environment:  
+    ```sh
+    gradle clean sampleTest
+    ```
+
+### **Use Local testing for apps that access resources hosted in development or testing environments :**
+
+- Simply configure the `browserstackLocal` parameter in the `browserstack.yml` file accordingly in [Android examples](android/testng-examples) or [iOS examples](ios/testng-examples).
+  ```
+  browserstackLocal: true
+  ```
+- You can use the `LocalSample` app provided in both folder [Android examples](android/testng-examples) or [iOS examples](ios/testng-examples) to run your test. Change the app parameter in the `browserstack.yml` file.
+
+- **For Maven:** Run the following command to execute tests in the Maven environment:  
+    ```sh
+    mvn test -P sample-local-test
+    ```
+- **For Gradle:** Run the following command to execute tests in the Gradle environment:  
+    ```sh
+    gradle clean sampleLocalTest
+    ```
+
+-similarly for gradle you can do :- gradle clean sampleLocalTest
+
+
+**Note**: If you are facing any issues, refer [Getting Help section](#Getting-Help)
+
+## Integration with other Java frameworks
+
+For other Java frameworks samples, refer to following repositories :
+
+- [JUnit](https://github.com/browserstack/junit-appium-app-browserstack)
+- [Java](https://github.com/browserstack/java-appium-app-browserstack)
+
+Note: For other test frameworks supported by App-Automate refer our [Developer documentation](https://www.browserstack.com/docs/)
+
+## Getting Help
+
+If you are running into any issues or have any queries, please check [Browserstack Support page](https://www.browserstack.com/support/app-automate) or [get in touch with us](https://www.browserstack.com/contact?ref=help).

app-automate/android/browserstack.yml

@@ -0,0 +1,81 @@
+# =============================
+# Set BrowserStack Credentials
+# =============================
+# Add your BrowserStack userName and acccessKey here or set BROWSERSTACK_USERNAME and
+# BROWSERSTACK_ACCESS_KEY as env variables
+userName: vishalshivkumar_ECWceV
+accessKey: CHwbbppxpBGZ5ypzTqxC
+
+# ======================
+# BrowserStack Reporting
+# ======================
+# The following capabilities are used to set up reporting on BrowserStack:
+# Set 'projectName' to the name of your project. Example, Marketing Website
+projectName: BrowserStack Sample
+# Set `buildName` as the name of the job / testsuite being run
+buildName: Cross-Device Automation Agent - Android
+# `buildIdentifier` is a unique id to differentiate every execution that gets appended to
+# buildName. Choose your buildIdentifier format from the available expressions:
+# ${BUILD_NUMBER} (Default): Generates an incremental counter with every execution
+# ${DATE_TIME}: Generates a Timestamp with every execution. Eg. 05-Nov-19:30
+# Read more about buildIdentifiers here -> https://www.browserstack.com/docs/automate/selenium/organize-tests
+buildIdentifier: '#${BUILD_NUMBER}' # Supports strings along with either/both ${expression}
+# Set `framework` of your test suite. Example, `testng`, `cucumber`, `cucumber-testng`
+# This property is needed to send test context to BrowserStack (test name, status)
+framework: testng
+
+source: testng:appium-sample-sdk:v1.1
+
+app: bs://b78d7940823391d54091b98d7f3b223e321d133e
+#app: ./LocalSample.apk #For running local tests
+
+# =======================================
+# Platforms (Browsers / Devices to test)
+# =======================================
+# Platforms object contains all the browser / device combinations you want to test on.
+# Entire list available here -> (https://www.browserstack.com/list-of-browsers-and-platforms/automate)
+
+platforms:
+  - deviceName: Samsung Galaxy S22 Ultra
+    osVersion: 12.0
+    platformName: android
+  # - deviceName: Samsung Galaxy S21
+  #   osVersion: 11.0
+  #   platformName: android
+  # - deviceName: Google Pixel 6 Pro
+  #   osVersion: 12.0
+  #   platformName: android
+aiAuthoring: true
+interactiveDebugging: true
+
+# =======================
+# Parallels per Platform
+# =======================
+# The number of parallel threads to be used for each platform set.
+# 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 (2 * 3) parallel threads will be used on BrowserStack
+#
+# Example 2 - If you have configured 1 platform and set `parallelsPerPlatform` as 5, a total of 5 (1 * 5) parallel threads will be used on BrowserStack
+parallelsPerPlatform: 1
+
+# ==========================================
+# BrowserStack Local
+# (For localhost, staging/private websites)
+# ==========================================
+# Set browserStackLocal to true if your website under test is not accessible publicly over the internet
+# Learn more about how BrowserStack Local works here -> https://www.browserstack.com/docs/automate/selenium/local-testing-introduction
+browserstackLocal: true # <boolean> (Default false)
+#browserStackLocalOptions:
+#Options to be passed to BrowserStack local in-case of advanced configurations
+#  localIdentifier: # <string> (Default: null) Needed if you need to run multiple instances of local.
+#  forceLocal: true  # <boolean> (Default: false) Set to true if you need to resolve all your traffic via BrowserStack Local tunnel.
+# Entire list of arguments available here -> https://www.browserstack.com/docs/automate/selenium/manage-incoming-connections
+
+# ===================
+# Debugging features
+# ===================
+debug: false # <boolean> # Set to true if you need screenshots for every selenium command ran
+networkLogs: false # <boolean> Set to true to enable HAR logs capturing
+consoleLogs: errors # <string> Remote browser's console debug levels to be printed (Default: errors)
+# Available options are `disable`, `errors`, `warnings`, `info`, `verbose` (Default: errors)

app-automate/android/build.gradle

@@ -0,0 +1,47 @@
+plugins {
+    id 'java'
+}
+
+repositories { mavenCentral() }
+
+dependencies {
+    testImplementation 'org.testng:testng:7.5'
+    implementation 'org.seleniumhq.selenium:selenium-java:4.13.0'
+    implementation 'io.appium:java-client:8.6.0'
+    implementation 'commons-io:commons-io:2.11.0'
+    implementation 'com.googlecode.json-simple:json-simple:1.1.1'
+    implementation 'com.browserstack:browserstack-java-sdk:latest.release'
+}
+
+group = 'com.browserstack'
+version = '1.0-SNAPSHOT'
+description = 'testng-browserstack'
+sourceCompatibility = '1.8'
+
+def browserstackSDKArtifact = configurations.compileClasspath.resolvedConfiguration.resolvedArtifacts.find { it.name == 'browserstack-java-sdk' }
+
+tasks.withType(JavaCompile) {
+    options.encoding = 'UTF-8'
+}
+
+tasks.withType(Test) {
+    systemProperties = System.properties
+}
+
+task sampleTest(type: Test) {
+    useTestNG() {
+        dependsOn cleanTest
+        useDefaultListeners = true
+        suites "src/test/resources/com/browserstack/sample-test.testng.xml"
+        jvmArgs "-javaagent:${browserstackSDKArtifact.file}"
+    }
+}
+
+task sampleLocalTest(type: Test) {
+    useTestNG() {
+        dependsOn cleanTest
+        useDefaultListeners = true
+        suites "src/test/resources/com/browserstack/sample-local-test.testng.xml"
+        jvmArgs "-javaagent:${browserstackSDKArtifact.file}"
+    }
+}