feat(browserstack-service): stamp hook_run_uuid on App A11y scans in the v9 CLI runtime path [APPA11Y-5542]

The earlier commits fixed accessibility-handler.ts (the classic/non-CLI
path), but v9 App Automate runs through the CLI observer runtime
(cli/modules/accessibilityModule.ts), where the hook-scan change was
inert. This ports the same contract into the active v9 path.

- Register hook-lifecycle observers (BEFORE_ALL / BEFORE_EACH /
  AFTER_EACH / AFTER_ALL, PRE + POST). PRE (onHookStart) 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 so
  DOM-changing commands inside hooks trigger scans. POST (onHookEnd)
  clears the uuid so subsequent test-body scans are not mis-stamped.
- Thread currentHookRunUuid through every scan entry point: the web
  per-command commandWrapper and both manual performScan() patches, into
  performScanCli(..., hookRunUuid) -> _getParamsForAppAccessibility,
  which emits thHookRunUuid (dropped when undefined, so in-test and
  lifecycle scans are unchanged). Matches SeleniumHub #14162 appAllyScan
  -> hook_run_uuid.
- Add 6 unit tests for the hook-scan logic in the CLI module.

Verified end-to-end on real BrowserStack sessions (web + Android App
Automate): scans fired inside before/beforeEach/afterEach carry the
correct per-hook uuid; test-body and end-of-test lifecycle scans carry
none.

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

Author: AakashHotchandani

packages/browserstack-service/src/cli/modules/accessibilityModule.ts

@@ -18,6 +18,7 @@ import PerformanceTester from '../../instrumentation/performance/performance-tes
 import * as PERFORMANCE_SDK_EVENTS from '../../instrumentation/performance/constants.js'
 import type { FetchDriverExecuteParamsEventRequest, FetchDriverExecuteParamsEventResponse } from '../../grpc/index.js'
 import { GrpcClient } from '../grpcClient.js'
