merge sdk branch in master

.gitignore

@@ -6,8 +6,8 @@ local.log
 .gradle
 build/
 .DS_Store
-browserstack.err
-gradle/
+gradle
 gradlew
 gradlew.bat
-logs/
+logs
+browserstack.err

README.md

@@ -2,58 +2,99 @@
 
 [TestNG](http://testng.org) Integration with BrowserStack.
 
-Master branch contains **Selenium 4** samples, for **Selenium 3 - JSON Wire Protocol** please checkout [selenium-3](https://github.com/browserstack/testng-browserstack/tree/selenium-3) branch
-
 ![BrowserStack Logo](https://d98b8t1nnulk5.cloudfront.net/production/images/layout/logo-header.png?1469004780)
 
 ## Using Maven
 
-### Setup
-
-* Clone the repo
+### Run sample build
+
+- Clone the repository
+- Replace YOUR_USERNAME and YOUR_ACCESS_KEY with your BrowserStack access credentials in browserstack.yml.
+- 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`
+
+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
+
+This repository uses the BrowserStack SDK to run tests on BrowserStack. Follow the steps below to install the SDK in your test suite and run tests on BrowserStack:
+
+* Create sample browserstack.yml file with the browserstack related capabilities with your [BrowserStack Username and Access Key](https://www.browserstack.com/accounts/settings) and place it in your root folder.
+* Add maven dependency of browserstack-java-sdk in your pom.xml file
+```sh
+<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}` and `maven-dependency-plugin` for resolving dependencies in the profiles `sample-test` and `sample-local-test`.
+```
+            <plugin>
+               <artifactId>maven-dependency-plugin</artifactId>
+                 <executions>
+                   <execution>
+                     <id>getClasspathFilenames</id>
+                       <goals>
+                         <goal>properties</goal>
+                       </goals>
+                   </execution>
+                 </executions>
+            </plugin>
+            <plugin>
+                <groupId>org.apache.maven.plugins</groupId>
+                <artifactId>maven-surefire-plugin</artifactId>
+                <version>3.0.0-M5</version>
+                <configuration>
+                    <suiteXmlFiles>
+                        <suiteXmlFile>config/sample-local-test.testng.xml</suiteXmlFile>
+                    </suiteXmlFiles>
+                    <argLine>
+                        -javaagent:${com.browserstack:browserstack-java-sdk:jar}
+                    </argLine>
+                </configuration>
+            </plugin>
+```
 * Install dependencies `mvn compile`
-* Update `*.conf.json` files inside the `src/test/resources/conf` directory with your [BrowserStack Username and Access Key](https://www.browserstack.com/accounts/settings)
-
-### Running your tests
 
-- To run a single test, run `mvn test -P single`
-- To run local tests, run `mvn test -P local`
-- To run parallel tests, run `mvn test -P parallel`
-- To run the test suite, run `mvn test -P suite`
+## Using Gradle
 
- Understand how many parallel sessions you need by using our [Parallel Test Calculator](https://www.browserstack.com/automate/parallel-calculator?ref=github)
-
-
- ## Using Gradle
-
- ### Setup
+### Prerequisites
+- If using Gradle, Java v9+ is required.
 
-* Clone the repo
-* Install dependencies `gradle build`
-* Update `*.conf.json` files inside the `src/test/resources/conf` directory with your [BrowserStack Username and Access Key](https://www.browserstack.com/accounts/settings)
-
-### Running your tests
+### Run sample build
 
-- To run a single test, run `gradle singleTest`
-- To run local tests, run `gradle localTest`
-- To run parallel tests, run `gradle parallelTest`
-- To run the test suite, run `gradle suiteTest`
+- Clone the repository
+- 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)
+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
 
-## Notes
-* You can view your test results on the [BrowserStack Automate dashboard](https://www.browserstack.com/automate)
-* To test on a different set of browsers, check out our [platform configurator](https://www.browserstack.com/automate/java#setting-os-and-browser)
-* You can export the environment variables for the Username and Access Key of your BrowserStack account
+This repository uses the BrowserStack SDK to run tests on BrowserStack. Follow the steps below to install the SDK in your test suite and run tests on BrowserStack:
 
+* Following are the changes required in `gradle.build` -
+    * Add `compileOnly 'com.browserstack:browserstack-java-sdk:latest.release'` in dependencies
+    * Fetch Artifact Information and add `jvmArgs` property in tasks *SampleTest* and *SampleLocalTest* :
   ```
-  export BROWSERSTACK_USERNAME=<browserstack-username> &&
-  export BROWSERSTACK_ACCESS_KEY=<browserstack-access-key>
+  def browserstackSDKArtifact = configurations.compileClasspath.resolvedConfiguration.resolvedArtifacts.find { it.name == 'browserstack-java-sdk' }
+
+  task sampleTest(type: Test) {
+    useTestNG() {
+      dependsOn cleanTest
+      useDefaultListeners = true
+      suites "config/sample-test.testng.xml"
+      jvmArgs "-javaagent:${browserstackSDKArtifact.file}"
+    }
+  }
   ```
 
-## Additional Resources
-* [Documentation for writing Automate test scripts in Java](https://www.browserstack.com/automate/java)
-* [Customizing your tests on BrowserStack](https://www.browserstack.com/automate/capabilities)
-* [Browsers & mobile devices for selenium testing on BrowserStack](https://www.browserstack.com/list-of-browsers-and-platforms?product=automate)
-* [Using REST API to access information about your tests via the command-line interface](https://www.browserstack.com/automate/rest-api)
+* Install dependencies `gradle build`
+
+
+## Notes
+* You can view your test results on the [BrowserStack Automate dashboard](https://www.browserstack.com/automate)

browserstack.yml

@@ -0,0 +1,75 @@
+# =============================
+# Set BrowserStack Credentials
+# =============================
+# Add your BrowserStack userName and acccessKey here or set BROWSERSTACK_USERNAME and
+# BROWSERSTACK_ACCESS_KEY as env variables
+userName: YOUR_USERNAME
+accessKey: YOUR_ACCESS_KEY
+
+# ======================
+# Organizing your tests
+# ======================
+# Use `projectName`, `buildName`, `name` capabilities to organise your tests
+# `name` is the name of your test sessions and is automatically picked from your
+# test name and doesn't need to be set manually when using BrowserStack SDK
+# `buildName` is used to name your CI/CD job or the execution of your test suite.
+# Ensure you add a dynamic identifier, like an incremental build number from your
+# CI/CD or timestamp at the end of every build; otherwise tests from different
+# executions will be grouped together on BrowserStack
+buildName: browserstack-build-1
+# Use `projectName` to set the name of your project. Example, Marketing Website
+projectName: BrowserStack Samples
+# Use `framework` to set the framework of your project. Example, testng, cucumber, cucumber-testng
+framework: testng
+
+# =======================================
+# 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:
+  - os: OS X
+    osVersion: Big Sur
+    browserName: Chrome
+    browserVersion: latest
+  - os: Windows
+    osVersion: 10
+    browserName: Edge
+    browserVersion: latest
+  - device: Samsung Galaxy S22 Ultra
+    browserName: chrome # Try 'samsung' for Samsung browser
+    osVersion: 12.0
+
+# =======================
+# 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
+
+source: testng:sample-master:v1.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)

build.gradle

@@ -7,48 +7,37 @@ repositories { mavenCentral() }
 dependencies {
     implementation 'org.testng:testng:7.4.0'
     implementation 'commons-io:commons-io:1.3.2'
-    implementation 'org.seleniumhq.selenium:selenium-java:4.1.0'
+    implementation 'org.seleniumhq.selenium:selenium-java:4.1.4'
     implementation 'com.browserstack:browserstack-local-java:1.0.6'
     implementation 'com.googlecode.json-simple:json-simple:1.1.1'
+    compileOnly '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'
 }
 
-task singleTest(type: Test) {
-    useTestNG() {
-      dependsOn cleanTest
-      useDefaultListeners = true
-      suites "config/single.testng.xml"
-    }
-}
-
-task localTest(type: Test) {
-    useTestNG() {
-      dependsOn cleanTest
-      useDefaultListeners = true
-      suites "config/local.testng.xml"
-    }
-}
-
-task parallelTest(type: Test) {
+task sampleTest(type: Test) {
     useTestNG() {
-      dependsOn cleanTest
-      useDefaultListeners = true
-      suites "config/parallel.testng.xml"
+        dependsOn cleanTest
+        useDefaultListeners = true
+        suites "config/sample-test.testng.xml"
+        jvmArgs "-javaagent:${browserstackSDKArtifact.file}"
     }
 }
 
-task suiteTest(type: Test) {
+task sampleLocalTest(type: Test) {
     useTestNG() {
-      dependsOn cleanTest
-      useDefaultListeners = true
-      suites "config/suite.testng.xml"
+        dependsOn cleanTest
+        useDefaultListeners = true
+        suites "config/sample-local-test.testng.xml"
+        jvmArgs "-javaagent:${browserstackSDKArtifact.file}"
     }
 }

config/local.testng.xml → config/sample-local-test.testng.xml

@@ -1,11 +1,10 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <!DOCTYPE suite SYSTEM "http://testng.org/testng-1.0.dtd">
 <suite name="Local">
-    <parameter name="config" value="local.conf.json"/>
     <test name="LocalTest">
-        <parameter name="environment" value="chrome"/>
         <classes>
             <class name="com.browserstack.LocalTest"/>
         </classes>
     </test>
 </suite>
+

config/sample-test.testng.xml

@@ -0,0 +1,9 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE suite SYSTEM "http://testng.org/testng-1.0.dtd">
+<suite name="Cross-Platform">
+    <test name="BStackDemo">
+        <classes>
+            <class name="com.browserstack.BStackDemoTest" />
+        </classes>
+    </test>
+</suite>