feat(browser): export aria tree utils by hi-ogawa · Pull Request #10171 · vitest-dev/vitest

hi-ogawa · 2026-04-22T05:36:22Z

Description

(marginally) related toMatchAriaInlineSnapshot cannot match empty aria trees #10158

This PR exposes ivya/aria exports via import { utils } from "vitest/browser". This can be useful as a standalone primitive of "node to aria tree" serialization similar to prettyDOM does for "ndoe to html like" serialization.

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""

The wiring is a bit mess like __INTERNAL and @vitest/browser/internal/vendor-types, but seems necessary to avoid duplicating modules and also hand-rolling same type definition. For example, I noticed type AriaRole is currently manually written in packages/browser/aria-role.d.ts but this can also come from ivya with similar tricks.

Please don't delete this checklist! Before submitting the PR, please make sure you do the following:

It's really useful if your PR references an issue where it is discussed ahead of time. If the feature is substantial or introduces breaking changes without a discussion, PR might be closed.
Ideally, include a test that fails without this PR but passes with it.
Please, don't make changes to pnpm-lock.yaml unless you introduce a new test example.
Please check Allow edits by maintainers to make review process faster. Note that this option is not available for repositories that are owned by Github organizations.

Tests

Run the tests with pnpm test:ci.

Documentation

If you introduce new functionality, document it. You can run documentation with pnpm run docs command.

Changesets

Changes in changelog are generated from PR name. Please, make sure that it explains your changes in an understandable manner. Please, prefix changeset messages with feat:, fix:, perf:, docs:, or chore:.

netlify · 2026-04-22T05:51:54Z

✅ Deploy Preview for vitest-dev ready!

Built without sensitive environment variables

Name	Link
🔨 Latest commit	`a69091c`
🔍 Latest deploy log	https://app.netlify.com/projects/vitest-dev/deploys/69e8635bf7b2780008818572
😎 Deploy Preview	https://deploy-preview-10171--vitest-dev.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify project configuration.

pkg-pr-new · 2026-04-22T06:06:25Z

@vitest/browser

npm i https://pkg.pr.new/@vitest/browser@10171

@vitest/browser-playwright

npm i https://pkg.pr.new/@vitest/browser-playwright@10171

@vitest/browser-preview

npm i https://pkg.pr.new/@vitest/browser-preview@10171

@vitest/browser-webdriverio

npm i https://pkg.pr.new/@vitest/browser-webdriverio@10171

@vitest/coverage-istanbul

npm i https://pkg.pr.new/@vitest/coverage-istanbul@10171

@vitest/coverage-v8

npm i https://pkg.pr.new/@vitest/coverage-v8@10171

@vitest/expect

npm i https://pkg.pr.new/@vitest/expect@10171

@vitest/mocker

npm i https://pkg.pr.new/@vitest/mocker@10171

@vitest/pretty-format

npm i https://pkg.pr.new/@vitest/pretty-format@10171

@vitest/runner

npm i https://pkg.pr.new/@vitest/runner@10171

@vitest/snapshot

npm i https://pkg.pr.new/@vitest/snapshot@10171

@vitest/spy

npm i https://pkg.pr.new/@vitest/spy@10171

@vitest/ui

npm i https://pkg.pr.new/@vitest/ui@10171

@vitest/utils

npm i https://pkg.pr.new/@vitest/utils@10171

vitest

npm i https://pkg.pr.new/vitest@10171

@vitest/web-worker

npm i https://pkg.pr.new/@vitest/web-worker@10171

@vitest/ws-client

npm i https://pkg.pr.new/@vitest/ws-client@10171

commit: 633fdbd

hi-ogawa · 2026-04-22T06:24:50Z

