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

[karanshah-browserstack]

Why it is not latest and pointed to specific version?

[Jimesh-browserstack]

There seems to be an issue in SDK for PW > 1.50.
Ticket raised here https://browserstack.atlassian.net/browse/SDK-5954

[Jimesh-browserstack]

Thanks for the review @karanshah-browserstack — pushed 0f337d2 which addresses threads #1, #2, and #4 directly. Thread #3 (README format) still needs your input — see the bottom of this comment.

---

Re: config/browserstack.single.yml — buildIdentifier: '#${BUILD_NUMBER}' ✅ resolved

Why is this needed?

Dropped. The whole config/ directory is gone, and buildIdentifier is removed from the remaining browserstack.yml — agree it was pure dashboard UX, not required for a sample. If we miss it, easy to add back.

---

Re: Makefile ✅ resolved

Why is makefile needed?

Dropped. We followed your instinct to look at this honestly — the Makefile was a Python equivalent of cucumber-ruby-browserstack's Rakefile, but the only thing it really earned was the per-mode config swapping, and we've removed all the modes except the default. Now there's one command:

browserstack-sdk behave features/sample.feature

Run directly, both locally and in CI (see .github/workflows/build.yml).

Local-tunnel mode is documented as a one-line config flip (browserstackLocal: true in browserstack.yml) rather than a separate config file + feature + Make target.

---

Re: requirements.txt — playwright==1.49.0

Why it is not latest and pointed to specific version?

Playwright >=1.50 triggers an immediate failure with the current Python SDK at session start:

TypeError: bstack1l111l11l1_opy_() got an unexpected keyword argument 'artifactsDir'

The SDK monkeypatches Playwright's BrowserType.launch() and passes a kwarg that newer Playwright launchers don't accept. PW 1.49.0 is the last version verified working against browserstack-sdk==1.46.0. Will move the pin once the SDK release notes call out a higher upper bound — if there's an existing SDK-team tracking ticket I'll link it from the comment in requirements.txt.

---

Re: README.md ⏸ awaiting input

This won't look good, let's keep it consistent with existing sample repos?

I modeled this PR on cucumber-ruby-browserstack (master) — same SDK family, similarly short README. After today's simplification the structure now matches it almost 1:1 (one yml, one feature, one command).

Existing samples diverge in shape though, so want to confirm before any prose rewrite. Which template should the README mirror?

• cucumber-ruby-browserstack — short README: Setup / Running / Further Reading (current shape)
• cucumber-java-playwright-browserstack — long README: BrowserStack logo + Prerequisites / Quick start / Setting credentials / Localhost / Project layout / Customizing / Adopting / Troubleshooting / Notes
• testng-browserstack — if there's a different canonical we're standardizing on

Happy to rewrite once we pick.

[karanshah-browserstack]

behave-playwright-browserstack

[Jimesh-browserstack]

Fixed in fa69904 — was behave-playwright-sdk:sample-master:v1.0 (my made-up -sdk prefix). Updated to behave-playwright:sample-master:v1.0 matching the existing convention: cucumber-ruby uses cucumber-ruby:sample-master:v1.1, cucumber-java-playwright uses cucumber-java-playwright:sample-master:v1.0 — pattern is <framework>-<library>:sample-master:v<N>. Happy to coordinate the version with the ASI team before merge if you'd like.

[karanshah-browserstack]

behave-playwright-browserstack

[karanshah-browserstack]

behave-playwright-browserstack:sample-main:v1.0