{"record":{"id":"b15ccffa540eac02","repo":"vitest-dev/vitest","slug":"expected-element-or-locator-to-be-an-instance-of-e","errorCode":null,"errorMessage":"Expected element or locator to be an instance of Element or Locator.","messagePattern":"Expected element or locator to be an instance of Element or Locator\\.","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/browser/src/client/tester/tester-utils.ts","lineNumber":310,"sourceCode":"\nexport async function serializeElement(elementOrLocator: Element | Locator, options?: SelectorOptions): Promise<SerializedLocator> {\n  if (!elementOrLocator) {\n    throw new Error('Expected element or locator to be defined.')\n  }\n  if (elementOrLocator instanceof Element) {\n    const selector = convertElementToCssSelector(elementOrLocator)\n    return { selector, locator: __INTERNAL._asLocator('javascript', selector) }\n  }\n  if (isLocator(elementOrLocator)) {\n    if (provider === 'playwright' || kElementLocator in elementOrLocator) {\n      return elementOrLocator.serialize()\n    }\n    const element = await elementOrLocator.findElement(options)\n    const selector = convertElementToCssSelector(element)\n    const locator = __INTERNAL._asLocator('javascript', selector)\n    return { selector, locator }\n  }\n  throw new Error('Expected element or locator to be an instance of Element or Locator.')\n}\n\nconst kLocator = Symbol.for('$$vitest:locator')\n\nexport function isLocator(element: unknown): element is Locator {\n  return (!!element && typeof element === 'object' && kLocator in element)\n}\n\nconst DEFAULT_WHEEL_DELTA = 100\n\nexport function resolveUserEventWheelOptions(options: UserEventWheelOptions): UserEventWheelDeltaOptions {\n  let delta: UserEventWheelDeltaOptions['delta']\n\n  if (options.delta) {\n    delta = options.delta\n  }\n  else {\n    switch (options.direction) {","sourceCodeStart":292,"sourceCodeEnd":328,"githubUrl":"https://github.com/vitest-dev/vitest/blob/1fa9837ec26533512fdcad8baebf249771bd340a/packages/browser/src/client/tester/tester-utils.ts#L292-L328","documentation":"Thrown by `serializeElement` as its final fallthrough after the input is confirmed truthy, is not an `instanceof Element`, and is not a `Locator` (detected via the `$$vitest:locator` symbol). The function only knows how to serialize actual DOM elements and Locator objects; any other truthy value (a plain object, a number, a string, a Window, a Document) reaches this branch and is rejected.","triggerScenarios":"Passing a Window, Document, NodeList entry that is a text node, a plain object mimicking a Locator but missing the symbol, or any non-Element/non-Locator value to `serializeElement`.","commonSituations":"Forwarding a value that the caller assumed was an element/Locator; a fake/mock Locator missing the internal symbol; cross-realm objects whose `instanceof Element` check fails.","solutions":["Pass only a DOM `Element` or a real Vitest `Locator` instance.","If using a custom Locator-like object, ensure it carries `Symbol.for('$$vitest:locator')` and a compatible shape — or, better, use the official Locator API.","Guard the call site: `if (el instanceof Element || isLocator(el)) { ... }`."],"exampleFix":"// before\nawait serializeElement(document) // Document is not an Element\n\n// after\nawait serializeElement(document.documentElement)","handlingStrategy":"type-guard","validationCode":"import { isLocator } from 'vitest/browser' // or local equivalent\nfunction isSerializableTarget(v: unknown): v is Element | Locator {\n  return v instanceof Element || (!!v && typeof v === 'object' && Symbol.for('$$vitest:locator') in (v as object))\n}\nif (!isSerializableTarget(target)) throw new TypeError('pass an Element or Locator')\nawait serializeElement(target)","typeGuard":"function isSerializableTarget(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 only DOM Elements or real Vitest Locators.","Avoid custom Locator-like objects missing the internal symbol.","Guard call sites with the type guard before forwarding."],"tags":["internal","browser","dom","locator","serialization"],"backgroundTag":null,"analyzedSha":"1fa9837ec26533512fdcad8baebf249771bd340a","analyzedAt":"2026-08-11T16:11:39.638Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}