{"id":"8ed4b34813adcb2f","repo":"vitest-dev/vitest","slug":"expected-element-or-locator-to-be-defined","errorCode":null,"errorMessage":"Expected element or locator to be defined.","messagePattern":"Expected element or locator to be defined\\.","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/browser/src/client/tester/tester-utils.ts","lineNumber":295,"sourceCode":"    return String(re)\n  }\n  // Even number of backslashes followed by the quote -> insert a backslash.\n  return String(re).replace(/(^|[^\\\\])(\\\\\\\\)*([\"'`])/g, '$1$2\\\\$3').replace(/>>/g, '\\\\>\\\\>')\n}\n\nexport function escapeForTextSelector(text: string | RegExp, exact: boolean): string {\n  if (typeof text !== 'string') {\n    return escapeRegexForSelector(text)\n  }\n  return `${JSON.stringify(text)}${exact ? 's' : 'i'}`\n}\n\nconst provider = getBrowserState().provider\nconst kElementLocator = Symbol.for('$$vitest:locator-resolved')\n\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')","sourceCodeStart":277,"sourceCodeEnd":313,"githubUrl":"https://github.com/vitest-dev/vitest/blob/d568f8ce3739b532d5bf2c1ee1e45e8a8a473d09/packages/browser/src/client/tester/tester-utils.ts#L277-L313","documentation":"Thrown by `serializeElement` at tester-utils.ts:294-296 when its first argument is falsy. The serializer is used by `toMatchScreenshot` (for masks) and other commands to convert an Element/Locator into a payload for the driver; a null/undefined input cannot be serialized.","triggerScenarios":"Calling `serializeElement(null)`, `serializeElement(undefined)`, or passing a value that resolves to undefined (e.g. `await locator.findElement()` when not found). Indirectly triggered when `toMatchScreenshot` options contain a `mask` entry that is null.","commonSituations":"Passing an optional element that wasn't resolved. Building a mask array where some entries are undefined. Race condition where an element was detached between resolution and serialization.","solutions":["Resolve and verify the element before serializing: `const el = await locator.findElement(); if (!el) throw ...`.","Filter undefined entries from mask arrays: `mask.filter(Boolean)` before passing to options.","Use `page.locator(...).waitFor()` to guarantee presence before serializing."],"exampleFix":"// before\nawait serializeElement(maybeMissingEl)\n\n// after\nif (!maybeMissingEl) throw new Error('mask element not found')\nawait serializeElement(maybeMissingEl)","handlingStrategy":"validation","validationCode":"if (!elementOrLocator) throw new Error('element/locator is required')\nawait serializeElement(elementOrLocator)","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Verify elements are present before serializing (waitFor/element()).","Filter falsy entries from mask arrays: mask.filter(Boolean).","Use page.locator(...).element() with a guard for null."],"tags":["browser","tester-utils","type-validation","screenshot","locator"],"analyzedSha":"d568f8ce3739b532d5bf2c1ee1e45e8a8a473d09","analyzedAt":"2026-08-03T20:23:56.861Z","schemaVersion":2}