Add BrowserStack SDK + Playwright behave sample

[Jimesh-browserstack]

Summary

Customer-facing starting point for running behave tests on BrowserStack via Playwright Python and the BrowserStack Python SDK. Mirrors the shape of browserstack/cucumber-ruby-browserstack (browserstack-sdk-selenium-4 branch) but adapted for behave + Playwright.

What customers get

.
├── browserstack.yml                  # 3-platform parallel default (chromium/firefox/webkit)
├── config/
│   ├── browserstack.single.yml       # 1 platform
│   └── browserstack.local.yml        # 1 platform + browserstackLocal: true
├── requirements.txt                  # SDK + behave + playwright==1.49.0 (pinned)
├── Makefile                          # parallel / single / local / install
└── features/
    ├── sample.feature                # bstackdemo add-to-cart
    ├── local.feature                 # localhost via tunnel
    ├── local-html/index.html         # static page served on :45454 by `make local`
    ├── environment.py                # sync_playwright + chromium.launch + page wiring
    └── steps/
        ├── sample_steps.py
        └── local_steps.py

Three customer-facing entry points:

• make parallel — runs across the three Playwright engine families (chromium / firefox / webkit) in parallel on BrowserStack
• make single — one chromium platform
• make local — one chromium platform + BrowserStack Local tunnel against a local HTTP server the Makefile spins up on :45454

Design notes

• Customer code is browser-agnostic. features/environment.py calls chromium.launch() unconditionally; the SDK monkeypatches Playwright at runtime to route the launch to the per-platform browser configured in browserstack.yml. No chromium.connect(wss_url) plumbing needed in customer code (this differs from the Java SDK behavior).
• Config swapping mirrors the Ruby reference. The SDK only reads ./browserstack.yml, so single and local Make targets copy in alternates from config/, run, and restore the parallel default afterwards (even on failure).
• Local mode self-tests. Rather than running bstackdemo through an unused tunnel, make local serves a small static page on localhost:45454 and routes a localhost-targeting scenario through the BS Local tunnel that the SDK starts/stops automatically.
• Playwright is pinned to ==1.49.0. PW >=1.50 trips an SDK monkeypatch arg that no longer matches (unexpected keyword argument 'artifactsDir'). Comment in requirements.txt explains.
• CI workflow follows the cucumber-java-playwright-browserstack pattern: workflow_dispatch only with a commit_sha input, posts check status back to that SHA. No push / pull_request triggers, so BrowserStack minutes aren't burned on every commit.

Local verification (already complete)

Ran each Make target end-to-end against BrowserStack from a fresh clone with creds in env vars:

Mode	Build	Sessions	Result
make parallel	3ea91fa0…	3 (chrome 147 / playwright-firefox 148 / playwright-webkit 18.2)	all 3 passed
make single	e64fd864…	1 (chrome)	passed
make local	d47aa127…	1 (chrome via BS Local tunnel → localhost:45454)	passed

Cleanup checks on every run: browserstack.yml restored to 3-platform default after single and local, no leftover .bak file, no orphan python3 -m http.server on :45454.

CI verification (pending post-merge)

workflow_dispatch workflows only become dispatchable from the Actions UI once they exist on the default branch — so CI can't be validated against this branch before merge. After merge, dispatch the workflow against main HEAD; if BrowserStack auth fails it means the org-level Actions secrets (BROWSERSTACK_USERNAME / BROWSERSTACK_ACCESS_KEY) aren't wired through to this repo and need to be added by an Actions admin (same setup as cucumber-java-playwright-browserstack).

Test plan

• make parallel runs all 3 platforms in parallel — see Build URL above
• make single runs one chromium session
• make local starts BS Local tunnel, serves localhost page, scenario passes
• browserstack.yml is restored after single / local, no .bak leftover
• No orphan python3 -m http.server on :45454 after make local
• workflow_dispatch runs green post-merge (pending — see "CI verification" above)

🤖 Generated with Claude Code