Evaluate dom-accessibility-api for webview accessibility regression testing

Purpose

Consider dom-accessibility-api when improving the webview testing infrastructure. This is a deferred evaluation, not a commitment to adopt the dependency and not a blocker for PR #895. The operator has completed and accepted increment 4's manual tests.

Background

PR #895 extracts reusable Fluent webview components. Increment 4 introduced FocusableBadge and aligned its accessible-name/description contract with MetricCard:

• Visible badge content or metric label/value nodes supply the accessible name through aria-labelledby.
• Tooltip explanations supply supplementary descriptions through aria-describedby.
• Badge focusability preserves the mixed-list tab order; metric cards remain focusable.

The current Jest/jsdom tests assert emitted attributes and DOM relationships. Before/after Chrome accessibility-tree measurements confirmed the computed results, but those measurements were a one-off check rather than committed automated coverage. Earlier measurements exposed both duplicated name/description content and summary cells with no accessible name.

dom-accessibility-api provides computeAccessibleName() and computeAccessibleDescription(), allowing tests to assert the resulting strings instead of only the presence of ARIA attributes. It does not simulate screen-reader speech, keyboard interaction or visual focus indicators.

Evaluation scope

• Compare representative results from dom-accessibility-api in the existing Jest/jsdom setup with Chrome's accessibility tree before relying on the library as a test oracle. Include hidden/referenced Fluent tooltip content and generated IDs.
• Pilot assertions on FocusableBadge and both filled/subtle MetricCard appearances: meaningful names, supplementary descriptions, and no unintended repetition.
• Include tooltip/no-tooltip cases, truncated values, mixed focusable/non-focusable badges, rich tooltips, and metric loading/unavailable/zero-value states where relevant.
• Decide whether a small shared test helper is useful, following the existing renderSurface conventions rather than introducing a separate framework.
• Evaluate dependency placement, supported Node/toolchain versions and lockfile impact. Do not add the dependency as an incidental change.
• Define which guarantees belong in unit tests, browser tests and manual screen-reader checks. Keep keyboard/ref integration and focus-ring checks separate from name computation.

Completion criteria

• Record a recommendation to adopt or defer, with evidence and limitations.
• Compare browser and jsdom computed results for representative Fluent components; document discrepancies.
• If adopted, add the dependency deliberately and commit focused computed-name/description regression tests.
• Document the testing pattern and remaining browser/manual responsibilities.

A substring check alone is not proof of correct announcements: missing names, lost labels/values and legitimate partial overlap must also be considered. Passing these tests must not be reported as a real screen-reader pass.

References

• PR #895
• docs/ai-and-plans/features/webview-fluentui-package/iterations/04-focusable-badge-and-accessible-names.md
• packages/vscode-ext-webview-fluentui/src/components/FocusableBadge/FocusableBadge.test.tsx
• packages/vscode-ext-webview-fluentui/src/components/MetricGrid/MetricCard.test.tsx
• Related but distinct: #818 (audit of existing accessibility patterns, not testing infrastructure)
• Library: https://github.com/eps1lon/dom-accessibility-api

Start by reading the FocusableBadge and MetricCard test files and the increment 4 plan referenced in the issue. Run the existing Jest/jsdom tests, then compare representative computed names and descriptions with Chrome accessibility-tree results, including the listed tooltip and state cases. Done means recording an adopt/defer recommendation, discrepancies, testing boundaries, and focused tests or documentation if adopted.