feat(browser): export aria tree utils

docs/api/browser/context.md

@@ -270,6 +270,17 @@ export const utils: {
    * Creates "Cannot find element" error. Useful for custom locators.
    */
   getElementError(selector: string, container?: Element): Error
+  /**
+   * Utilities for generating and working with ARIA trees and templates.
+   * @experimental
+   */
+  aria: {
+    generateAriaTree(rootElement: Element): AriaNode
+    renderAriaTree(root: AriaNode): string
+    renderAriaTemplate(template: AriaTemplateNode): string
+    parseAriaTemplate(text: string): AriaTemplateNode
+    matchAriaTree(root: AriaNode, template: AriaTemplateNode): { pass: boolean; resolved: string }
+  }
 }
 ```
 
@@ -340,3 +351,22 @@ utils.configurePrettyDOM({
 ::: tip
 This feature is inspired by Testing Library's [`defaultIgnore`](https://testing-library.com/docs/dom-testing-library/api-configuration/#defaultignore) configuration.
 :::
+
+### aria <Version type="experimental">5.0.0</Version> {#aria}
+
+The `aria` namespace exposes low-level utilities used by Vitest's ARIA snapshot matchers.
+
+```ts
+import { utils } from 'vitest/browser'
+
+document.body.innerHTML = `
+  <h1>Hello, World!</h1>
+  <button aria-hidden="true">Hidden</button>
+  <button>Visible</button>
+`
+const tree = utils.aria.generateAriaTree(document.body)
+const yaml = utils.aria.renderAriaNode(tree)
+console.log(yaml)
+// - heading "Hello, World!" [level=1]
+// - button "Visible""
+```

docs/guide/browser/aria-snapshots.md

@@ -30,6 +30,8 @@ await expect.element(page.getByRole('navigation')).toMatchAriaInlineSnapshot(`
 
 This catches accessibility regressions: missing labels, broken roles, incorrect heading levels, and more — things that DOM snapshots would miss. Even if the underlying HTML structure changes, the assertion would not fail as long as content matches semantically.
 
+For advanced cases, you can also generate and inspect the ARIA tree through `utils.aria` from `vitest/browser`. See the [Context API](/api/browser/context#aria) for details.
+
 ## Snapshot Workflow
 
 ARIA snapshots use the same Vitest snapshot workflow as other snapshot assertions. File snapshots, inline snapshots, `--update` / `-u`, watch mode updates, and CI snapshot behavior all work the same way.

packages/browser/context.d.ts

@@ -2,6 +2,7 @@ import { SerializedConfig } from 'vitest'
 import { StringifyOptions, CDPSession, BrowserCommands } from 'vitest/internal/browser'
 import { ARIARole } from './aria-role.js'
 import {} from './matchers.js'
+import { __ivyaAriaTypes } from '@vitest/browser/internal/vendor-types'
 
 export type BufferEncoding =
   | 'ascii'
@@ -934,6 +935,23 @@ export const utils: {
    * Creates "Cannot find element" error. Useful for custom locators.
    */
   getElementError(selector: string, container?: Element): Error
+
+  /**
+   * Utilities for generating and working with ARIA trees and templates.
+   * @experimental
+   */
+  aria: {
+    /** Captures the ARIA tree for a DOM subtree. */
+    generateAriaTree: typeof __ivyaAriaTypes.generateAriaTree
+    /** Renders a captured ARIA tree to the textual snapshot format. */
+    renderAriaTree: typeof __ivyaAriaTypes.renderAriaTree
+    /** Renders an ARIA template back to text. */
+    renderAriaTemplate: typeof __ivyaAriaTypes.renderAriaTemplate
+    /** Parses textual ARIA snapshot syntax into a template tree. */
+    parseAriaTemplate: typeof __ivyaAriaTypes.parseAriaTemplate
+    /** Matches a captured ARIA tree against a parsed template. */
+    matchAriaTree: typeof __ivyaAriaTypes.matchAriaTree
+  }
 }
 
 export const locators: BrowserLocators

packages/browser/package.json

@@ -44,6 +44,10 @@
     "./utils": {
       "default": "./dummy.js"
     },
+    "./internal/vendor-types": {
+      "types": "./dist/vendor-types.d.ts",
+      "default": "./dummy.js"
+    },
     "./package.json": "./package.json"
   },
   "main": "./dist/index.js",

