{"id":"c33516232eb96767","repo":"vitest-dev/vitest","slug":"aria-adapter-expects-an-element","errorCode":null,"errorMessage":"aria adapter expects an Element","messagePattern":"aria adapter expects an Element","errorType":"exception","errorClass":"TypeError","httpStatus":null,"severity":"error","filePath":"packages/browser/src/client/tester/aria.ts","lineNumber":31,"sourceCode":"\ngetBrowserState().aria = aria\n\nconst {\n  generateAriaTree,\n  matchAriaTree,\n  parseAriaTemplate,\n  renderAriaTemplate,\n  renderAriaTree,\n} = aria\n\nconst ariaSnapshotAdapter: DomainSnapshotAdapter<AriaNode, AriaTemplateNode> = {\n  name: 'aria',\n\n  capture(received) {\n    if (received instanceof Element) {\n      return generateAriaTree(received)\n    }\n    throw new TypeError('aria adapter expects an Element')\n  },\n\n  render(captured) {\n    return wrapNewlines(renderAriaTree(captured))\n  },\n\n  parseExpected(input) {\n    // increase limit so that yaml parse error can reach `toMatchAriaSnapshot` callsite in user test files\n    const limit = Error.stackTraceLimit\n    Error.stackTraceLimit = limit + 20\n    try {\n      return parseAriaTemplate(input.trim())\n    }\n    finally {\n      Error.stackTraceLimit = limit\n    }\n  },\n","sourceCodeStart":13,"sourceCodeEnd":49,"githubUrl":"https://github.com/vitest-dev/vitest/blob/d568f8ce3739b532d5bf2c1ee1e45e8a8a473d09/packages/browser/src/client/tester/aria.ts#L13-L49","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Pass a resolved DOM Element: call .element() on a Locator, or query the node first.","If you only have a Locator, resolve it inside expect: expect(await locator.element()).toMatchAriaSnapshot(...).","Guard for null: const el = document.querySelector('.x'); if (el) expect(el).toMatchAriaSnapshot(...)."],"exampleFix":"// before\nexpect(page.getByRole('button')).toMatchAriaSnapshot('button')\n// after\nexpect(page.getByRole('button').element()).toMatchAriaSnapshot('button')","handlingStrategy":"type-guard","validationCode":"import type { Locator } from 'vitest/browser'\nconst isElement = (v: unknown): v is Element => v instanceof Element\nconst target = locatorOrEl\nconst el = isElement(target) ? target : (target as Locator).element?.()\nif (isElement(el)) {\n  expect(el).toMatchAriaSnapshot('button')\n}","typeGuard":"function isElementOrNull(v: unknown): v is Element {\n  return v == null || v instanceof Element\n}","tryCatchPattern":null,"preventionTips":["Always resolve a Locator to an Element via .element() before passing to aria snapshot matchers.","Type the helper parameter as Element, not unknown, so the compiler catches misuse."],"tags":["browser","aria","snapshot","dom","type-error"],"analyzedSha":"d568f8ce3739b532d5bf2c1ee1e45e8a8a473d09","analyzedAt":"2026-08-03T20:23:56.861Z","schemaVersion":2}