{"record":{"id":"c93a81e078564eb4","repo":"vitest-dev/vitest","slug":"received-value-must-a-node-or-a-locator-that-retur","errorCode":null,"errorMessage":"received value must a Node or a Locator that returns a Node.","messagePattern":"received value must a Node or a Locator that returns a Node\\.","errorType":"exception","errorClass":"UserInputNodeTypeError","httpStatus":null,"severity":"error","filePath":"packages/browser/src/client/tester/expect/utils.ts","lineNumber":79,"sourceCode":"\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 (\n    elementOrLocator instanceof defaultView.Node\n  ) {\n    return elementOrLocator\n  }\n\n  throw new UserInputNodeTypeError(\n    elementOrLocator,\n    matcherFn,\n    context,\n  )\n}\n\nexport function getMessage(\n  context: MatcherState,\n  matcher: string,\n  expectedLabel: string,\n  expectedValue: unknown,\n  receivedLabel: string,\n  receivedValue: unknown,\n): string {\n  return [\n    `${matcher}\\n`,\n\n    `${expectedLabel}:\\n${context.utils.EXPECTED_COLOR(","sourceCodeStart":61,"sourceCodeEnd":97,"githubUrl":"https://github.com/vitest-dev/vitest/blob/1fa9837ec26533512fdcad8baebf249771bd340a/packages/browser/src/client/tester/expect/utils.ts#L61-L97","documentation":"Thrown by `getNodeFromUserInput` (as `UserInputNodeTypeError`) when the value passed to a node-based matcher/function is not a DOM `Node` or a `Locator` resolving to one. The helper unwraps a `Locator` via `.element()` then checks `instanceof defaultView.Node`; text nodes, comment nodes, document fragments, and elements all pass, but non-Node values (string, number, plain object, Window) are rejected.","triggerScenarios":"Passing a selector string, a Window, a plain object, or null/undefined to a function that uses `getNodeFromUserInput`; passing a NodeList or HTMLCollection instead of a single Node.","commonSituations":"Treating a matcher as selector-based; passing a collection where a single node is required; cross-document nodes whose `defaultView` differs from the current window.","solutions":["Pass a single DOM Node (e.g. `document.querySelector('#x')`) or a Locator.","Index into a collection first: `nodes[0]` rather than `nodes`.","For selector-based lookups, build a Locator with `page.locator(...)` / `getBy*` helpers."],"exampleFix":"// before\nexpect(document.querySelectorAll('.item')).toHaveTextContent('x')\n\n// after\nexpect(document.querySelector('.item')).toHaveTextContent('x')","handlingStrategy":"type-guard","validationCode":"function isNodeOrLocator(v: unknown): v is Node | Locator {\n  return v instanceof Node\n    || (!!v && typeof v === 'object' && Symbol.for('$$vitest:locator') in (v as object))\n}\nif (!isNodeOrLocator(target)) throw new TypeError('pass a Node or Locator')","typeGuard":"function isNodeOrLocator(v: unknown): v is Node | Locator {\n  return v instanceof Node\n    || (!!v && typeof v === 'object' && Symbol.for('$$vitest:locator') in (v as object))\n}","tryCatchPattern":null,"preventionTips":["Pass a single Node (not a NodeList/HTMLCollection).","Index collections before forwarding.","Use Locators for selector-based lookups."],"tags":["matcher","argument-validation","browser","dom","node"],"backgroundTag":null,"analyzedSha":"1fa9837ec26533512fdcad8baebf249771bd340a","analyzedAt":"2026-08-11T16:11:39.638Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-14T00:17:10.932Z"}