{"id":"e3ddaf36b73f573d","repo":"vitest-dev/vitest","slug":"matcherhint-tobefasterthan-expects-the-actu","errorCode":null,"errorMessage":"${matcherHint('.toBeFasterThan')} expects the actual value to be a benchmark result.","messagePattern":"(.+?) expects the actual value to be a benchmark result\\.","errorType":"exception","errorClass":"TypeError","httpStatus":null,"severity":"error","filePath":"packages/vitest/src/integrations/chai/bench.ts","lineNumber":23,"sourceCode":"  return (\n    typeof value === 'object'\n    && value !== null\n    && 'latency' in value\n    && typeof (value as any).latency?.mean === 'number'\n  )\n}\n\nfunction formatOps(ops: number): string {\n  return ops.toLocaleString('en-US', { minimumFractionDigits: 2, maximumFractionDigits: 2 })\n}\n\nexport const benchMatchers: MatchersObject = {\n  toBeFasterThan(actual: unknown, expected: unknown, options?: { delta?: number }) {\n    const { matcherHint, RECEIVED_COLOR, EXPECTED_COLOR } = this.utils\n    const delta = options?.delta ?? 0\n\n    if (!isBenchResult(actual)) {\n      throw new TypeError(\n        `${matcherHint('.toBeFasterThan')} expects the actual value to be a benchmark result.`,\n      )\n    }\n    if (!isBenchResult(expected)) {\n      throw new TypeError(\n        `${matcherHint('.toBeFasterThan')} expects the expected value to be a benchmark result.`,\n      )\n    }\n\n    const threshold = expected.latency.mean * (1 - delta)\n    const pass = actual.latency.mean < threshold\n\n    return {\n      pass,\n      message: () => {\n        const relation = ((actual.latency.mean - expected.latency.mean) / expected.latency.mean * 100).toFixed(2)\n        return pass\n          ? `${matcherHint('.not.toBeFasterThan')}\\n\\nExpected to not be faster, but was ${Math.abs(Number(relation))}% faster.\\n\\n`","sourceCodeStart":5,"sourceCodeEnd":41,"githubUrl":"https://github.com/vitest-dev/vitest/blob/d568f8ce3739b532d5bf2c1ee1e45e8a8a473d09/packages/vitest/src/integrations/chai/bench.ts#L5-L41","documentation":"Thrown by the toBeFasterThan benchmark matcher in packages/vitest/src/integrations/chai/bench.ts when the actual value (the receiver of expect()) is not a BenchResult — i.e. an object with a numeric latency.mean produced by vitest's bench() API. The matcher compares benchmark statistics, so passing a plain number or non-bench object makes the comparison meaningless; Vitest throws a TypeError rather than silently degrading.","triggerScenarios":"expect(myNumber).toBeFasterThan(other); using toBeFasterThan outside of a bench() task where expect() receives the result of a normal assertion; passing a raw timing value instead of the BenchResult returned by bench.","commonSituations":"Confusing benchmark matchers with regular numeric matchers; refactoring a bench task so expect() no longer receives the BenchResult; calling toBeFasterThan inside an it() instead of a bench() block.","solutions":["Use toBeFasterThan only inside a bench() task, passing the benchmark result object that vitest provides.","For plain numeric comparisons use toBeLessThan, not toBeFasterThan.","Capture the BenchResult from bench() and pass it to expect(): const result = await bench(...); expect(result).toBeFasterThan(baseline).","Confirm you imported the bench matchers (they ship with vitest) and are inside a benchmark run."],"exampleFix":"// before\nexpect(50).toBeFasterThan(baseline)\n\n// after\nimport { bench, expect } from 'vitest'\nbench('op', () => { /* ... */ })\n// inside a benchmark task, expect() receives the BenchResult\nexpect(actualBenchResult).toBeFasterThan(baselineBenchResult)","handlingStrategy":"type-guard","validationCode":"function isBenchResult(value: unknown): value is { latency: { mean: number }; throughput: { mean: number } } {\n  return typeof value === 'object' && value !== null\n    && 'latency' in value && typeof (value as any).latency?.mean === 'number'\n}","typeGuard":"function isBenchResult(value: unknown): value is { latency: { mean: number }; throughput: { mean: number } } {\n  return typeof value === 'object' && value !== null\n    && 'latency' in value && typeof (value as any).latency?.mean === 'number'\n}","tryCatchPattern":null,"preventionTips":["Only call toBeFasterThan inside bench() tasks where expect() receives a BenchResult.","Use toBeLessThan for plain numeric comparisons.","Capture and reuse baseline BenchResult objects across runs."],"tags":["benchmark","matcher","type-mismatch"],"analyzedSha":"d568f8ce3739b532d5bf2c1ee1e45e8a8a473d09","analyzedAt":"2026-08-03T20:23:56.861Z","schemaVersion":2}