Add second sample: BrowserStack Local test (features/local.feature)

Mirrors the 2-sample pattern from cucumber-java-browserstack and
junit-browserstack so customers get one public-site sample plus one
BrowserStack Local sample.

- features/local.feature — navigates http://bs-local.com:45454/ and asserts
  the page title contains "BrowserStack Local".
- features/steps/local_steps.py — two steps.
- features/local-html/index.html — title-matching page; start with
  `python3 -m http.server 45454 --directory features/local-html` before
  running the local feature.
- browserstack.yml — browserstackLocal: true (matches cucumber-java-browserstack
  canonical so the SDK starts and stops the tunnel for every run).
- README.md — repo layout updated; Running section split into "Sample test"
  and "Local test" subsections with explicit local-server start command.

Live-verified end-to-end: build 03f2c770c3b15871829075c20f45ad4a826b56cf
returns status=passed for all 6 sessions (2 scenarios x 3 Playwright engines:
chromium 148, playwright-firefox 148, playwright-webkit 18.2).

Author: Jimesh-browserstack

README.md

@@ -13,19 +13,39 @@ This repo shows how to run [behave](https://behave.readthedocs.io/) tests on Bro
 * Set `BROWSERSTACK_USERNAME` and `BROWSERSTACK_ACCESS_KEY` as environment variables, or replace `userName` and `accessKey` directly in `browserstack.yml` with your [BrowserStack Username and Access Key](https://www.browserstack.com/accounts/settings). Env vars take precedence.
 
 ### Running your tests
-Run the sample in parallel across the 3 Playwright browser engines (chromium / firefox / webkit) declared in `browserstack.yml`:
+There are two sample scenarios in `features/`:
+
+* **`features/sample.feature`** — drives `https://www.bstackdemo.com` (a public site) and adds a product to the cart.
+* **`features/local.feature`** — drives `http://bs-local.com:45454/` through the BrowserStack Local tunnel; verifies the page title contains "BrowserStack Local".
+
+`browserstack.yml` enables `browserstackLocal: true`, so the SDK starts and stops the BrowserStack Local tunnel for you on every run — no manual binary lifecycle.
+
+#### Sample test (public site)
+Runs in parallel across the 3 Playwright browser engines (chromium / firefox / webkit) declared in `browserstack.yml`:
 
 ```sh
 browserstack-sdk behave features/sample.feature
 ```
 
+#### Local test (private / localhost host)
+Start a local HTTP server first — `features/local-html/` contains a tiny page titled "BrowserStack Local Test Page":
+
+```sh
+python3 -m http.server 45454 --directory features/local-html
+```
+
+Then in a separate terminal:
+
+```sh
+browserstack-sdk behave features/local.feature
+```
+
+`bs-local.com` is a hostname BrowserStack Local resolves to your machine inside the remote browser — for your own app, point your scenarios at `http://bs-local.com:<port>/` instead of a public URL.
+
 Understand how many parallel sessions you need by using our [Parallel Test Calculator](https://www.browserstack.com/automate/parallel-calculator?ref=github).
 
 Alternatively the variables can be set in the environment using env or your CI framework (like GitHub Actions or Jenkins). See `.github/workflows/build.yml` for a GitHub Actions example — it runs on `workflow_dispatch` (manual trigger) with a commit SHA input and posts a status check back to that commit.
 
-### Testing a private host (BrowserStack Local)
-If your app lives on `localhost`, a staging host, or behind a firewall, set `browserstackLocal: true` in `browserstack.yml` and rerun the same command. The SDK starts and stops the BrowserStack Local tunnel for you — no manual binary download or lifecycle management. Then point your scenarios at `http://bs-local.com:<port>/` (a hostname BrowserStack Local resolves to your machine) instead of a public URL.
-
 ### How the SDK changes things
 - **One `browserstack.yml`** declares platforms; the SDK picks them up automatically.
 - **The SDK runs platforms in parallel for you** — no hand-rolled parallel runner; the SDK forks one behave run per `(platform × parallelsPerPlatform)` cell.
@@ -39,9 +59,13 @@ If your app lives on `localhost`, a staging host, or behind a firewall, set `bro
 ├── requirements.txt
 └── features/
     ├── sample.feature         # bstackdemo add-to-cart scenario
+    ├── local.feature          # BrowserStack Local tunnel scenario
+    ├── local-html/
+    │   └── index.html         # static page served on :45454 for local.feature
     ├── environment.py         # behave hooks: launch browser, hand to context.page
     └── steps/
-        └── sample_steps.py
+        ├── sample_steps.py
+        └── local_steps.py
 ```
 
 ### Further Reading

browserstack.yml

@@ -65,7 +65,7 @@ parallelsPerPlatform: 1
 # ==========================================
 # 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: false # <boolean> (Default false)
+browserstackLocal: true # <boolean> (Default false)
 
 # Options to be passed to BrowserStack local in-case of advanced configurations
 # browserStackLocalOptions:

features/local-html/index.html

@@ -0,0 +1,16 @@
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <title>BrowserStack Local Test Page</title>
+  </head>
+  <body>
+    <h1>BrowserStack Local Test Page</h1>
+    <p>
+      Served on <code>http://localhost:45454/</code> for the
+      <code>features/local.feature</code> scenario. The BrowserStack Local
+      tunnel resolves <code>bs-local.com:45454</code> on the remote browser
+      back to this page.
+    </p>
+  </body>
+</html>

features/local.feature

@@ -0,0 +1,5 @@
+Feature: Verify BrowserStack Local
+
+  Scenario: Navigate to a page served on localhost through the BrowserStack Local tunnel
+    Given I visit local app website
+    Then the page title should contain "BrowserStack Local"

features/steps/local_steps.py

@@ -0,0 +1,14 @@
+from behave import given, then
+
+
+@given("I visit local app website")
+def visit_local_app(context):
+    context.page.goto("http://bs-local.com:45454/")
+
+
+@then('the page title should contain "{expected}"')
+def verify_title_contains(context, expected):
+    title = context.page.title()
+    assert expected in title, (
+        f"expected title to contain {expected!r}, got {title!r}"
+    )