Add pytest-bdd + Appium App Automate sample (Android + iOS)

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

@@ -0,0 +1,75 @@
+# Runs the BrowserStack SDK sample against a given commit and reports a status check.
+# Trigger: Actions tab -> "pytest-bdd Appium App Automate SDK sample test" -> Run workflow -> paste the PR's full commit SHA.
+# Requires repo secrets: BROWSERSTACK_USERNAME, BROWSERSTACK_ACCESS_KEY.
+# NOTE (App Automate): the sample app is committed in the repo and referenced by relative path
+# (app: ./WikipediaSample.apk); the SDK uploads it at run time, so no pre-uploaded bs:// id is needed.
+name: pytest-bdd Appium App Automate 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]
+        python: ['3.10', '3.11']
+    name: pytest-bdd-appium Python ${{ matrix.python }} sample
+    env:
+      BROWSERSTACK_USERNAME: ${{ secrets.BROWSERSTACK_USERNAME }}
+      BROWSERSTACK_ACCESS_KEY: ${{ secrets.BROWSERSTACK_ACCESS_KEY }}
+    defaults:
+      run:
+        working-directory: android
+    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: pytest-bdd-appium Python ${{ matrix.python }} 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-python@v5
+        with:
+          python-version: ${{ matrix.python }}
+      - name: Install
+        run: |
+          pip install -r requirements.txt
+      - name: Run sample test
+        run: |
+          browserstack-sdk pytest tests/test_sample.py
+      - name: Mark status check completed
+        if: always()
+        uses: actions/github-script@v7
+        env:
+          conclusion: ${{ job.status }}
+          job_name: pytest-bdd-appium Python ${{ matrix.python }} 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,9 @@
+.vscode
+__pycache__
+.pytest_cache
+.venv
+env
+local.log
+log/
+*.apk
+*.ipa

README.md

