From 0f68be05a51f6a58741f71fa349d475216e1fdc7 Mon Sep 17 00:00:00 2001
From: Aakash Hotchandani <aakash.h@browserstack.com>
Date: Wed, 3 Jun 2026 17:24:36 +0530
Subject: [PATCH] feat: add BrowserStack SDK sample (Java / Selenium / Gauge)

Adds browserstack.yml (framework: gauge) + browserstack-java-sdk dependency
and README-SDK.md documenting the Gauge -javaagent run. Existing legacy
capability-based sample (env/*.properties, specs, step impls) preserved.

Best-effort: Gauge forks a JVM for its runner; the -javaagent attach
(GAUGE_JAVA_OPTS) and the 'gauge' framework token should be confirmed with
the Java SDK owner before publishing.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 .gitignore       |  3 +++
 README-SDK.md    | 56 ++++++++++++++++++++++++++++++++++++++++++++++++
 browserstack.yml | 27 +++++++++++++++++++++++
 pom.xml          |  6 ++++++
 4 files changed, 92 insertions(+)
 create mode 100644 README-SDK.md
 create mode 100644 browserstack.yml

diff --git a/.gitignore b/.gitignore
index 767ab8c..d95abeb 100644
--- a/.gitignore
+++ b/.gitignore
@@ -23,3 +23,6 @@ logs/
 gauge_bin
 target/
 browserstack.err
+*.log
+local.log
+reports/
diff --git a/README-SDK.md b/README-SDK.md
new file mode 100644
index 0000000..3b5f070
--- /dev/null
+++ b/README-SDK.md
@@ -0,0 +1,56 @@
+# Gauge (Java) with BrowserStack SDK
+
+Run Gauge + Selenium specs on BrowserStack using the [BrowserStack Java SDK](https://www.browserstack.com/docs/automate/selenium/sdk-installation).
+The SDK attaches as a `-javaagent`, reads `browserstack.yml`, and instruments WebDriver — capabilities and
+the hub URL come from `browserstack.yml`, not from the test code or `env/*.properties`.
+
+> This is the SDK sample (on the `sdk` branch). The legacy capability-based sample (`env/*.properties`,
+> the manual `RemoteWebDriver` setup in `src/test/java/.../SearchSpec.java`) is preserved for reference.
+
+## Prerequisites
+
+- A [BrowserStack](https://www.browserstack.com/) account (username + access key)
+- JDK 8+ and Maven
+- Gauge CLI (`gauge`) — see https://docs.gauge.org/getting_started/installing-gauge
+
+## Setup
+
+```bash
+git clone -b sdk https://github.com/browserstack/gauge-java-browserstack.git
+cd gauge-java-browserstack
+mvn -q dependency:resolve
+```
+
+Configure credentials — set `userName`/`accessKey` in `browserstack.yml`, or:
+
+```bash
+export BROWSERSTACK_USERNAME="YOUR_USERNAME"
+export BROWSERSTACK_ACCESS_KEY="YOUR_ACCESS_KEY"
+```
+
+## Run Sample Test
+
+The add-to-cart spec (`sample-specs/add-to-cart.spec`) across the platforms in `browserstack.yml`:
+
+```bash
+# Resolve the SDK jar and attach it as the agent to Gauge's runner JVM:
+export GAUGE_JAVA_OPTS="-javaagent:$(mvn -q help:evaluate -Dexpression=settings.localRepository -DforceStdout)/com/browserstack/browserstack-java-sdk/*/browserstack-java-sdk-*.jar"
+mvn gauge:execute -DspecsDir=sample-specs
+```
+
+## Run Local Test
+
+Verifies the BrowserStack Local tunnel (`browserstackLocal: true` starts it automatically):
+
+```bash
+mvn gauge:execute -DspecsDir=sample-local-specs
+```
+
+## Notes
+
+- Results: [BrowserStack Automate dashboard](https://automate.browserstack.com/).
+- Product features (Accessibility, Percy, Observability) are `browserstack.yml` keys — `testObservability: true` is on by default.
+
+> ⚠️ **Verify before publishing:** Gauge forks a JVM for the Java runner, so the SDK `-javaagent` must reach
+> that JVM (here via `GAUGE_JAVA_OPTS`). Confirm the exact attach mechanism / `framework: gauge` token with
+> the Java SDK owner — this combo's wiring is best-effort and was not run live (no credentials available).
diff --git a/browserstack.yml b/browserstack.yml
new file mode 100644
index 0000000..f2b6707
--- /dev/null
+++ b/browserstack.yml
@@ -0,0 +1,27 @@
+userName: YOUR_USERNAME
+accessKey: YOUR_ACCESS_KEY
+projectName: BrowserStack Samples
+buildName: browserstack build
+buildIdentifier: '#${BUILD_NUMBER}'
+# Gauge runs on the BrowserStack Java SDK (javaagent). framework token = gauge.
+framework: gauge
+platforms:
+  - os: OS X
+    osVersion: Big Sur
+    browserName: Chrome
+    browserVersion: latest
+  - os: Windows
+    osVersion: 10
+    browserName: Edge
+    browserVersion: latest
+  - deviceName: Samsung Galaxy S22 Ultra
+    browserName: chrome
+    osVersion: 12.0
+parallelsPerPlatform: 1
+browserstackAutomation: true
+browserstackLocal: true
+source: gauge-java-browserstack:sample-sdk:v1.0
+testObservability: true
+debug: false
+networkLogs: false
+consoleLogs: errors
diff --git a/pom.xml b/pom.xml
index 4e36b3e..ec7a91c 100644
--- a/pom.xml
+++ b/pom.xml
@@ -42,6 +42,12 @@
             <artifactId>gauge-java</artifactId>
             <version>0.9.1</version>
         </dependency>
+        <!-- BrowserStack SDK: instruments WebDriver via the -javaagent (see README-SDK.md). -->
+        <dependency>
+            <groupId>com.browserstack</groupId>
+            <artifactId>browserstack-java-sdk</artifactId>
+            <version>LATEST</version>
+        </dependency>
         <dependency>
             <groupId>junit</groupId>
             <artifactId>junit</artifactId>