Add vanilla Java (Selenium) BrowserStack SDK Automate sample

.github/workflows/sdk-sample-test.yml

@@ -0,0 +1,72 @@
+# Runs the BrowserStack SDK sample against a given commit and reports a status check.
+# Trigger: Actions tab -> "Vanilla Java SDK sample test" -> Run workflow -> paste the PR's full commit SHA.
+# Requires repo secrets: BROWSERSTACK_USERNAME, BROWSERSTACK_ACCESS_KEY.
+name: Vanilla Java SDK sample test
+
+on:
+  workflow_dispatch:
+    inputs:
+      commit_sha:
+        description: 'The full commit id to build'
+        required: true
+
+permissions:
+  contents: read       # checkout
+  checks: write        # github-script creates the status check
+
+jobs:
+  sdk-sample:
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      max-parallel: 3
+      matrix:
+        os: [ubuntu-latest]
+        java: ['11', '17']
+    name: vanilla-java JDK ${{ matrix.java }} sample
+    env:
+      BROWSERSTACK_USERNAME: ${{ secrets.BROWSERSTACK_USERNAME }}
+      BROWSERSTACK_ACCESS_KEY: ${{ secrets.BROWSERSTACK_ACCESS_KEY }}
+    defaults:
+      run:
+        working-directory: .
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          ref: ${{ github.event.inputs.commit_sha }}
+      - name: Mark status check in_progress
+        uses: actions/github-script@v7
+        env:
+          job_name: vanilla-java JDK ${{ matrix.java }} sample
+          commit_sha: ${{ github.event.inputs.commit_sha }}
+        with:
+          github-token: ${{ github.token }}
+          script: |
+            await github.rest.checks.create({
+              owner: context.repo.owner, repo: context.repo.repo,
+              name: process.env.job_name, head_sha: process.env.commit_sha,
+              status: 'in_progress'
+            }).catch(e => console.log('check create failed:', e.status));
+      - uses: actions/setup-java@v4
+        with:
+          distribution: 'temurin'
+          java-version: ${{ matrix.java }}
+      - name: Run sample test
+        run: |
+          mvn compile
+          mvn compile exec:exec
+      - name: Mark status check completed
+        if: always()
+        uses: actions/github-script@v7
+        env:
+          conclusion: ${{ job.status }}
+          job_name: vanilla-java JDK ${{ matrix.java }} sample
+          commit_sha: ${{ github.event.inputs.commit_sha }}
+        with:
+          github-token: ${{ github.token }}
+          script: |
+            await github.rest.checks.create({
+              owner: context.repo.owner, repo: context.repo.repo,
+              name: process.env.job_name, head_sha: process.env.commit_sha,
+              status: 'completed', conclusion: process.env.conclusion
+            }).catch(e => console.log('check create failed:', e.status));

.gitignore

@@ -0,0 +1,21 @@
+# Maven
+target/
+
+# IDE
+.idea/
+*.iml
+.vscode/
+.project
+.classpath
+.settings/
+
+# OS
+.DS_Store
+
+# BrowserStack / logs
+local.log
+logs/
+log/
+
+# Credentials — never commit
+.env

README.md

