vitest-dev/vitest · error · TypeError

aria adapter expects an Element

Error message

aria adapter expects an Element

What it means

Thrown by the aria snapshot adapter's capture() when the value passed to toMatchAriaSnapshot / toMatchAriaInlineSnapshot is not a DOM Element. The adapter calls ivya's generateAriaTree(received), which requires a real DOM node to walk; passing a Locator, string, or null produces a TypeError before any snapshot comparison runs.

Source

Thrown at packages/browser/src/client/tester/aria.ts:31

getBrowserState().aria = aria

const {
  generateAriaTree,
  matchAriaTree,
  parseAriaTemplate,
  renderAriaTemplate,
  renderAriaTree,
} = aria

const ariaSnapshotAdapter: DomainSnapshotAdapter<AriaNode, AriaTemplateNode> = {
  name: 'aria',

  capture(received) {
    if (received instanceof Element) {
      return generateAriaTree(received)
    }
    throw new TypeError('aria adapter expects an Element')
  },

  render(captured) {
    return wrapNewlines(renderAriaTree(captured))
  },

  parseExpected(input) {
    // increase limit so that yaml parse error can reach `toMatchAriaSnapshot` callsite in user test files
    const limit = Error.stackTraceLimit
    Error.stackTraceLimit = limit + 20
    try {
      return parseAriaTemplate(input.trim())
    }
    finally {
      Error.stackTraceLimit = limit
    }
  },

View on GitHub (pinned to d568f8ce37)

Solutions

1. Pass a resolved DOM Element: call .element() on a Locator, or query the node first.
2. If you only have a Locator, resolve it inside expect: expect(await locator.element()).toMatchAriaSnapshot(...).
3. Guard for null: const el = document.querySelector('.x'); if (el) expect(el).toMatchAriaSnapshot(...).

Example fix

// before
expect(page.getByRole('button')).toMatchAriaSnapshot('button')
// after
expect(page.getByRole('button').element()).toMatchAriaSnapshot('button')

import type { Locator } from 'vitest/browser'
const isElement = (v: unknown): v is Element => v instanceof Element
const target = locatorOrEl
const el = isElement(target) ? target : (target as Locator).element?.()
if (isElement(el)) {
  expect(el).toMatchAriaSnapshot('button')
}

function isElementOrNull(v: unknown): v is Element {
  return v == null || v instanceof Element
}

When it happens

Trigger: Calling expect(locator).toMatchAriaSnapshot(...), expect('<div>...</div>'), or expect(null).toMatchAriaSnapshot(...) — i.e. passing anything other than an Element instance to the aria matchers defined at packages/browser/src/client/tester/aria.ts:69-75.

Common situations: Passing a Vitest Locator instead of an element (expect(locator) instead of expect(locator.element())), passing an HTML string, or passing a wrapper object from a component test framework. Also happens when a query returns null and the null is forwarded to the matcher.

Related errors

• Expecting a valid DOM element, but got ${typeName}.
• Element not found: ${v.element}
• Invalid element or locator: ${elementOrLocator}. Expected an
• .toContainHTML() expects a string value, got ${htmlText}
• .toHaveDisplayValue() currently supports only input, textare

AI-assisted analysis of vitest-dev/vitest@d568f8ce37 (2026-08-03). Data as JSON: /data/errors/c33516232eb96767.json. Report an issue: GitHub.