fix(percy): skip launcher Percy setup when the BrowserStack CLI is running (SDK-7817)

[kamal-kaur04]

What is this about?

With Percy enabled and the BrowserStack CLI running, Percy was set up twice at the same path:

1. The CLI's PercyModule downloads the Percy CLI to ~/.browserstack/percy and starts it.
2. The launcher then also ran setupPercy (launcher.ts, if (shouldSetupPercy)), which re-downloaded Percy into that same file while it was running.

On Linux, writing over a running executable fails with ETXTBSY: text file is busy, open '~/.browserstack/percy'. The error is unhandled and crashes the run (GitHub Actions and other Linux CI). macOS allows the overwrite silently, so it only showed up as a Corrupt percy binary, retrying loop.

The launcher's Percy is never used in the CLI flow, because the worker-side PercyHandler only runs when the CLI is not running. This PR skips the launcher's Percy setup when BrowserstackCLI.getInstance().isRunning(). The best-platform Percy selection still runs. The non-CLI flow is unchanged.

Why it started now: binary 1.58.0 (browserstack-binary #1820, security fix SDK-7620) pins Percy CLI to v1.32.9 and no longer writes ~/.browserstack/percy.etag. Before that, the service found the binary's ETag, got a 304 from releases/latest and skipped its download. Now it always downloads.

v8: not affected. On v8, this Percy setup is already inside the !BrowserstackCLI.getInstance().isRunning() block.

Related Jira task/s

• SDK-7817
• TM-28964

Release (mandatory for every PR — required for the ready-for-review label)

Version bump: (required — tick exactly one)

• minor (backwards-compatible feature)
• patch (bug fix or other small change)

Release notes type: (optional)

• New Feature
• Bug Fix
• Other Improvement

Release notes (customer-facing): (optional but encouraged)

• Fixed ETXTBSY: text file is busy, open '~/.browserstack/percy' crashes on Linux when Percy is enabled.

Release notes (internal): (required — engineer-facing; what actually changed / why)

• The launcher no longer runs setupPercy (download + start of a service-side Percy CLI) when the BrowserStack CLI is running, because the CLI's PercyModule owns the Percy process. This removes the second download over the running ~/.browserstack/percy, which binary 1.58.0's removal of percy.etag turned into an ETXTBSY crash on Linux.

Checklist

• Ready to review
• Has it been tested locally?

Testing

• Unit tests: added 2 tests in tests/launcher.test.ts. "CLI running → no service Percy" fails without the fix and passes with it; "CLI not running → service Percy still starts" passes. launcher.test.ts result: 130/132 pass; the 2 _uploadApp failures also fail on main.
• End-to-end on macOS, WDIO 9 + mocha, App Automate, 3 parallel Android devices, percy: true, clean home directory:
  • Before the fix (9.29.1 and 9.39.2): the service re-downloaded Percy twice over the CLI's running binary (Saved new ETag for percy binary, then Corrupt percy binary, retrying).
  • With the fix: zero service-side downloads, the CLI's Percy binary is left intact, 27/27 Percy screenshots succeeded and 3/3 specs passed (Percy build).
• Pending: Linux container run showing ETXTBSY before the fix and not after.

PR Validations

Run Tests: Comment RUN_TESTS to trigger sanity tests.

🤖 Generated with Claude Code

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on this repository. Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

• Configuration used: Central YAML (base), Organization UI (inherited), Workspace UI (inherited)
• Review profile: ASSERTIVE
• Plan: Enterprise
• Run ID: 153fc57a-bb6a-4d95-8306-3217fe96df72

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

• Autopilot · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

---

_{Comment @coderabbitai help to get the list of available commands.}

[kamal-kaur04]

E2E verification — before / after

Setup: WDIO 9 + mocha, App Automate, 3 parallel Android devices, percy: true, fresh empty HOME per run, BrowserStack CLI flow, macOS.

Run	Service	TestHub build UUID	App Automate build	Percy build	Specs	Percy screenshots ok / fail	Service-side Percy download (Saved new ETag)	Corrupt percy binary	Percy is managed by the BrowserStack CLI	~/.browserstack/percy after run
Before	9.29.1 (customer version)	hcifhubfb43xfkzgqcbpih5lgzatqokwz7cmd5t9	6edf9a4f73984d891170c74dfa63ebbcaf1eb6d3	54341993	3/3	27 / 0	2	2	0	91,498,624 B (overwritten by the service's download)
Before	9.39.2 (latest)	bl5iessngvwvw9irzjkflfallwml33pkw4pmxqqg	6783fb61f344ecfe29474e6d7fc1ed45a3a943f4	54341893	3/3	27 / 0	2	2	0	91,498,624 B (overwritten by the service's download)
After	this PR (eb3aac1)	x6xkcvalcnsthap8rw9qplvvcq7ol9ojlsgj10gq	b8868d502c9398942ceda5d628f899ef3ea05d7f	54342039	3/3	27 / 0	0	0	1	81,170,608 B (the CLI's own pinned copy, intact)

Dashboard checks: all 3 sessions are present with the correct status on every build listed.

Before: the launcher downloads Percy twice over the CLI's running ~/.browserstack/percy and logs Corrupt percy binary, retrying each time. The CLI's Percy then exits abnormally. On Linux, this same write fails with ETXTBSY and crashes the run. macOS allows the write, so no ETXTBSY appears in these runs.
After: no service-side download or start, and the CLI's Percy binary is left intact.

Side benefit: in both before runs, the service-side Percy process was still running after wdio exited (orphaned, holding port 5338). That breaks the next build on reused or self-hosted machines. After the fix, the port is free once the run ends.

Pending: the Linux before/after pair showing ETXTBSY and its absence. Docker is unavailable locally, so this needs a container or a GitHub Actions ubuntu run.

[kamal-kaur04]

RUN_TESTS

[kamal-kaur04]

✅ Good to go

File	Confidence
.changeset/pr-263.md	✅ All Clear
packages/browserstack-service/src/launcher.ts	✅ All Clear
packages/browserstack-service/tests/launcher.test.ts	✅ All Clear

Change map (generated deterministically from the diff)

graph LR
  subgraph nwdio_browserstack_service["wdio-browserstack-service"]
    npackages_browserstack_service_src_launcher_ts["launcher.ts<br/>~20 lines"]
    npackages_browserstack_service_tests_launcher_test_ts["launcher.test.ts<br/>~20 lines"]
    n_changeset_pr_263_md["pr-263.md<br/>~5 lines"]
  end

Loading

↻ This verdict comment is the review anchor — it's updated in place on each run (the gate posts its status separately).

— SDK PR Review Agent

[github-actions]

🟢 SDK PR Review gate is green — the SDK PR Review Agent has run on the current head commit (verdict: success).

This gate confirms a review ran on the latest commit. The verdict itself is advisory — read the findings and use your judgement; it does not block merge. A native GitHub reviewer approval is still separately required by branch protection before this PR can merge.

[minionhelperappqa]

[SDK Wdio Test] TRA build state: passed | Stability 100% — verdict: success. Passed: 52, Failed: 0, Aggregate: 52. TRA: https://observability.browserstack.com/builds/uys99ocrohxg5de1ombemh3b4wraszcn3rvmfdpb

[minionhelperappqa]

[SDK Wdio Test] TRA build state: failed | Stability 81% — verdict: failure. Passed: 982, Failed: 226, Aggregate: 1210. TRA: https://observability.browserstack.com/builds/ymv23wmubh3f3398fmi2tmlvuibhxwaicib9yoqq

[yashdsaraf]

Why is this file needed?

[kamal-kaur04]

This file is automatically added for release notes purposes and get removed

[yashdsaraf]

Okay to add in regression but I'm not sure about the purpose of .changeset/pr-263.md file.