+  /**
+   * 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
+  }


Typescript couldn't infer jsdoc from the original ivya/aria exports (likely due to dts bundling), so I wrote up it manually by partially duplicating the ones in ivya.

AriPerkkio

Looks good, this will allow users to use a11y tree utils without having to install another ivya next to the bundled one.

AriPerkkio · 2026-04-22T07:00:40Z

+  get aria() {
+    return __INTERNAL._aria
+  },


What exactly does this work-around fix? Why not import { aria } from "./aria" and return that here?

There's some weird @vitest/browser client bundle split and we have tester/context.ts and tester/expect-element.ts independently built without sharing chunks. Previously ivya/aria lived only in expect-element bundle, but this one now needs to be available from context.ts, so it's passed through __INTERNAL global.

There's other globals that are passed around like __vitest_browser_runner__, but haven't fully understood what is for what.

JReinhold · 2026-04-22T07:57:20Z

This is pretty awesome! How does it compare to Playwright's mode: 'ai' | 'default' option? https://playwright.dev/docs/api/class-page#page-aria-snapshot

Where the AI mode also captures iframe's contents and adds unique references to each element.

hi-ogawa · 2026-04-22T08:06:49Z

This is pretty awesome! How does it compare to Playwright's mode: 'ai' | 'default' option? https://playwright.dev/docs/api/class-page#page-aria-snapshot

Where the AI mode also captures iframe's contents and adds unique references to each element.

Our implementation is stripped down port and AI part isn't included. https://github.com/vitest-dev/ivya/blob/7d84867d3576ac9c7342299e552d3c78a60a272b/src/aria/folk/injected/ariaSnapshot.ts#L17-L20

It's expected to exactly match with their default mode though haven't verified. I haven't looked into beyond what's needed for Vitest's toMatchAriaSnapshot. If it's useful as standalone or relevant to snapshot feature, we can probably try supporting that too.

hi-ogawa added 6 commits April 22, 2026 13:06

feat: export aria tree utils

6960106

wip: add vendor-types

c833570

chore: hack root tsc paths

ed6ee88

docs

64cd094

test: add test

9fc20e7

todo

6b8eea0

hi-ogawa mentioned this pull request Apr 22, 2026

feat: export AriaRole type and add aria tree API jsdoc vitest-dev/ivya#15

Draft

docs

1f4d4a4

hi-ogawa added 2 commits April 22, 2026 14:56

docs

459f7cf

cleanup

a69091c

hi-ogawa added the cr-tracked label Apr 22, 2026

hi-ogawa added 2 commits April 22, 2026 15:18

docs: add jsdoc

61d57ca

chore: cleanup

07a6fe2

hi-ogawa commented Apr 22, 2026

View reviewed changes

hi-ogawa requested a review from AriPerkkio April 22, 2026 06:40

hi-ogawa marked this pull request as ready for review April 22, 2026 06:40

AriPerkkio previously approved these changes Apr 22, 2026

View reviewed changes

refactor: use getBrowserState

633fdbd

hi-ogawa dismissed AriPerkkio’s stale review via 633fdbd April 22, 2026 07:59

AriPerkkio approved these changes Apr 22, 2026

View reviewed changes

sheremet-va merged commit c342301 into vitest-dev:main Apr 23, 2026
17 checks passed

hi-ogawa deleted the feat-export-aria-tree-utils branch April 23, 2026 09:13

github-actions Bot locked and limited conversation to collaborators Aug 5, 2026

Navigation Menu

Uh oh!

feat(browser): export aria tree utils - #10171

feat(browser): export aria tree utils#10171
sheremet-va merged 12 commits into
vitest-dev:mainfrom
hi-ogawa:feat-export-aria-tree-utils

hi-ogawa commented Apr 22, 2026 •

edited

Loading

Uh oh!

netlify Bot commented Apr 22, 2026 •

edited

Loading

Uh oh!

pkg-pr-new Bot commented Apr 22, 2026 •

edited

Loading

Uh oh!

hi-ogawa Apr 22, 2026

Uh oh!

AriPerkkio left a comment

Uh oh!

AriPerkkio Apr 22, 2026

Uh oh!

hi-ogawa Apr 22, 2026

Uh oh!

JReinhold commented Apr 22, 2026

Uh oh!

hi-ogawa commented Apr 22, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

Uh oh!

Conversation

hi-ogawa commented Apr 22, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Please don't delete this checklist! Before submitting the PR, please make sure you do the following:

Tests

Documentation

Changesets

Uh oh!

netlify Bot commented Apr 22, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

✅ Deploy Preview for vitest-dev ready!

Uh oh!

pkg-pr-new Bot commented Apr 22, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

hi-ogawa Apr 22, 2026

Choose a reason for hiding this comment

Uh oh!

AriPerkkio left a comment

Choose a reason for hiding this comment

Uh oh!

AriPerkkio Apr 22, 2026

Choose a reason for hiding this comment

Uh oh!

hi-ogawa Apr 22, 2026

Choose a reason for hiding this comment

Uh oh!

JReinhold commented Apr 22, 2026

Uh oh!

hi-ogawa commented Apr 22, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

hi-ogawa commented Apr 22, 2026 •

edited

Loading

netlify Bot commented Apr 22, 2026 •

edited

Loading

pkg-pr-new Bot commented Apr 22, 2026 •

edited

Loading