{"record":{"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/1fa9837ec26533512fdcad8baebf249771bd340a/packages/browser/src/client/tester/aria.ts#L13-L49","documentation":"The aria snapshot adapter's capture() method only accepts a DOM Element. Vitest throws this TypeError when the matcher backing toMatchAriaSnapshot receives something that is not an Element instance (e.g. a Locator, a Document, a plain object, or null). Internally generateAriaTree walks the DOM, so any non-Element input is rejected before tree generation begins.","triggerScenarios":"Calling expect(locator).toMatchAriaSnapshot(...) where locator is a Vitest Locator that has not been resolved to an Element; passing document or window to an aria snapshot matcher; passing null/undefined to the aria adapter's capture; calling the aria adapter directly with a serialized/stale node reference.","commonSituations":"Using the aria snapshot API with a Locator object instead of resolving it via .element(); running in an environment where the DOM node was detached/removed before capture; passing the result of querySelector that returned null; SSR or jsdom contexts where Element is not the same constructor as the one in the captured node.","solutions":["Resolve the Locator to an Element before passing it: use await locator.element() or await page.elementLocator(...).element().","Ensure the value is a real Element via document.querySelector(...) and check for null before the matcher.","If calling the adapter programmatically, guard with `value instanceof Element` before invoking capture().","Re-query the DOM if the node may have been detached since it was first obtained."],"exampleFix":"// before\nexpect(locator).toMatchAriaSnapshot(`- button \"Save\"`)\n// after\nexpect(await locator.element()).toMatchAriaSnapshot(`- button \"Save\"`)","handlingStrategy":"type-guard","validationCode":"if (!(value instanceof Element)) {\n  throw new Error('aria snapshot requires an Element')\n}\nexpect(value).toMatchAriaSnapshot(template)","typeGuard":"function isElement(value: unknown): value is Element {\n  return typeof Element !== 'undefined' && value instanceof Element\n}","tryCatchPattern":"try {\n  expect(await locator.element()).toMatchAriaSnapshot(template)\n} catch (e) {\n  if (e instanceof TypeError && /aria adapter expects an Element/.test(e.message)) {\n    // resolve the locator and retry\n  } else throw e\n}","preventionTips":["Always resolve Locators via await locator.element() before aria snapshot matchers.","Type your helper inputs as Element rather than Element | Locator where possible.","Add a runtime instanceof Element guard in shared assertion utilities."],"tags":["browser","aria","snapshot","dom","type-guard"],"backgroundTag":null,"analyzedSha":"1fa9837ec26533512fdcad8baebf249771bd340a","analyzedAt":"2026-08-11T16:11:39.638Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}