fix(cli): honour BROWSERSTACK_PROJECT_NAME / BROWSERSTACK_BUILD_NAME in session caps (SDK-7075)

[shivam5643]

What is this about?

BROWSERSTACK_PROJECT_NAME and BROWSERSTACK_BUILD_NAME were ignored by this service. The launcher read projectName / buildName only out of the capabilities, so a value exported in the environment never reached the session — the build landed on the dashboard under whatever the config file said.

Every other SDK, and the binary's own env→config map, already give the environment precedence over the config file. The service was the one place that did not, so a user who overrides the build name per CI run (the standard pattern) silently got the config name instead.

The fix

In the constructor, before the bstack:options values are folded into this._buildName / this._projectName, take the env value when one is exported. Both capability shapes are covered — the array form and the multiremote object form.

if (process.env.BROWSERSTACK_PROJECT_NAME) {
    capability['bstack:options'].projectName = process.env.BROWSERSTACK_PROJECT_NAME
}
if (process.env.BROWSERSTACK_BUILD_NAME) {
    capability['bstack:options'].buildName = process.env.BROWSERSTACK_BUILD_NAME
}

Writing it back into the caps (rather than only into the private field) is what makes the session itself carry the name; the private fields are assigned from the caps on the next lines, so Test Reporting picks the env value up too.

Knock-on: _handleBuildIdentifier — please read

Because the env var is now folded into the caps, a buildName is present whenever BROWSERSTACK_BUILD_NAME is exported. _handleBuildIdentifier drops the identifier when !this._buildName, so that branch no longer fires in this case and the identifier is appended to the env-sourced name instead of being discarded.

This is the direction already taken and approved in this repo, not a new one:

• SDK-4748 (f1ebafc, 079f4b8, merged) removed || process.env.BROWSERSTACK_BUILD_NAME from that guard, so the env var stopped suppressing the identifier.
• SDK-7075 (this PR) makes the env var supply the build name.

Together they give the coherent result: the env names the build, and the identifier is appended to it. The previously open #192 (SDK-4165) asked for the same end state and was superseded by SDK-4748.

The one test that encoded the old edge case — env var set, caps carrying no buildName — asserted the identifier was dropped. Its premise is now self-contradictory, since the env var is a buildName source, so it is rewritten to assert the corrected contract. A buildName counts as absent only when neither the caps nor the environment supply one, which should not set buildIdentifier from env when buildName is absent already covers and which still passes unchanged. The SDK-4748 comments that asserted "this service never reads that var as a buildName source" are updated, since that is no longer true.

Scope boundary

Only the bstack:options (W3C) capability shape is covered. The legacy branch — caps with no bstack:options, where the build name comes from the top-level build key — is left as is. That is the shape the CLI flow never produces, and it is not the path SDK-7075 reproduces on.

Verification

End to end, against a real session. The config file and the environment deliberately disagreed:

	config file said	dashboard shows
project	sdk7075repro_project	sdk7075v9_project_env_vars
build	sdk7075repro_build	sdk7075v9_build_env_vars v9_identifier_repro

Run via the automate/wdio_cucumber BStackAutomation sample (binary/CLI flow) — Spec Files: 1 passed, 1 total, session status passed. Both env values won; before the fix both came through as the config values. The identifier is appended, as described above.

Unit tests. Three new constructor tests. Reverting only launcher.ts while keeping the tests makes the two "prefer env" tests fail, so they are not vacuous; the third ("keep the caps values when the env vars are not set") passes either way and is there as a no-regression guard.

Full suite green on this branch: 61 files, 1386 tests passed, build clean.

Related Jira task/s

SDK-7075

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:

• New Feature
• Bug Fix
• Other Improvement

Release notes (customer-facing):

• Fixed BROWSERSTACK_PROJECT_NAME and BROWSERSTACK_BUILD_NAME being ignored — the environment now takes precedence over the project and build names in your config file, matching the other BrowserStack SDKs.

Release notes (internal):

• Launcher constructor now folds BROWSERSTACK_PROJECT_NAME / BROWSERSTACK_BUILD_NAME into bstack:options for both the array and multiremote capability shapes, ahead of the this._buildName / this._projectName assignment, so the session and Test Reporting both carry the env value.
• Knock-on: a buildName is now present whenever BROWSERSTACK_BUILD_NAME is set, so _handleBuildIdentifier keeps the identifier rather than dropping it. Completes the direction SDK-4748 started; the test encoding the old edge case is rewritten and the stale comments corrected.
• Legacy (non-bstack:options) capability shape deliberately out of scope.

Checklist

• Ready to review
• Has it been tested locally?

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: d2dafd16-a42c-4c7e-80e2-d8a22180d5d3

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

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

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

[shivam5643]

v8 backport: #283 — same change, same tests, verified the same way. Please review the two together.

[github-actions]

🔴 SDK PR Review gate is red. Pending:

• The SDK PR Review Agent has not been run on the current head commit yet — run the SDK PR Review Agent (its verdict is advisory; this gate only requires that it ran on the latest commit).

It turns green once the SDK PR Review Agent has run on the current head commit (any verdict — the gate only requires that the review ran). A native reviewer approval is separately required by branch protection before merge.