{"record":{"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/1fa9837ec26533512fdcad8baebf249771bd340a/packages/browser/src/client/tester/tester-utils.ts#L277-L313","documentation":"Thrown by `serializeElement` when `elementOrLocator` is falsy (null/undefined). The function needs a concrete element or Locator to produce a `SerializedLocator` (selector + human-readable locator string) that can be sent over RPC to the browser command server. A null/undefined input has no selector representation, so it is rejected before any serialization step.","triggerScenarios":"Passing `null`/`undefined` to `serializeElement`; a Locator that resolved to nothing and was then forwarded; an optional-chain expression that yielded undefined.","commonSituations":"A `querySelector` that returned null being forwarded without a null check; a Locator `.element()` returning null in non-strict mode; refactor that dropped a guard.","solutions":["Null-check before serializing: `if (el) await serializeElement(el)`.","Resolve Locators in strict mode so a missing element fails earlier with a descriptive error.","Ensure the upstream query/Locator actually returns an element before forwarding."],"exampleFix":"// before\nawait serializeElement(maybeEl)\n\n// after\nif (!maybeEl) throw new Error('element not found')\nawait serializeElement(maybeEl)","handlingStrategy":"validation","validationCode":"if (!elementOrLocator) {\n  throw new Error('Cannot serialize: element or locator is null/undefined')\n}\nawait serializeElement(elementOrLocator)","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Null-check elements before serializing.","Resolve Locators in strict mode so nulls fail earlier.","Forward only confirmed-non-null results from queries."],"tags":["internal","browser","dom","serialization"],"backgroundTag":null,"analyzedSha":"1fa9837ec26533512fdcad8baebf249771bd340a","analyzedAt":"2026-08-11T16:11:39.638Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}