{"record":{"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/1fa9837ec26533512fdcad8baebf249771bd340a/packages/vitest/src/integrations/chai/bench.ts#L5-L41","documentation":"The .toBeFasterThan benchmark matcher requires the actual (received) value to be a BenchResult — an object with a `latency.mean` number, produced by vitest bench(). isBenchResult checks `typeof value === 'object'`, non-null, has 'latency', and latency.mean is a number. If the actual side fails this check, the matcher throws a TypeError immediately.","triggerScenarios":"Calling expect(value).toBeFasterThan(other) where `value` is not the result of a bench() call — e.g. a plain number, a string, or a raw object lacking the latency structure.","commonSituations":"Using toBeFasterThan in a regular (non-bench) test; comparing raw timing numbers instead of BenchResult objects; passing the wrong variable as actual.","solutions":["Ensure the actual value comes from a `bench()` task result (the object passed to the benchmark callback's result).","Use a regular numeric matcher (toBeLessThan) if you are comparing raw numbers, not bench results.","Check that both actual and expected are BenchResult objects before calling the matcher."],"exampleFix":"// before:\nexpect(50).toBeFasterThan(otherResult)\n\n// after — pass the bench result object, not a raw number:\nexpect(myBenchResult).toBeFasterThan(otherBenchResult)","handlingStrategy":"type-guard","validationCode":null,"typeGuard":"function isBenchResult(v: unknown): v is { latency: { mean: number }; throughput: { mean: number } } {\n  return typeof v === 'object' && v !== null\n    && 'latency' in v && typeof (v as any).latency?.mean === 'number'\n}","tryCatchPattern":null,"preventionTips":["Only use toBeFasterThan inside bench() task callbacks with actual bench result objects.","For raw numeric comparisons, use toBeLessThan."],"tags":["bench","matcher","type-validation"],"backgroundTag":null,"analyzedSha":"1fa9837ec26533512fdcad8baebf249771bd340a","analyzedAt":"2026-08-11T16:11:39.638Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}