+import { TestFrameworkConstants } from '../frameworks/constants/testFrameworkConstants.js'
 
 export default class AccessibilityModule extends BaseModule {
 
@@ -34,6 +35,10 @@ export default class AccessibilityModule extends BaseModule {
     LOG_DISABLED_SHOWN: Map<number, boolean>
     testMetadata: Record<string, { [key: string]: unknown; }> = {}
     currentTestName: string | null = null
+    // The run uuid of the hook currently executing (set at hook PRE, cleared at hook POST).
+    // Any scan fired while this is set is stamped with it as thHookRunUuid so the backend
+    // (SeleniumHub appAllyScan → hook_run_uuid) can reconcile the scan onto the wrapping test.
+    currentHookRunUuid: string | null = null
 
     constructor(accessibilityConfig: Accessibility, isNonBstackA11y: boolean) {
         super()
@@ -42,6 +47,13 @@ export default class AccessibilityModule extends BaseModule {
         AutomationFramework.registerObserver(AutomationFrameworkState.CREATE, HookState.POST, this.onBeforeExecute.bind(this))
         TestFramework.registerObserver(TestFrameworkState.TEST, HookState.PRE, this.onBeforeTest.bind(this))
         TestFramework.registerObserver(TestFrameworkState.TEST, HookState.POST, this.onAfterTest.bind(this))
+        // Track the hook window for every hook state the framework supports. PRE captures the
+        // hook's run uuid + opens the scan gate; POST clears the uuid so later test-body scans
+        // are not mis-stamped as hook scans.
+        for (const hookFrameworkState of [TestFrameworkState.BEFORE_ALL, TestFrameworkState.BEFORE_EACH, TestFrameworkState.AFTER_EACH, TestFrameworkState.AFTER_ALL]) {
+            TestFramework.registerObserver(hookFrameworkState, HookState.PRE, this.onHookStart.bind(this))
+            TestFramework.registerObserver(hookFrameworkState, HookState.POST, this.onHookEnd.bind(this))
+        }
         this.accessibility = Boolean(accessibilityConfig)
         const accessibilityOptions = (BrowserstackCLI.getInstance().options as Record<string, unknown>)?.accessibilityOptions as { [key: string]: string | boolean | undefined }
         this.autoScanning = Boolean(accessibilityOptions?.autoScanning ?? true)
@@ -52,6 +64,39 @@ export default class AccessibilityModule extends BaseModule {
         this.isNonBstackA11y = isNonBstackA11y
     }
 
+    async onHookStart(args: Record<string, unknown>) {
+        try {
+            const testInstance: TestFrameworkInstance = (args?.instance as TestFrameworkInstance) || TestFramework.getTrackedInstance()
+            const autoInstance: AutomationFrameworkInstance = AutomationFramework.getTrackedInstance()
+            if (!testInstance || !autoInstance) {
+                return
+            }
+            const sessionId = AutomationFramework.getState(autoInstance, AutomationFrameworkConstants.KEY_FRAMEWORK_SESSION_ID)
+            // KEY_HOOK_ID is stamped on the instance at hook PRE (wdioMochaTestFramework.trackEvent)
+            // and is the SAME uuid reported to TestHub as the hook run, so a scan tagged with it can
+            // be self-joined onto the wrapping test in BTCER.
+            const hookRunUuid = TestFramework.getState(testInstance, TestFrameworkConstants.KEY_HOOK_ID) as string | undefined
+            this.currentHookRunUuid = hookRunUuid || null
+
+            if (!this.accessibility) {
+                return
+            }
+            // Open the scan gate for the hook window so DOM-changing commands issued inside
+            // before/beforeEach/afterEach/after hooks trigger scans (web per-command path). The
+            // following onBeforeTest re-computes the per-test gate, so this only affects the hook.
+            if (this.autoScanning && sessionId !== undefined && sessionId !== null) {
+                this.accessibilityMap.set(sessionId, true)
+            }
+        } catch (error) {
+            this.logger.error(`Exception in accessibility onHookStart: ${error}`)
+        }
+    }
+
+    async onHookEnd() {
+        // Hook finished: subsequent (test-body) scans must not be stamped with the hook uuid.
+        this.currentHookRunUuid = null
+    }
+
     async onBeforeExecute() {
         try {
             const autoInstance: AutomationFrameworkInstance = AutomationFramework.getTrackedInstance()
@@ -116,7 +161,8 @@ export default class AccessibilityModule extends BaseModule {
                 if (!this.accessibility && !this.isAppAccessibility){
                     return
                 }
-                return await this.performScanCli(browser)
+                // If invoked from inside a hook, currentHookRunUuid stamps the scan for the hook.
+                return await this.performScanCli(browser, undefined, this.currentHookRunUuid)
             }
 
             (browser as WebdriverIO.Browser).startA11yScanning = async () => {
@@ -174,7 +220,7 @@ export default class AccessibilityModule extends BaseModule {
                     !this.shouldPatchExecuteScript(args.length ? args[0] as string : null)
                 ) {
                     try {
-                        await this.performScanCli(browser, command.name)
+                        await this.performScanCli(browser, command.name, this.currentHookRunUuid)
                         this.logger.debug(`Accessibility scan performed after ${command.name} command`)
                     } catch (scanError) {
                         this.logger.debug(`Error performing accessibility scan after ${command.name}: ${scanError}`)
@@ -244,7 +290,7 @@ export default class AccessibilityModule extends BaseModule {
                 if (!this.accessibility && !this.isAppAccessibility){
                     return
                 }
-                const results = await this.performScanCli(browser)
+                const results = await this.performScanCli(browser, undefined, this.currentHookRunUuid)
                 if (results){
                     const testIdentifier = String(testInstance.getContext().getId())
                     this.testMetadata[testIdentifier] = {
@@ -387,7 +433,8 @@ export default class AccessibilityModule extends BaseModule {
 
     private async performScanCli(
         browser: WebdriverIO.Browser | WebdriverIO.MultiRemoteBrowser,
-        commandName?: string
+        commandName?: string,
+        hookRunUuid?: string | null
     ): Promise<Record<string, unknown> | undefined> {
         return await PerformanceTester.measureWrapper(
             PERFORMANCE_SDK_EVENTS.A11Y_EVENTS.PERFORM_SCAN,
@@ -400,7 +447,7 @@ export default class AccessibilityModule extends BaseModule {
                     if (this.isAppAccessibility) {
                         const testName=this.currentTestName || undefined
                         const results: unknown = await (browser as WebdriverIO.Browser).execute(
-                            formatString(this.scriptInstance.performScan, JSON.stringify(_getParamsForAppAccessibility(commandName, testName))) as string,
+                            formatString(this.scriptInstance.performScan, JSON.stringify(_getParamsForAppAccessibility(commandName, testName, hookRunUuid))) as string,
                             {}
                         )
                         BStackLogger.debug(util.format(results as string))

packages/browserstack-service/tests/accessibility-handler.test.ts

@@ -468,6 +468,45 @@ describe('beforeHook / afterHook (hook scans)', () => {
         await jasmineHandler.beforeHook({ title: '"before each" hook' } as any, {}, 'hook-uuid-3')
         expect(jasmineHandler['_currentHookRunUuid']).toBeNull()
     })
+
+    it('actually PASSES the hook uuid to performA11yScan for a scan fired inside a hook', async () => {
+        vi.spyOn(utils, 'shouldScanTestForAccessibility').mockReturnValue(true)
+        const scanSpy = vi.spyOn(utils, 'performA11yScan').mockResolvedValue(undefined)
+        // enter a hook window -> sets the scan gate + _currentHookRunUuid
+        await accessibilityHandler.beforeHook(
+            { title: '"before each" hook', parent: 'suite' } as any,
+            { currentTest: { parent: 'suite', title: 'test' } },
+            'hook-uuid-42'
+        )
+        // simulate a wrapped DOM-changing command running inside the hook
+        const orig = vi.fn().mockResolvedValue('ok')
+        await accessibilityHandler['commandWrapper']({ name: 'click', class: 'Element' } as any, undefined as any, orig, 'arg')
+        expect(scanSpy).toHaveBeenCalled()
+        const lastCall = scanSpy.mock.calls[scanSpy.mock.calls.length - 1]
+        // performA11yScan(isAppAutomate, browser, isBS, isA11y, commandName, testName, hookRunUuid)
+        expect(lastCall[lastCall.length - 1]).toBe('hook-uuid-42')
+    })
+
+    it('does NOT stamp a hook uuid on a test-body scan (afterHook cleared it)', async () => {
+        vi.spyOn(utils, 'shouldScanTestForAccessibility').mockReturnValue(true)
+        const scanSpy = vi.spyOn(utils, 'performA11yScan').mockResolvedValue(undefined)
+        await accessibilityHandler.beforeHook(
+            { title: '"before each" hook', parent: 'suite' } as any,
+            { currentTest: { parent: 'suite', title: 'test' } },
+            'hook-uuid-77'
+        )
+        await accessibilityHandler.afterHook() // hook ends -> uuid cleared, gate remains on
+        const orig = vi.fn().mockResolvedValue('ok')
+        await accessibilityHandler['commandWrapper']({ name: 'click', class: 'Element' } as any, undefined as any, orig, 'arg')
+        expect(scanSpy).toHaveBeenCalled()
+        const lastCall = scanSpy.mock.calls[scanSpy.mock.calls.length - 1]
+        expect(lastCall[lastCall.length - 1]).toBeNull()
+    })
+
+    it('_getParamsForAppAccessibility puts the hook uuid on the scan payload as thHookRunUuid', () => {
+        expect(utils._getParamsForAppAccessibility('click', 'testName', 'hook-uuid-9').thHookRunUuid).toBe('hook-uuid-9')
+        expect(utils._getParamsForAppAccessibility('click', 'testName').thHookRunUuid).toBeUndefined()
+    })
 })
 
 describe('beforeTest', () => {

packages/browserstack-service/tests/cli/modules/accessibilityModule.test.ts

@@ -51,7 +51,7 @@ vi.mock('../../../src/cli/grpcClient.js', () => ({
 }))
 
 import AccessibilityModule from '../../../src/cli/modules/accessibilityModule.js'
-import { validateCapsWithA11y, validateCapsWithAppA11y } from '../../../src/util.js'
+import { validateCapsWithA11y, validateCapsWithAppA11y, _getParamsForAppAccessibility } from '../../../src/util.js'
 import accessibilityScripts from '../../../src/scripts/accessibility-scripts.js'
 import TestFramework from '../../../src/cli/frameworks/testFramework.js'
 import AutomationFramework from '../../../src/cli/frameworks/automationFramework.js'
@@ -443,4 +443,71 @@ describe('AccessibilityModule', () => {
             )
         })
     })
+
+    // APPA11Y-5542: scans fired inside test hooks must carry the hook's run uuid
+    // (thHookRunUuid) so the backend (SeleniumHub appAllyScan -> hook_run_uuid) can
+    // reconcile them onto the wrapping test. onHookStart captures the uuid + opens the
+    // scan gate for the hook window; onHookEnd clears it so test-body scans are unstamped.
+    describe('onHookStart / onHookEnd (hook scans)', () => {
+        it('registers hook observers for every hook lifecycle state (PRE + POST)', () => {
+            for (const state of [
+                TestFrameworkState.BEFORE_ALL,
+                TestFrameworkState.BEFORE_EACH,
+                TestFrameworkState.AFTER_EACH,
+                TestFrameworkState.AFTER_ALL
+            ]) {
+                expect(TestFramework.registerObserver).toHaveBeenCalledWith(state, HookState.PRE, expect.any(Function))
+                expect(TestFramework.registerObserver).toHaveBeenCalledWith(state, HookState.POST, expect.any(Function))
+            }
+        })
+
+        it('captures the hook run uuid and opens the scan gate at hook start', async () => {
+            vi.mocked(TestFramework.getState).mockReturnValue('hook-uuid-123')
+            vi.mocked(AutomationFramework.getState).mockImplementation((instance: any, key: string) =>
+                (key.includes('session_id') ? 12345 : {}) as any)
+
+            await accessibilityModule.onHookStart({ instance: mockTestInstance } as any)
+
+            expect(accessibilityModule.currentHookRunUuid).toBe('hook-uuid-123')
+            expect(accessibilityModule.accessibilityMap.get(12345)).toBe(true)
+        })
+
+        it('does not open the scan gate when accessibility is disabled', async () => {
+            accessibilityModule.accessibility = false
+            vi.mocked(TestFramework.getState).mockReturnValue('hook-uuid-123')
+
+            await accessibilityModule.onHookStart({ instance: mockTestInstance } as any)
+
+            expect(accessibilityModule.currentHookRunUuid).toBe('hook-uuid-123')
+            expect(accessibilityModule.accessibilityMap.get(12345)).toBeUndefined()
+        })
+
+        it('clears the hook run uuid at hook end so later test-body scans are unstamped', async () => {
+            accessibilityModule.currentHookRunUuid = 'hook-uuid-123'
+
+            await accessibilityModule.onHookEnd()
+
+            expect(accessibilityModule.currentHookRunUuid).toBeNull()
+        })
+
+        it('threads the hook run uuid into the app scan payload (thHookRunUuid)', async () => {
+            accessibilityModule.accessibility = true
+            accessibilityModule.isAppAccessibility = true
+            mockBrowser.execute.mockResolvedValue({ scanned: true })
+
+            await (accessibilityModule as any).performScanCli(mockBrowser, 'click', 'hook-uuid-99')
+
+            expect(_getParamsForAppAccessibility).toHaveBeenCalledWith('click', undefined, 'hook-uuid-99')
+        })
+
+        it('passes no hook uuid for an ordinary (non-hook) app scan', async () => {
+            accessibilityModule.accessibility = true
+            accessibilityModule.isAppAccessibility = true
+            mockBrowser.execute.mockResolvedValue({ scanned: true })
+
+            await (accessibilityModule as any).performScanCli(mockBrowser, 'click')
+
+            expect(_getParamsForAppAccessibility).toHaveBeenCalledWith('click', undefined, undefined)
+        })
+    })
 })