What causes "Suggest using the built-in comparison matchers" in oxc-project/oxc?

Rewrite positive comparisons: `expect(a > b).toBe(true)` → `expect(a).toBeGreaterThan(b)` (and gte/lt/lte equivalents).

Suggest using the built-in comparison matchers

Error message

Suggest using the built-in comparison matchers

What it means

Diagnostic from oxlint's shared jest/vitest prefer-comparison-matcher rule. It fires when `expect()` wraps a raw comparison (`>`, `>=`, `<`, `<=`) asserted with an equality matcher (`toBe`/`toEqual` with true/false), instead of using Jest's built-in comparison matchers. The matcher form produces far better failure messages (it prints both operands and the operator instead of just `false`).

Source

Thrown at crates/oxc_linter/src/rules/shared/jest_vitest/prefer_comparison_matcher.rs:16

use oxc_ast::{
    AstKind,
    ast::{Argument, BinaryExpression, Expression},
};
use oxc_diagnostics::OxcDiagnostic;
use oxc_span::Span;
use oxc_syntax::operator::BinaryOperator;

use crate::{
    context::LintContext,
    fixer::RuleFixer,
    utils::{ParsedExpectFnCall, PossibleJestNode, is_equality_matcher, parse_expect_jest_fn_call},
};

fn use_to_be_comparison(preferred_method: &str, span: Span) -> OxcDiagnostic {
    OxcDiagnostic::warn("Suggest using the built-in comparison matchers")
        .with_help(format!("Prefer using `{preferred_method:?}` instead"))
        .with_label(span)
}

pub const DOCUMENTATION: &str = r"### What it does

This rule checks for comparisons in tests that could be replaced with one of the
following built-in comparison matchers:
- `toBeGreaterThan`
- `toBeGreaterThanOrEqual`
- `toBeLessThan`
- `toBeLessThanOrEqual`

### Why is this bad?

Using generic matchers like `toBe(true)` with comparison expressions
makes tests less readable and provides less helpful error messages when
they fail. Jest's specific comparison matchers offer clearer intent and

View on GitHub (pinned to e1e7af627c)

Solutions

Rewrite positive comparisons: `expect(a > b).toBe(true)` → `expect(a).toBeGreaterThan(b)` (and gte/lt/lte equivalents).
Rewrite negative comparisons by negating the matcher: `expect(a <= b).toBe(false)` → `expect(a).toBeGreaterThan(b)`.
Where NaN is possible, assert `Number.isNaN` explicitly alongside the matcher rewrite.

Example fix

// before
expect(actual.length).toBeGreaterThan(0) ? null : null;
expect(total > limit).toBe(true);
expect(score < passing).toBe(false);

// after
expect(total).toBeGreaterThan(limit);
expect(score).toBeGreaterThanOrEqual(passing);

Defensive patterns

Strategy: validation

Validate before calling

oxlint --jest-plugin test/ # prefer-comparison-matcher

Prevention

Reach for toBeGreaterThan/OrEqual/toBeLessThan/OrEqual before writing expect(a OP b).toBe(true).
Watch the NaN edge when flipping `toBe(false)` comparisons into matchers — add an explicit Number.isNaN assertion if NaN is possible.
Prefer matcher forms in review: they print both operands on failure.

When it happens

Trigger: An `expect(...)` argument that is a BinaryExpression with a gt/gte/lt/lte operator combined with an equality matcher (`is_equality_matcher`), e.g. `expect(a > b).toBe(true)`, `expect(price <= budget).toBe(false)`, `expect(age >= 18).toEqual(true)`. Equality (===) and other shapes are untouched.

Common situations: Assertions written by developers new to Jest's matcher vocabulary; ported assert-style tests (`assert(a > b)`); reviewer-unnoticed `expect(x > y).toBe(true)` in older suites. Note the NaN edge: `expect(a > b).toBe(false)` passes when a or b is NaN, but `expect(a).toBeLessThanOrEqual(b)` fails — the rewrite is usually desired but is not strictly semantics-preserving there.

Related errors

AI-assisted analysis of oxc-project/oxc@e1e7af627c (2026-08-20). Data as JSON: /api/errors/883913fce63527c8. Report an issue: GitHub.