{"record":{"id":"66b411079c0009c1","repo":"vitest-dev/vitest","slug":"expecting-a-valid-dom-element-but-got-typename","errorCode":null,"errorMessage":"Expecting a valid DOM element, but got ${typeName}.","messagePattern":"Expecting a valid DOM element, but got (.+?)\\.","errorType":"exception","errorClass":"TypeError","httpStatus":null,"severity":"error","filePath":"packages/browser/src/client/tester/context.ts","lineNumber":567,"sourceCode":"  maxLength: number = Number(defaultOptions?.maxLength ?? import.meta.env.DEBUG_PRINT_LIMIT ?? 7000),\n  prettyFormatOptions: PrettyDOMOptions = {},\n): string {\n  if (maxLength === 0) {\n    return ''\n  }\n\n  if (!dom) {\n    dom = document.body\n  }\n\n  if ('element' in dom && 'all' in dom) {\n    dom = dom.element()\n  }\n\n  const type = typeof dom\n  if (type !== 'object' || !dom.outerHTML) {\n    const typeName = type === 'object' ? dom.constructor.name : type\n    throw new TypeError(`Expecting a valid DOM element, but got ${typeName}.`)\n  }\n\n  const pretty = stringify(dom, Number.POSITIVE_INFINITY, {\n    maxLength,\n    highlight: true,\n    ...defaultOptions,\n    ...prettyFormatOptions,\n  })\n  return dom.outerHTML.length > maxLength\n    ? `${pretty.slice(0, maxLength)}...`\n    : pretty\n}\n\nfunction getElementError(selector: string | Locator, container: Element): Error {\n  const locator = typeof selector === 'string' ? __INTERNAL._asLocator('javascript', selector) : selector.asLocator()\n  const formatted = formatDOM(container)\n  const error = new Error(`Cannot find element with locator: ${locator}\\n\\n${formatted}`)\n  error.name = 'VitestBrowserElementError'","sourceCodeStart":549,"sourceCodeEnd":585,"githubUrl":"https://github.com/vitest-dev/vitest/blob/1fa9837ec26533512fdcad8baebf249771bd340a/packages/browser/src/client/tester/context.ts#L549-L585","documentation":"prettyDOM() (exposed as page.utils.prettyDOM / debug) stringifies an Element for diagnostic output. After resolving a falsy argument to document.body and unwrapping a Locator via .element(), it checks typeof === 'object' and the presence of outerHTML. If the value is a primitive, null, or a non-Element object, it throws a TypeError naming the offending constructor/type. This usually indicates a Locator that resolved to nothing or a non-DOM object.","triggerScenarios":"Passing a Locator whose element() returns null/undefined to prettyDOM/debug; passing a number/string/boolean; passing an object that lacks outerHTML (e.g. a plain JS object, a NodeList, or a Window); calling debug() on a stale reference after the node was removed.","commonSituations":"Logging a Locator for debugging without awaiting/resolving it; refactors that changed a query to return a NodeList or array; SSR/jsdom mismatches where Element constructor differs.","solutions":["Resolve Locators first: prettyDOM(await locator.element()).","Verify the value is truthy before calling: if (!el) return;","For arrays/NodeLists, iterate and stringify each Element individually.","Check `value instanceof Element` before prettyDOM to fail with a clearer message."],"exampleFix":"// before\nconsole.log(page.utils.prettyDOM(page.getByRole('button')))\n// after\nconst el = await page.getByRole('button').element()\nif (el) console.log(page.utils.prettyDOM(el))","handlingStrategy":"type-guard","validationCode":"if (!dom || typeof dom !== 'object' || !(dom instanceof Element)) {\n  throw new TypeError('prettyDOM needs an Element')\n}\npage.utils.prettyDOM(dom)","typeGuard":"function isElement(v: unknown): v is Element {\n  return typeof Element !== 'undefined' && v instanceof Element\n}","tryCatchPattern":null,"preventionTips":["Resolve Locators via await locator.element() before passing to prettyDOM/debug.","Check the value is truthy and an Element before formatting.","Iterate NodeLists/arrays individually instead of passing them directly."],"tags":["browser","pretty-dom","debug","dom","type-guard"],"backgroundTag":null,"analyzedSha":"1fa9837ec26533512fdcad8baebf249771bd340a","analyzedAt":"2026-08-11T16:11:39.638Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}