{"id":"c503fc1daf79dd1c","repo":"vitest-dev/vitest","slug":"received-value-must-expectedstring-or-a-locator","errorCode":null,"errorMessage":"received value must ${expectedString} or a Locator that returns ${expectedString}.","messagePattern":"received value must (.+?) or a Locator that returns (.+?)\\.","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/d568f8ce3739b532d5bf2c1ee1e45e8a8a473d09/packages/browser/src/client/tester/expect/utils.ts#L37-L73","documentation":"Thrown via the `UserInputElementTypeError` class (utils.ts:55, 192-200) which subclasses `GenericTypeError` with the expected string `'an HTMLElement or an SVGElement'`. It fires from `getElementFromUserInput` (utils.ts:42-60) when the resolved value is neither an `HTMLElement` nor an `SVGElement` of its owner document's defaultView. The message template lives at utils.ts:184-188.","triggerScenarios":"Passing a text node, a Document, a Window, a plain object, a number, or a Locator whose `element()` resolves to a non-element Node to any matcher that calls `getElementFromUserInput` (e.g. `toBeChecked`, `toHaveValue`, `toHaveSelection`, `toHaveFormValues`). Cross-realm element instances whose constructor differs from the document's `defaultView.HTMLElement` also fail.","commonSituations":"Passing `document` or `window` by mistake. Grabbing a text node via `element.firstChild`. Element coming from an iframe whose `defaultView` differs. Serializer returning a wrapper object instead of a real Element.","solutions":["Ensure you pass a DOM Element (e.g. `document.querySelector('button')`) or a Vitest Locator that resolves to one.","For iframe contents, resolve the element through that iframe's document so `instanceof` matches the correct realm.","If you hold a Node, walk up to its parentElement/ownerDocument.documentElement to obtain an Element."],"exampleFix":"// before\nexpect(document).toHaveValue('x')\n\n// after\nexpect(document.querySelector('input')!).toHaveValue('x')","handlingStrategy":"type-guard","validationCode":"function isHtmlOrSvg(el: unknown, view: Window = window): boolean {\n  return el instanceof view.HTMLElement || el instanceof view.SVGElement\n}\nif (!isHtmlOrSvg(target)) throw new Error('expected HTMLElement or SVGElement')","typeGuard":"function isHtmlOrSvgElement(el: unknown, view: Window = window): el is HTMLElement | SVGElement {\n  return el instanceof view.HTMLElement || el instanceof view.SVGElement\n}","tryCatchPattern":null,"preventionTips":["Pass real DOM Elements or Vitest Locators to matchers; never document/window.","When working with iframes, resolve elements from that iframe's document so realms match.","Use querySelector/Locator methods that return Elements, not text nodes or wrappers."],"tags":["browser","expect-matcher","type-validation","dom","locator"],"analyzedSha":"d568f8ce3739b532d5bf2c1ee1e45e8a8a473d09","analyzedAt":"2026-08-03T20:23:56.861Z","schemaVersion":2}