{"record":{"id":"7651d01eebb0e9b8","repo":"vitest-dev/vitest","slug":"received-value-must-an-htmlelement-or-an-svgelemen","errorCode":null,"errorMessage":"received value must an HTMLElement or an SVGElement or a Locator that returns an HTMLElement or an SVGElement.","messagePattern":"received value must an HTMLElement or an SVGElement or a Locator that returns an HTMLElement or an SVGElement\\.","errorType":"exception","errorClass":"UserInputElementTypeError","httpStatus":null,"severity":"error","filePath":"packages/browser/src/client/tester/expect/utils.ts","lineNumber":55,"sourceCode":"  elementOrLocator: Element | Locator | null,\n  // TODO: minifier doesn't keep names, so we need to update this\n  matcherFn: (...args: any) => any,\n  context: MatcherState,\n): HTMLElement | SVGElement {\n  if (elementOrLocator instanceof Locator) {\n    elementOrLocator = elementOrLocator.element()\n  }\n\n  const defaultView = elementOrLocator?.ownerDocument?.defaultView || window\n\n  if (\n    elementOrLocator instanceof defaultView.HTMLElement\n    || elementOrLocator instanceof defaultView.SVGElement\n  ) {\n    return elementOrLocator\n  }\n\n  throw new UserInputElementTypeError(\n    elementOrLocator,\n    matcherFn,\n    context,\n  )\n}\n\nexport function getNodeFromUserInput(\n  elementOrLocator: Element | Locator,\n  matcherFn: (...args: any) => any,\n  context: MatcherState,\n): Node {\n  if (elementOrLocator instanceof Locator) {\n    elementOrLocator = elementOrLocator.element()\n  }\n\n  const defaultView = elementOrLocator.ownerDocument?.defaultView || window\n\n  if (","sourceCodeStart":37,"sourceCodeEnd":73,"githubUrl":"https://github.com/vitest-dev/vitest/blob/1fa9837ec26533512fdcad8baebf249771bd340a/packages/browser/src/client/tester/expect/utils.ts#L37-L73","documentation":"Thrown by `getElementFromUserInput` (as `UserInputElementTypeError`, a `GenericTypeError` subclass) when the value passed to an element-based matcher is neither an `HTMLElement`, an `SVGElement`, nor a `Locator` that resolves to one. The helper first unwraps a `Locator` via `.element()`, then checks `instanceof defaultView.HTMLElement || instanceof defaultView.SVGElement`; anything else (Document, Window, string, number, null, plain object, a Node that is not an Element) is rejected. The resulting message is the matcher-specific 'received value must … or a Locator that returns …' string.","triggerScenarios":"Passing a CSS selector string instead of an element/Locator; passing `document` or `window`; passing the result of `querySelectorAll` (a NodeList); passing null/undefined; passing an element from a different document whose `defaultView` differs.","commonSituations":"Confusing `@testing-library`-style string selectors with Vitest browser matchers (which need a Locator); passing a detached or cross-frame element; refactor that swapped an element for its wrapper object.","solutions":["Use a Locator: `expect(page.getByRole('button')).toBeVisible()` instead of passing a selector string.","If you have a raw DOM node, ensure it is an Element (e.g. `document.querySelector('#x')`) and not a Document/NodeList.","For elements from iframes, pass the iframe's content element directly or build a Locator scoped to the iframe."],"exampleFix":"// before\nexpect('#submit').toBeVisible()\n\n// after\nexpect(page.getByRole('button', { name: 'Submit' })).toBeVisible()","handlingStrategy":"type-guard","validationCode":"function isElementOrLocator(v: unknown): v is Element | Locator {\n  return v instanceof Element || (!!v && typeof v === 'object' && Symbol.for('$$vitest:locator') in v)\n}\nif (!isElementOrLocator(target)) throw new TypeError('pass an Element or Locator')\nexpect(target).toBeVisible()","typeGuard":"function isElementOrLocator(v: unknown): v is Element | Locator {\n  return v instanceof Element\n    || (!!v && typeof v === 'object' && Symbol.for('$$vitest:locator') in (v as object))\n}","tryCatchPattern":null,"preventionTips":["Pass Element or Locator values, never selector strings.","Use `page.getByRole(...)` / `page.locator(...)` to build Locators.","Resolve `querySelector` results and null-check before passing."],"tags":["matcher","argument-validation","browser","locator","dom"],"backgroundTag":null,"analyzedSha":"1fa9837ec26533512fdcad8baebf249771bd340a","analyzedAt":"2026-08-11T16:11:39.638Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}