@@ -1,2 +1,89 @@
-# pytest-bdd-appium-app-browserstack
-We require the following new public repositories under the browserstack GitHub organization to host customer-facing sample projects for the BrowserStack SDK.
+# pytest-bdd + Appium with BrowserStack App Automate
+
+Run Appium (mobile app) tests written with **pytest-bdd** on real devices on
+[BrowserStack App Automate](https://app-automate.browserstack.com/) using the
+BrowserStack Python SDK. No capability boilerplate in your tests — the SDK reads
+`browserstack.yml` and routes each session to the BrowserStack device cloud.
+
+This repo has two self-contained platform directories:
+
+```
+android/   Android sample (WikipediaSample.apk) + local (LocalSample.apk)
+ios/       iOS sample (BStackSampleApp.ipa) + local (LocalSample.ipa)
+```
+
+Each directory has its own `browserstack.yml`, `conftest.py` (Appium driver
+fixture), `features/` (Gherkin), `tests/` (pytest-bdd step definitions), and
+`requirements.txt`.
+
+## Prerequisites
+
+- A [BrowserStack](https://www.browserstack.com/) account (username + access key).
+- Python 3.8+.
+- An application to test. Both directories reference their public sample app by
+  **local path** (`app: ./WikipediaSample.apk` / `./BStackSampleApp.ipa`) — the SDK
+  uploads it at run time, so the sample works on any account (no pre-uploaded
+  `bs://` id required).
+
+## Setup
+
+```bash
+git clone <this-repo>
+cd pytest-bdd-appium-app-browserstack/android      # or: cd pytest-bdd-appium-app-browserstack/ios
+
+python3 -m venv .venv
+.venv/bin/pip install -r requirements.txt
+```
+
+Configure credentials via env vars (recommended) or by editing `browserstack.yml`:
+
+```bash
+export BROWSERSTACK_USERNAME="YOUR_USERNAME"
+export BROWSERSTACK_ACCESS_KEY="YOUR_ACCESS_KEY"
+```
+
+## Run Sample Test (Android)
+
+From inside `android/`:
+
+```bash
+browserstack-sdk pytest -s tests/test_sample.py
+```
+
+This runs the **Wikipedia search** scenario on a real Samsung Galaxy S22 Ultra:
+tap "Search Wikipedia", type "BrowserStack", and assert matching results are returned.
+
+## Run Sample Test (iOS)
+
+From inside `ios/`:
+
+```bash
+browserstack-sdk pytest -s tests/test_sample.py
+```
+
+## Run Local Test
+
+The local scenario (`tests/test_local.py`) exercises **BrowserStack Local**. Because
+App Automate installs **one app per build**, the local scenario is a *separate* build
+that runs against the **local** sample app (`LocalSample.apk` / `LocalSample.ipa`,
+committed alongside the main app) — it cannot share a build with the Wikipedia/BStack
+sample. To run it, point `app:` at the local build in `browserstack.yml`, then run only
+the local test:
+
+```bash
+# android/ — set `app: ./LocalSample.apk` in browserstack.yml, then:
+browserstack-sdk pytest -s tests/test_local.py
+# ios/ — set `app: ./LocalSample.ipa`, then run the same command
+```
+
+`browserstackLocal: true` (already set in `browserstack.yml`) starts the Local tunnel
+automatically — no separate binary to launch.
+
+## Notes / Dashboard
+
+- View runs and shareable session links at
+  [app-automate.browserstack.com](https://app-automate.browserstack.com/).
+- Test Observability (`testObservability: true`) reports also appear at
+  [observability.browserstack.com](https://observability.browserstack.com/).
+- The `app:` value can be a local path (the SDK uploads it and rewrites to
+  `bs://<hashed-id>`) or a pre-uploaded `bs://<id>`.

android/browserstack.yml

@@ -0,0 +1,55 @@
+# =============================
+# 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: appauto-pytest-bdd-appium
+buildIdentifier: '#${BUILD_NUMBER}'
+# `framework` lets the SDK instrument pytest-bdd and send test context to BrowserStack.
+framework: pytest-bdd
+
+# ==========================================
+# Application under test
+# ==========================================
+# Public sample app committed in this repo; the SDK uploads it at run time (works on any account).
+# NOTE: App Automate installs ONE app per build. The local scenario uses ./LocalSample.apk and must
+# run as a SEPARATE build (set app: ./LocalSample.apk for that run) — see README "Run Local Test".
+app: ./WikipediaSample.apk
+
+# =======================================
+# Platforms (Devices to test)
+# =======================================
+platforms:
+  - deviceName: Samsung Galaxy S22 Ultra
+    osVersion: "12.0"
+    platformName: android
+
+# =======================
+# Parallels per Platform
+# =======================
+parallelsPerPlatform: 1
+
+# ==========================================
+# BrowserStack Local (used by the local scenario / tests/test_local.py)
+# ==========================================
+browserstackLocal: true
+
+source: pytest-bdd:appium-sample-sdk:v1.0
+
+# ======================
+# Test Observability
+# ======================
+testObservability: true
+
+# ===================
+# Debugging features
+# ===================
+debug: true
+networkLogs: true

android/conftest.py

@@ -0,0 +1,18 @@
+import pytest
+from appium import webdriver
+from appium.options.android import UiAutomator2Options
+
+
+@pytest.fixture(scope="function")
+def driver(request):
+    """Appium driver fixture shared by the pytest-bdd step definitions.
+
+    Under `browserstack-sdk pytest`, the SDK injects the app, device, and
+    credentials from browserstack.yml (or the BROWSERSTACK_USERNAME /
+    BROWSERSTACK_ACCESS_KEY env vars), so a bare UiAutomator2Options() is
+    enough — no device caps or credentials are set here.
+    """
+    options = UiAutomator2Options()
+    drv = webdriver.Remote("https://hub.browserstack.com/wd/hub", options=options)
+    yield drv
+    drv.quit()

android/features/local.feature

@@ -0,0 +1,9 @@
+Feature: BrowserStack App Automate local test
+  As a BrowserStack user
+  I want the local sample app to reach a service over the BrowserStack Local tunnel
+  So that I can verify BrowserStack Local tunnelling works for mobile apps
+
+  Scenario: Reach the local endpoint from the device
+    Given I have launched the local sample app
+    When I trigger the local network test
+    Then the app reports it is up and running

android/features/sample.feature

@@ -0,0 +1,9 @@
+Feature: BrowserStack App Automate sample test
+  As a BrowserStack user
+  I want to search Wikipedia in the WikipediaSample app
+  So that I can verify search results are returned
+
+  Scenario: Search Wikipedia for BrowserStack
+    Given I have launched the Wikipedia sample app
+    When I search Wikipedia for "BrowserStack"
+    Then search results are displayed

android/requirements.txt

@@ -0,0 +1,6 @@
+Appium-Python-Client
+selenium>=3.14
+pytest
+pytest-bdd
+browserstack-local
+browserstack-sdk @ https://sdk-assets.browserstack.com/python/browserstack_sdk-latest.tar.gz

android/tests/test_local.py

@@ -0,0 +1,29 @@
+import os
+
+from pytest_bdd import scenario, given, when, then
+from appium.webdriver.common.appiumby import AppiumBy
+
+FEATURES = os.path.join(os.path.dirname(os.path.dirname(__file__)), "features")
+
+
+@scenario(os.path.join(FEATURES, "local.feature"), "Reach the local endpoint from the device")
+def test_local():
+    """LocalSample.apk over the BrowserStack Local tunnel (browserstackLocal: true)."""
+
+
+@given("I have launched the local sample app")
+def launch_local_app(driver):
+    # The SDK launches the local sample app from browserstack.yml.
+    pass
+
+
+@when("I trigger the local network test")
+def trigger_local_test(driver):
+    driver.find_element(
+        AppiumBy.ID, "com.example.android.basicnetworking:id/test_action").click()
+
+
+@then("the app reports it is up and running")
+def app_up_and_running(driver):
+    texts = driver.find_elements(AppiumBy.CLASS_NAME, "android.widget.TextView")
+    assert any("Up and running" in (t.text or "") for t in texts)

android/tests/test_sample.py

@@ -0,0 +1,33 @@
+import os
+import time
+
+from pytest_bdd import scenario, given, when, then, parsers
+from appium.webdriver.common.appiumby import AppiumBy
+
+FEATURES = os.path.join(os.path.dirname(os.path.dirname(__file__)), "features")
+
+
+@scenario(os.path.join(FEATURES, "sample.feature"), "Search Wikipedia for BrowserStack")
+def test_search_wikipedia():
+    """WikipediaSample.apk: search Wikipedia and assert results appear."""
+
+
+@given("I have launched the Wikipedia sample app")
+def launch_app(driver):
+    # The SDK launches the app (WikipediaSample.apk) from browserstack.yml.
+    driver.find_element(AppiumBy.ACCESSIBILITY_ID, "Search Wikipedia").click()
+
+
+@when(parsers.parse('I search Wikipedia for "{query}"'))
+def search_wikipedia(driver, query):
+    search = driver.find_element(
+        AppiumBy.ID, "org.wikipedia.alpha:id/search_src_text")
+    search.send_keys(query)
+    time.sleep(5)
+
+
+@then("search results are displayed")
+def results_displayed(driver):
+    results = driver.find_elements(AppiumBy.CLASS_NAME, "android.widget.TextView")
+    # Assert the search actually returned matching results — not merely that the app rendered.
+    assert any("BrowserStack" in (r.text or "") for r in results), "no search result matched the query"

ios/browserstack.yml

@@ -0,0 +1,52 @@
+# =============================
+# Set BrowserStack Credentials
+# =============================
+userName: YOUR_USERNAME
+accessKey: YOUR_ACCESS_KEY
+
+# ======================
+# BrowserStack Reporting
+# ======================
+projectName: BrowserStack Samples
+buildName: appauto-pytest-bdd-appium
+buildIdentifier: '#${BUILD_NUMBER}'
+framework: pytest-bdd
+
+# ==========================================
+# Application under test
+# ==========================================
+# Public sample app committed in this repo; the SDK uploads it at run time (works on any account).
+# NOTE: App Automate installs ONE app per build. The local scenario uses ./LocalSample.ipa and must
+# run as a SEPARATE build (set app: ./LocalSample.ipa for that run) — see README "Run Local Test".
+app: ./BStackSampleApp.ipa
+
+# =======================================
+# Platforms (Devices to test)
+# =======================================
+platforms:
+  - deviceName: iPhone 14 Pro
+    osVersion: "16"
+    platformName: ios
+
+# =======================
+# Parallels per Platform
+# =======================
+parallelsPerPlatform: 1
+
+# ==========================================
+# BrowserStack Local (used by the local scenario / tests/test_local.py)
+# ==========================================
+browserstackLocal: true
+
+source: pytest-bdd:appium-sample-sdk:v1.0
+
+# ======================
+# Test Observability
+# ======================
+testObservability: true
+
+# ===================
+# Debugging features
+# ===================
+debug: true
+networkLogs: true