{"record":{"id":"999527c207416e02","repo":"oxc-project/oxc","slug":"snapshot-is-missing-a-hint","errorCode":null,"errorMessage":"Snapshot is missing a hint.","messagePattern":"Snapshot is missing a hint\\.","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"warning","filePath":"crates/oxc_linter/src/rules/shared/jest_vitest/prefer_snapshot_hint.rs","lineNumber":28,"sourceCode":"use oxc_semantic::NodeId;\nuse oxc_span::Span;\n\nuse crate::{\n    context::LintContext,\n    utils::{\n        JestFnKind, JestGeneralFnKind, PossibleJestNode, collect_possible_jest_call_node,\n        parse_expect_jest_fn_call,\n    },\n};\n\nfn snapshot_matcher_too_many_arguments_diagnostic(span: Span) -> OxcDiagnostic {\n    OxcDiagnostic::warn(\"`toMatchSnapshot` takes at most two arguments.\")\n        .with_help(\"Pass a hint string, or a property matcher object followed by a hint string.\")\n        .with_label(span)\n}\n\nfn snapshot_missing_hint_diagnostic(span: Span) -> OxcDiagnostic {\n    OxcDiagnostic::warn(\"Snapshot is missing a hint.\")\n        .with_help(\"Include a hint string to identify this snapshot in the snapshot file.\")\n        .with_label(span)\n}\n\nfn snapshot_hint_must_be_string_diagnostic(span: Span) -> OxcDiagnostic {\n    OxcDiagnostic::warn(\"Snapshot hint must be a string literal.\")\n        .with_help(\n            \"Provide a string literal as the hint, or pass a property matcher object as the first argument and the hint string as the second.\",\n        )\n        .with_label(span)\n}\n\n#[derive(Debug, Clone, Copy, Eq, PartialEq, Deserialize, JsonSchema, Default)]\n#[serde(rename_all = \"lowercase\")]\npub enum SnapshotHintMode {\n    /// Require a hint to always be provided when using external snapshot matchers.\n    Always,\n    /// Require a hint to be provided when there are multiple external snapshot matchers within the scope (meaning it includes nested calls).","sourceCodeStart":10,"sourceCodeEnd":46,"githubUrl":"https://github.com/oxc-project/oxc/blob/e1e7af627c8843ab64044ed466b128fcc21a035b/crates/oxc_linter/src/rules/shared/jest_vitest/prefer_snapshot_hint.rs#L10-L46","documentation":"This is the oxlint `prefer-snapshot-hint` rule, missing-hint branch. External snapshot matchers (`toMatchSnapshot`, `toThrowErrorMatchingSnapshot`) key their stored snapshots by auto-incrementing numbers within a test; adding or reordering assertions silently shifts those numbers and pollutes reviews. The rule groups snapshot calls per enclosing function scope (including helper functions called from tests) and requires a hint string whenever the mode says one is needed.","triggerScenarios":"In mode `always`: any zero-argument `toMatchSnapshot()`/`toThrowErrorMatchingSnapshot()`. In default mode `multi`: zero-argument external snapshot matchers when the same scope (test callback or helper function, nested included) contains 2+ of them. Note `toMatchInlineSnapshot` never triggers this.","commonSituations":"Helper functions shared by multiple tests that each call toMatchSnapshot (the classic trap: every caller adds snapshots to one scope, numbers shift); growing a test from one to two snapshots without adding hints; CI snapshot diffs full of renumbered entries after inserting an early assertion.","solutions":["Add a stable hint: `expect(stdout).toMatchSnapshot({}, 'cli --version stdout')` or `toMatchSnapshot('renders header')`.","Convert one-off snapshots to `toMatchInlineSnapshot()` which is exempt.","If hints are unwanted team-wide, set the rule off; if you only disagree with the default, switch mode between 'always' and 'multi' in .oxlintrc.json."],"exampleFix":"// before\nconst snapshotOutput = ({ stdout, stderr }) => {\n  expect(stdout).toMatchSnapshot();\n  expect(stderr).toMatchSnapshot();\n};\n\n// after\nconst snapshotOutput = ({ stdout, stderr }, hints) => {\n  expect(stdout).toMatchSnapshot({}, `stdout: ${hints.stdout}`);\n  expect(stderr).toMatchSnapshot({}, `stderr: ${hints.stderr}`);\n};","handlingStrategy":"validation","validationCode":"// .oxlintrc.json\n{ \"rules\": { \"jest/prefer-snapshot-hint\": [\"error\", \"always\"] } }\n\nnpx oxlint tests/","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Give every external snapshot a stable, human-meaningful hint string.","Watch shared helper functions that call toMatchSnapshot — each caller multiplies the snapshots in one scope.","Prefer toMatchInlineSnapshot for one-off captures; it is exempt and self-documenting."],"tags":["jest","vitest","oxlint","testing","snapshots","static-analysis"],"backgroundTag":"snapshot-hint","analyzedSha":"e1e7af627c8843ab64044ed466b128fcc21a035b","analyzedAt":"2026-08-20T07:01:07.079Z","contentChangedAt":"2026-08-20T07:01:07.079Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}