@@ -1,2 +1,82 @@
-# vanilla-java-browserstack
-We require the following new public repositories under the browserstack GitHub organization to host customer-facing sample projects for the BrowserStack SDK.
+# Vanilla Java (Selenium) with BrowserStack
+
+Run Selenium WebDriver tests on [BrowserStack Automate](https://automate.browserstack.com/)
+using the **BrowserStack Java SDK** — no test framework required. The SDK attaches as a
+`-javaagent:`, reads `browserstack.yml`, and runs your tests across the configured platform
+matrix with zero code changes for credentials, platforms, Test Observability, and Local.
+
+This sample contains exactly two tests:
+
+- **Sample test** (`BStackDemoTest`) — an add-to-cart flow on [bstackdemo.com](https://bstackdemo.com/).
+- **Local test** (`BStackLocalTest`) — verifies the BrowserStack Local tunnel by opening
+  `http://bs-local.com:45454` and asserting the page title.
+
+## Prerequisites
+
+- A [BrowserStack account](https://www.browserstack.com/users/sign_up) (username + access key).
+- **JDK 11+** — Selenium 4.23 requires Java 11 (`maven.compiler.source/target = 11`).
+- **Maven 3.6+**.
+
+## Setup
+
+1. Clone this repository and change into it:
+   ```bash
+   git clone https://github.com/browserstack/vanilla-java-browserstack.git
+   cd vanilla-java-browserstack
+   ```
+2. Configure your BrowserStack credentials. Either edit `userName` / `accessKey` in
+   `browserstack.yml`, or export them as environment variables (env vars take precedence):
+   ```bash
+   export BROWSERSTACK_USERNAME="YOUR_USERNAME"
+   export BROWSERSTACK_ACCESS_KEY="YOUR_ACCESS_KEY"
+   ```
+3. Resolve dependencies (downloads Selenium and the BrowserStack Java SDK):
+   ```bash
+   mvn clean compile
+   ```
+
+The `-javaagent:` jar is wired automatically: the `maven-dependency-plugin` resolves the
+SDK jar path into the `${com.browserstack:browserstack-java-sdk:jar}` property, and the
+`exec-maven-plugin` passes it as `-javaagent:` when launching each test class.
+
+## Run Sample Test
+
+Runs the bstackdemo.com add-to-cart flow across the platforms in `browserstack.yml`:
+
+```bash
+mvn test
+```
+
+Or, equivalently, via the exec goal:
+
+```bash
+mvn compile exec:exec
+```
+
+## Run Local Test
+
+`browserstackLocal: true` in `browserstack.yml` tells the SDK to start a BrowserStack Local
+tunnel before the session, so the remote browser can reach `http://bs-local.com:45454`:
+
+```bash
+mvn compile exec:exec -P sample-local
+```
+
+To run both tests concurrently:
+
+```bash
+mvn compile exec:exec -P run-parallel
+```
+
+## Notes / Dashboard
+
+- View runs, video, logs, and network traffic at
+  [automate.browserstack.com](https://automate.browserstack.com/).
+- With `testObservability: true`, the same build also appears in
+  [Test Observability](https://observability.browserstack.com/).
+- Platforms, parallelism, Local, Observability, and debugging flags are all controlled from
+  `browserstack.yml` — no code changes needed to add browsers or devices.
+- Vanilla Java has no test runner, so `browserstack.yml` intentionally omits the `framework:`
+  field. The `-javaagent:` still instruments the Selenium `RemoteWebDriver` so sessions are
+  created and reported. Add `framework:` only when adopting a supported test framework
+  (TestNG / JUnit 4 / JUnit 5 / Cucumber).

browserstack.yml

@@ -0,0 +1,59 @@
+# =============================
+# Set BrowserStack Credentials
+# =============================
+# Add your BrowserStack userName and accessKey here or set BROWSERSTACK_USERNAME and
+# BROWSERSTACK_ACCESS_KEY as env variables
+userName: YOUR_USERNAME
+accessKey: YOUR_ACCESS_KEY
+
+# ======================
+# BrowserStack Reporting
+# ======================
+projectName: BrowserStack Samples
+buildName: browserstack build
+buildIdentifier: '#${BUILD_NUMBER}'
+# NOTE: no `framework:` field for vanilla Java — there is no test runner for the SDK to
+# instrument. The `-javaagent:` jar still instruments the Selenium RemoteWebDriver
+# constructor, so sessions are created and reported. Set `framework:` only when using a
+# supported test framework (testng / junit4 / junit5 / cucumber).
+
+# =======================================
+# Platforms (Browsers / Devices to test)
+# =======================================
+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
+
+# =======================
+# Parallels per Platform
+# =======================
+parallelsPerPlatform: 1
+
+# ==========================================
+# BrowserStack Automate + Local
+# ==========================================
+browserstackAutomation: true
+browserstackLocal: true
+
+source: java:sample-sdk:v1.0
+
+# ======================
+# Test Observability
+# ======================
+testObservability: true
+
+# ===================
+# Debugging features
+# ===================
+debug: false
+networkLogs: false
+consoleLogs: errors

pom.xml

@@ -0,0 +1,150 @@
+<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
+    <modelVersion>4.0.0</modelVersion>
+
+    <groupId>com.browserstack</groupId>
+    <artifactId>vanilla-java-browserstack</artifactId>
+    <version>1.0-SNAPSHOT</version>
+    <packaging>jar</packaging>
+
+    <name>vanilla-java-browserstack</name>
+    <url>https://github.com/browserstack/vanilla-java-browserstack</url>
+
+    <properties>
+        <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
+        <maven.compiler.source>11</maven.compiler.source>
+        <maven.compiler.target>11</maven.compiler.target>
+        <selenium.version>4.23.0</selenium.version>
+    </properties>
+
+    <dependencies>
+        <dependency>
+            <groupId>org.seleniumhq.selenium</groupId>
+            <artifactId>selenium-java</artifactId>
+            <version>${selenium.version}</version>
+        </dependency>
+        <dependency>
+            <groupId>com.browserstack</groupId>
+            <artifactId>browserstack-java-sdk</artifactId>
+            <version>LATEST</version>
+            <scope>compile</scope>
+        </dependency>
+        <dependency>
+            <groupId>io.github.bonigarcia</groupId>
+            <artifactId>webdrivermanager</artifactId>
+            <version>5.9.2</version>
+        </dependency>
+    </dependencies>
+
+    <build>
+        <plugins>
+            <plugin>
+                <groupId>org.apache.maven.plugins</groupId>
+                <artifactId>maven-compiler-plugin</artifactId>
+                <version>3.8.1</version>
+                <configuration>
+                    <source>${maven.compiler.source}</source>
+                    <target>${maven.compiler.target}</target>
+                </configuration>
+            </plugin>
+
+            <!-- Resolves the browserstack-java-sdk jar path so it can be wired as a -javaagent. -->
+            <plugin>
+                <artifactId>maven-dependency-plugin</artifactId>
+                <executions>
+                    <execution>
+                        <id>getClasspathFilenames</id>
+                        <goals>
+                            <goal>properties</goal>
+                        </goals>
+                    </execution>
+                </executions>
+            </plugin>
+
+            <!-- Default `mvn exec:exec` (and `mvn test`) runs the add-to-cart sample test. -->
+            <plugin>
+                <groupId>org.codehaus.mojo</groupId>
+                <artifactId>exec-maven-plugin</artifactId>
+                <version>3.0.0</version>
+                <executions>
+                    <execution>
+                        <phase>test</phase>
+                        <goals>
+                            <goal>exec</goal>
+                        </goals>
+                    </execution>
+                </executions>
+                <configuration>
+                    <executable>java</executable>
+                    <arguments>
+                        <argument>-javaagent:${com.browserstack:browserstack-java-sdk:jar}</argument>
+                        <argument>-cp</argument>
+                        <classpath />
+                        <argument>com.browserstack.tests.BStackDemoTest</argument>
+                    </arguments>
+                </configuration>
+            </plugin>
+        </plugins>
+    </build>
+
+    <profiles>
+        <!-- mvn exec:exec -P sample-local  → BrowserStack Local tunnel test -->
+        <profile>
+            <id>sample-local</id>
+            <build>
+                <plugins>
+                    <plugin>
+                        <groupId>org.codehaus.mojo</groupId>
+                        <artifactId>exec-maven-plugin</artifactId>
+                        <version>3.0.0</version>
+                        <executions>
+                            <execution>
+                                <goals>
+                                    <goal>exec</goal>
+                                </goals>
+                            </execution>
+                        </executions>
+                        <configuration>
+                            <executable>java</executable>
+                            <arguments>
+                                <argument>-javaagent:${com.browserstack:browserstack-java-sdk:jar}</argument>
+                                <argument>-cp</argument>
+                                <classpath />
+                                <argument>com.browserstack.tests.BStackLocalTest</argument>
+                            </arguments>
+                        </configuration>
+                    </plugin>
+                </plugins>
+            </build>
+        </profile>
+
+        <!-- mvn exec:exec -P run-parallel  → run both tests concurrently -->
+        <profile>
+            <id>run-parallel</id>
+            <build>
+                <plugins>
+                    <plugin>
+                        <groupId>org.codehaus.mojo</groupId>
+                        <artifactId>exec-maven-plugin</artifactId>
+                        <version>3.0.0</version>
+                        <executions>
+                            <execution>
+                                <goals>
+                                    <goal>exec</goal>
+                                </goals>
+                            </execution>
+                        </executions>
+                        <configuration>
+                            <executable>java</executable>
+                            <arguments>
+                                <argument>-javaagent:${com.browserstack:browserstack-java-sdk:jar}</argument>
+                                <argument>-cp</argument>
+                                <classpath />
+                                <argument>com.browserstack.runner.ParallelTestRunner</argument>
+                            </arguments>
+                        </configuration>
+                    </plugin>
+                </plugins>
+            </build>
+        </profile>
+    </profiles>
+</project>