{"record":{"id":"2acada4c7fda6269","repo":"vitest-dev/vitest","slug":"expected-selection-must-be-a-string-or-undefined","errorCode":null,"errorMessage":"expected selection must be a string or undefined","messagePattern":"expected selection must be a string or undefined","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/browser/src/client/tester/expect/toHaveSelection.ts","lineNumber":30,"sourceCode":" * The above copyright notice and this permission notice shall be included in all\n * copies or substantial portions of the Software.\n */\n\nimport type { MatcherResult, MatcherState } from 'vitest'\nimport type { Locator } from '../locators'\nimport { arrayAsSetComparison, getElementFromUserInput, getMessage, getTag } from './utils'\n\nexport default function toHaveSelection(\n  this: MatcherState,\n  element: HTMLElement | SVGElement | Locator,\n  expectedSelection: string,\n): MatcherResult {\n  const htmlElement = getElementFromUserInput(element, toHaveSelection, this)\n\n  const expectsSelection = expectedSelection !== undefined\n\n  if (expectsSelection && typeof expectedSelection !== 'string') {\n    throw new Error(`expected selection must be a string or undefined`)\n  }\n\n  const receivedSelection = getSelection(htmlElement)\n\n  return {\n    pass: expectsSelection\n      ? this.equals(receivedSelection, expectedSelection, [arrayAsSetComparison, ...this.customTesters])\n      : Boolean(receivedSelection),\n    message: () => {\n      const to = this.isNot ? 'not to' : 'to'\n      const matcher = this.utils.matcherHint(\n        `${this.isNot ? '.not' : ''}.toHaveSelection`,\n        'element',\n        expectedSelection,\n      )\n      return getMessage(\n        this,\n        matcher,","sourceCodeStart":12,"sourceCodeEnd":48,"githubUrl":"https://github.com/vitest-dev/vitest/blob/1fa9837ec26533512fdcad8baebf249771bd340a/packages/browser/src/client/tester/expect/toHaveSelection.ts#L12-L48","documentation":"Thrown by the `toHaveSelection` matcher when the expected-selection argument is defined (not undefined) but is not a string. The matcher reads `selection.toString()` from the DOM and compares it to a string; a non-string expected value cannot be compared meaningfully, so it rejects the call up front. Passing `undefined` is allowed and means 'assert that some selection exists'.","triggerScenarios":"Calling `expect(el).toHaveSelection(42)`, `.toHaveSelection(['a','b'])`, or `.toHaveSelection({ start: 0 })`. Also any value whose `typeof` is not `'string'` and not `'undefined'`.","commonSituations":"Passing a number where the test meant to assert selected text length; passing an array of strings; confusing `toHaveSelection` (text content) with a hypothetical range/offset API; TypeScript callers bypassing types with `as any`.","solutions":["Pass the exact selected text string, e.g. `expect(el).toHaveSelection('hello')`.","To assert only that a selection exists, omit the argument or pass `undefined`: `expect(el).toHaveSelection()`.","If you need offset-based assertions, read `element.selectionStart`/`selectionEnd` directly and assert with `toBe`."],"exampleFix":"// before\nexpect(input).toHaveSelection(5)\n\n// after\nexpect(input).toHaveSelection('hello')","handlingStrategy":"type-guard","validationCode":"if (expected !== undefined && typeof expected !== 'string') {\n  throw new TypeError('expectedSelection must be a string or undefined')\n}\nexpect(el).toHaveSelection(expected)","typeGuard":"function isSelectionArg(v: unknown): v is string | undefined {\n  return v === undefined || typeof v === 'string'\n}","tryCatchPattern":null,"preventionTips":["Pass the exact selected text, or omit the argument to assert existence.","Let the `string` TypeScript parameter type catch non-string calls.","For offset-based checks, assert on `selectionStart`/`selectionEnd` directly."],"tags":["matcher","argument-validation","browser","selection"],"backgroundTag":null,"analyzedSha":"1fa9837ec26533512fdcad8baebf249771bd340a","analyzedAt":"2026-08-11T16:11:39.638Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}