{"record":{"id":"b8f75b6b2cde2abe","repo":"pmndrs/react-three-fiber","slug":"prefix-msg","errorCode":null,"errorMessage":"`${prefix} ${msg}`","messagePattern":"`\\$\\{prefix\\} \\$\\{msg\\}`","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/test-renderer/src/helpers/testInstance.ts","lineNumber":12,"sourceCode":"import type { ReactThreeTestInstance } from '../createTestInstance'\nimport type { Obj } from '../types/internal'\n\nexport const expectOne = <TItem>(items: TItem[], msg: string) => {\n  if (items.length === 1) {\n    return items[0]\n  }\n\n  const prefix =\n    items.length === 0 ? 'RTTR: No instances found' : `RTTR: Expected 1 but found ${items.length} instances`\n\n  throw new Error(`${prefix} ${msg}`)\n}\n\nexport const matchProps = (props: Obj, filter: Obj) => {\n  for (const key in filter) {\n    // Check for matches if filter contains regex matchers\n    const isRegex = filter[key] instanceof RegExp\n    const shouldMatch = isRegex && typeof props[key] === 'string'\n    const match = shouldMatch && filter[key].test(props[key])\n\n    // Bail if props aren't identical and filters found no match\n    if (props[key] !== filter[key] && !match) {\n      return false\n    }\n  }\n\n  return true\n}\n","sourceCodeStart":1,"sourceCodeEnd":30,"githubUrl":"https://github.com/pmndrs/react-three-fiber/blob/ff3899dbf43d2a88895fecf53c147192abfd7431/packages/test-renderer/src/helpers/testInstance.ts#L1-L30","documentation":"This error is thrown by react-three-test-renderer's expectOne helper when a test query (e.g. tree.getBy / a selector matching instances) does not return exactly one matching instance. The prefix distinguishes the two cases: 'No instances found' means zero nodes matched, 'Expected 1 but found N' means the selector was ambiguous and matched multiple nodes. It exists to make tests deterministic — implicit first-match behavior would hide bugs.","triggerScenarios":"Calling expectOne with the result of a findAll-style query inside test-renderer helpers (used by tree('...') selectors / getBy-style APIs) where the JSX rendered 0 matching elements, or where multiple elements share the same type/props (e.g. two <mesh> elements with no distinguishing props).","commonSituations":"Wrong selector string or PascalCase typo (e.g. 'Mesh' vs 'mesh'), the component under test not actually rendering the expected subtree, assertions running before React has flushed/committed the tree, or queries that are too broad in a scene with repeated objects.","solutions":["Make the selector more specific: add distinguishing props (e.g. tree(mesh, { name: 'target' }) or user props) so exactly one instance matches.","If zero matched, verify the element actually rendered — check for conditional rendering guards, early returns, or Suspense boundaries that suspend the subtree.","If the assertion may run before commit, wrap it in tree.waitFor(...) (or waitFor with a timeout) so the query retries until the node appears.","If you genuinely expect multiple instances, use a query that returns all matches (findAll-style) and assert on the array length instead of expectOne."],"exampleFix":"// before\nconst instance = expectOne(tree.findAll(mesh), 'mesh') // found 3 <mesh> elements\n\n// after\nconst instance = expectOne(tree.findAll(mesh).filter(i => i.props.name === 'target'), 'target mesh')","handlingStrategy":"validation","validationCode":"// Before calling expectOne, assert the match count yourself\nconst found = tree.findAll(mesh)\nif (found.length === 0) throw new Error('mesh not rendered yet — did the component mount?')\nif (found.length > 1) throw new Error(`ambiguous selector: ${found.length} meshes, add a distinguishing prop`)","typeGuard":"const isSingleMatch = <T>(items: T[]): items is [T] => items.length === 1","tryCatchPattern":"try {\n  const inst = expectOne(tree.findAll(mesh), 'mesh')\n} catch (e) {\n  if (e instanceof Error && e.message.startsWith('RTTR:')) {\n    // query mismatch: refine selector or wait for render, don't rethrow blindly\n  } else throw e\n}","preventionTips":["Give scene elements distinguishing props (name, userData) so selectors are unique by construction.","Wait for async rendering with tree.waitFor before querying.","Prefer the most specific selector type + props combination in tests."],"tags":["react-three-fiber","testing","query","test-renderer"],"backgroundTag":"test-selector-no-match","analyzedSha":"ff3899dbf43d2a88895fecf53c147192abfd7431","analyzedAt":"2026-08-28T10:16:38.568Z","schemaVersion":2},"datasetVersion":"2026-08-28T11:17:15.048Z"}