packages/browser/rollup.config.js

@@ -157,4 +157,36 @@ export default () =>
       external,
       plugins: dtsUtilsClient.dts(),
     },
+    {
+      input: {
+        'vendor-types': './src/vendor-types.ts',
+      },
+      output: {
+        dir: 'dist',
+        entryFileNames: '[name].ts',
+        format: 'esm',
+      },
+      external,
+      plugins: [
+        ...dtsUtils.isolatedDecl(),
+        ...plugins,
+      ],
+    },
+    {
+      input: {
+        'vendor-types': './dist/.types/vendor-types.d.ts',
+      },
+      output: {
+        dir: 'dist',
+        entryFileNames: '[name].d.ts',
+        format: 'esm',
+      },
+      external,
+      plugins: [
+        resolve({
+          preferBuiltins: true,
+        }),
+        dtsUtils.dts(),
+      ],
+    },
   ])

packages/browser/src/client/tester/aria.ts

@@ -4,14 +4,19 @@ import type {
   AriaNode,
   AriaTemplateNode,
 } from 'ivya/aria'
-import {
+import * as aria from 'ivya/aria'
+import { Snapshots } from 'vitest'
+import { getBrowserState } from '../utils'
+
+getBrowserState().aria = aria
+
+const {
   generateAriaTree,
   matchAriaTree,
   parseAriaTemplate,
   renderAriaTemplate,
   renderAriaTree,
-} from 'ivya/aria'
-import { Snapshots } from 'vitest'
+} = aria
 
 const ariaSnapshotAdapter: DomainSnapshotAdapter<AriaNode, AriaTemplateNode> = {
   name: 'aria',

packages/browser/src/client/tester/context.ts

@@ -556,4 +556,7 @@ export const utils = {
   debug,
   getElementLocatorSelectors,
   configurePrettyDOM,
+  get aria() {
+    return getBrowserState().aria
+  },
 }

packages/browser/src/client/utils.ts

@@ -95,6 +95,7 @@ export interface BrowserRunnerState {
     send: (method: string, params?: Record<string, unknown>) => Promise<unknown>
     emit: (event: string, payload: unknown) => void
   }
+  aria: typeof import('ivya/aria')
 }
 
 /* @__NO_SIDE_EFFECTS__ */

packages/browser/src/vendor-types.ts

@@ -0,0 +1 @@
+export type * as __ivyaAriaTypes from 'ivya/aria'

test/browser/test/utils.test.ts

@@ -206,3 +206,17 @@ test('filterNode with wildcard selector filters nested content', async () => {
     </div>"
   `)
 })
+
+test('aria tree utils', () => {
+  document.body.innerHTML = `
+    <h1>Hello, World!</h1>
+    <button aria-hidden="true">Hidden</button>
+    <button>Visible</button>
+  `
+  const { generateAriaTree, renderAriaTree } = utils.aria
+  expect(`\n${renderAriaTree(generateAriaTree(document.body))}`).toMatchInlineSnapshot(`
+    "
+    - heading "Hello, World!" [level=1]
+    - button "Visible""
+  `)
+})

tsconfig.base.json

@@ -23,6 +23,7 @@
       "@vitest/browser-playwright": ["./packages/browser-playwright/src/index.ts"],
       "@vitest/browser": ["./packages/browser/src/node/index.ts"],
       "@vitest/browser/client": ["./packages/browser/src/client/client.ts"],
+      "@vitest/browser/internal/vendor-types": ["./packages/browser/src/vendor-types.ts"],
       "~/*": ["./packages/ui/client/*"],
       "vitest": ["./packages/vitest/src/public/index.ts"],
       "vitest/internal/browser": ["./packages/vitest/src/public/browser.ts"],