feat(browserstack-service): stamp hook_run_uuid on App A11y scans fired inside hooks [APPA11Y-5542]

[AakashHotchandani]

What

App A11y scans fired inside test hooks (before/after, beforeEach/afterEach) are dropped or misattributed today. This makes the SDK stamp the hook's run UUID (thHookRunUuid) on scans fired inside a supported hook.

How

• util.ts — _getParamsForAppAccessibility(commandName, testName, hookRunUuid?) adds thHookRunUuid (dropped by JSON.stringify when undefined, so in-test scans are byte-for-byte unchanged); performA11yScan(…, hookRunUuid?) threads it.
• insights-handler.ts — expose getCurrentHook() so a11y reuses the same UUID reported to TestHub as HookRunStarted (= the hook's BTCER uuid).
• accessibility-handler.ts — beforeHook/afterHook set _currentHookRunUuid for the hook window and, for mocha, enable the scan gate during hooks (per-test hooks honour include/exclude scope; suite hooks use autoScanning); commandWrapper passes the hook uuid into performA11yScan.
• service.ts — wire accessibilityHandler.beforeHook/afterHook, passing the shared hook uuid.

Backend contract

SeleniumHub appAllyHandler (PR #14162, APPA11Y-5542-hook-run-uuid) destructures thHookRunUuid and relays it as hook_run_uuid; app-accessibility reconciles the scan onto the wrapping test via the BTCER self-join. Additive at every hop — no field ⇒ unchanged in-test behaviour.

Scope

Gated on frameworkSupportsHook (mocha before/after/beforeEach/afterEach; cucumber uuid-stamped, its scan gate stays owned by beforeScenario).

Tests

Added hook-scan unit tests (stamp/clear + unsupported-framework no-op). Note: local tsc couldn't fully run against a v8 node_modules on the v9 main base — CI validates on v9 deps.

Co-Authored-By: Claude Opus 4.8 (1M context) noreply@anthropic.com

🤖 Generated with Claude Code

[AakashHotchandani]

Follow-up: ported the change into the active v9 CLI runtime path

The initial commits changed accessibility-handler.ts (the classic/non-CLI path). While validating against a real v9 App Automate session I found that path is inert in the v9 CLI runtime — v9 routes accessibility through the CLI observer modules (cli/modules/accessibilityModule.ts), so the hook-scan behaviour never actually engaged there. This latest commit (62c6f6e) ports the identical contract into the CLI module. (The handler changes are retained; they cover the non-CLI path and are additive.)

What the CLI-path change does

• Registers hook-lifecycle observers (BEFORE_ALL/BEFORE_EACH/AFTER_EACH/AFTER_ALL, PRE+POST). PRE captures the hook's run uuid from KEY_HOOK_ID (the same uuid reported to TestHub as the hook run) and opens the scan gate for the hook window; POST clears it so test-body scans stay unstamped.
• Threads currentHookRunUuid through the web per-command commandWrapper and both manual performScan() patches → performScanCli(…, hookRunUuid) → _getParamsForAppAccessibility → thHookRunUuid (dropped when undefined, so in-test / end-of-test scans are unchanged). Matches SeleniumHub #14162 appAllyScan → hook_run_uuid.
• Adds 6 unit tests for the CLI-module hook logic.

Verified end-to-end on real BrowserStack sessions (file-write probe, since removed):

• Web (Chrome): 5 hook windows detected; each url scan fired inside before/beforeEach/afterEach carried that hook's uuid; test-body click/url scans carried null.
• Android App Automate (Appium): a performScan() called inside each hook fired performScanCli (app branch) with the matching hook uuid → thHookRunUuid in the payload; test-body and end-of-test lifecycle scans carried none.

Scope note for reviewers (App Automate per-command): the v9 CLI deliberately does not install per-command overwriteCommand wrapping for app sessions (appium drivers don't register those commands; it would throw and abort onBeforeExecute) — app scans run via the lifecycle/performScan path. So on the CLI path a hook-time app scan is stamped when it comes from a performScan() (or the lifecycle scan while a hook window is open), not from automatic per-command wrapping. The v8/handler path (which wraps every command) covers automatic per-command app hook scans. If we want automatic per-command app scanning on the CLI path too, that's a separate, larger change (re-enabling app command wrapping with per-command try/catch) and I'd raise it separately.