{"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/d568f8ce3739b532d5bf2c1ee1e45e8a8a473d09/packages/browser/src/client/tester/tester-utils.ts#L292-L328","documentation":"Thrown by `serializeElement` at tester-utils.ts:310 when the input is truthy but is neither an `instanceof Element` nor passes the `isLocator` duck-type check (Symbol.for('$$vitest:locator') in object). The serializer only accepts real DOM Elements or Vitest Locators.","triggerScenarios":"Passing a plain object, a string, a number, a Node that isn't an Element (text/comment node), a Playwright Locator from a different library, or a stale wrapper that lost its symbol.","commonSituations":"Hand-constructing a locator-like object. Passing a jQuery wrapper or testing-library element instead of a DOM Element. Cross-realm Element instances failing `instanceof Element` (rare; usually caught earlier).","solutions":["Pass a DOM Element obtained via `querySelector`/`getByRole` etc., or a Vitest `Locator`.","Unwrap collections/jQuery: pass `$(sel)[0]` not `$(sel)`.","If using a custom locator abstraction, adapt it to expose the Vitest Locator interface or resolve to an Element first."],"exampleFix":"// before\nawait serializeElement($('.btn')) // jQuery wrapper\n\n// after\nawait serializeElement(document.querySelector('.btn')!)","handlingStrategy":"type-guard","validationCode":"import { isLocator } from '@vitest/browser/client'\nfunction isSerializable(v: unknown): v is Element | Locator {\n  return v instanceof Element || isLocator(v)\n}\nif (!isSerializable(target)) throw new Error('expected Element or Locator')","typeGuard":"function isElementOrLocator(v: unknown): v is Element | Locator {\n  const kLocator = Symbol.for('$$vitest:locator')\n  return v instanceof Element || (!!v && typeof v === 'object' && kLocator in v)\n}","tryCatchPattern":null,"preventionTips":["Pass DOM Elements or Vitest Locators; never plain objects, strings, or jQuery wrappers.","Unwrap collections to a single Element.","Adapt custom locator abstractions to expose the Vitest Locator interface."],"tags":["browser","tester-utils","type-validation","screenshot","locator","dom"],"analyzedSha":"d568f8ce3739b532d5bf2c1ee1e45e8a8a473d09","analyzedAt":"2026-08-03T20:23:56.861Z","schemaVersion":2}