feat(LCAM-1282): central-user test metadata, GRR URL guard, build grouping identifier (v8)

[ashish0305]

What is this about?

Adds central-user test-metadata support to the BrowserStack WebdriverIO service on the v8 line into this extracted standalone repo (packages/browserstack-service/src).

• New BrowserStackSDK.setTestMetadata({ identifier, ... }) public API backed by a per-test-run TestMetadata store, gated on the app_lcnc central user (BROWSERSTACK_CENTRAL_USER). Metadata is attached to the TestFramework gRPC event and the reporter's BTCER payload.
• getCentralUser() central-user mode; its keys are merged into the TestHub product maps.
• APIUtils.updateURLSForGRR validates the GRR URL set via a hasValidGRRUrls type guard and no-ops (returns false) when incomplete — prevents the TypeError → prod-collector fallback.
• Sends grouping_identifier (BROWSERSTACK_BUILD_GROUPING_IDENTIFIER) on build launch.
• Forces result = 'skipped' for TestRunSkipped (mocha sets state = 'pending').

Verified locally on v8: npm run build passes and the full test suite is green (42/42 files). Supersedes the accidentally main-based PR #72.

Related Jira task/s

LCAM-1282 — App LCA SDK integration (WebdriverIO service, v8).

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)

• Added support for attaching custom test metadata to test runs via BrowserStackSDK.setTestMetadata() for central-user integrations.

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

• Updated testHub/utils, funnelInstrumentation, and testHubModule specs for the new app_lcnc product-map key / onBeforeTest instance arg.

Checklist

• Ready to review
• Has it been tested locally?

PR Validations

Run Tests: Comment RUN_TESTS to trigger sanity tests.

🤖 Generated with Claude Code

---

🔗 Related PRs — SDK + App A11y Deploy Plan

📄 Deploy plan: SDK + App A11y Deploy Plan

SDK artifacts

• browserstack/browserstack-binary#1123
• feat(LCAM-1282): central-user test metadata, GRR URL guard, build grouping identifier (v8) #78

Config

• browserstack/infra-config#45945

Backend services

• browserstack/observability-pipeline#6324
• browserstack/app-lcnc-backend#139 — SDK Integration
• browserstack/app-lcnc-backend#382 — App A11y
• browserstack/app-lcnc-runner#137
• browserstack/app-lcnc-services#86

Staging URL support for App A11y scans

• browserstack/realmobile#10823
• browserstack/mobile#13752

[github-actions]

🔴 SDK PR Review gate is red. Pending:

• The SDK PR Review Agent has not reviewed the current head commit yet — run the SDK PR Review Agent.

It turns green once the latest SDK PR Review Agent run reports GTG on the current head commit. A native reviewer approval is separately required by branch protection before merge.

[github-actions]

🔴 SDK PR Review gate is red. Pending:

• The SDK PR Review Agent has not reviewed the current head commit yet — run the SDK PR Review Agent.

It turns green once the latest SDK PR Review Agent run reports GTG on the current head commit. A native reviewer approval is separately required by branch protection before merge.

[github-actions]

🔴 SDK PR Review gate is red. Pending:

• The SDK PR Review Agent has not reviewed the current head commit yet — run the SDK PR Review Agent.

It turns green once the latest SDK PR Review Agent run reports GTG on the current head commit. A native reviewer approval is separately required by branch protection before merge.

[osho-20]

Code review — App LCNC rollout (setTestMetadata / appLcnc)

Reviewed alongside the paired Binary PR (browserstack-binary#1123).

🔴 Must-fix

1. packages/browserstack-service/src/reporter.ts → getRunData — verified directly against the source: line 363-364 (pre-existing, unchanged) already does if (eventType === 'TestRunSkipped') { eventType = 'TestRunFinished' }. The new block added by this PR checks if (eventType === 'TestRunSkipped') again a few lines later — but by then eventType has already been rewritten, so that branch (which sets result: 'skipped' and attaches app_lcnc metadata) can never execute. Dead code as written.

2. packages/browserstack-service/src/metadata.ts → TestMetadata.get() — metadataByTestRunUuid[uuid] || fallbackMetadata || {}. fallbackMetadata is module-level shared state overwritten by every set() call, so any test run that never calls setTestMetadata() silently inherits whatever an unrelated run last set, instead of {}. The new unit test ('falls back to the latest metadata for an unknown uuid') currently asserts this leak as intended behavior — it'll need updating alongside the fix.

3. Same getRunData call site, a second independent problem — TestMetadata.get(testData.uuid) is keyed on the reporter's own local uuidv4(), not the test_uuid scheme that TestMetadata.setCurrentTestRunUuid() actually uses (see testHubModule.ts). Even once Browserstack wdio service code #1 is fixed and the branch becomes reachable, this lookup can never hit the right entry — it'll keep returning stale/leaked metadata from chore: update package and lock files devDependencies #2 instead of {}.

⚠️ Worth fixing, non-blocking

4. packages/browserstack-service/src/cli/modules/testHubModule.ts → onBeforeTest — the new test-run-uuid tracking (getCurrentTestRunUuid / TestMetadata.setCurrentTestRunUuid) has no error boundary; args.instance is only typed, not runtime-guaranteed, so a bad instance can throw and abort the whole pre-test hook. The test suite needed a new mock field just to avoid crashing — itself a signal this path isn't hardened.
5. testHubModule.ts + testHub/utils.ts → getProductMap — the new TestMetadata/app_lcnc wiring (uuid resolution, reset() trigger, merge into the outgoing event, and the getCentralUser() spread) has no behavioral test coverage anywhere in this PR — only mock patches to prevent crashes, not assertions on the actual new behavior.

Contract note (informational)

util.ts adds an optional grouping_identifier field to the build-launch payload. Safe as an additive optional field — flagging only because it's a wire-contract change worth tracking.

What's good

• metadata.ts validates identifier (non-empty string, ≤40 chars) before accepting it, and no-ops with a warning rather than throwing — solid graceful degradation.
• The appLcnc resolution precedence tests (config flag vs APP_LCNC_RUN env var vs binConfig.envVars) are dense and check both productMap and parseConfigForBuildStartCall for consistency.

Cross-repo note

metadata.ts's fallback-leak bug has a mirrored copy in browserstack-binary's vendored copy of this file — worth fixing both together so the bug doesn't survive in one repo after being patched in the other.

— SDK PR Review Agent