oxc-project/oxc · warning

Mock functions that return simple values should use `mockRet

Error message

Mock functions that return simple values should use `mockReturnValue/mockReturnValueOnce`.

What it means

This is the oxlint `prefer-mock-return-shorthand` rule (jest/vitest plugin). When a mock only needs to return a simple value, `mockImplementation(() => value)` is boilerplate; Jest/Vitest provide `mockReturnValue(value)` (and the `...Once` variants) for exactly this. The diagnostic names the current property and the replacement so the fix is mechanical.

Source

Thrown at crates/oxc_linter/src/rules/shared/jest_vitest/prefer_mock_return_shorthand.rs:25

        VariableDeclarationKind,
    },
};
use oxc_ast_visit::{VisitJs, walk_js};
use oxc_diagnostics::OxcDiagnostic;
use oxc_semantic::{ReferenceId, ScopeFlags, SymbolId};
use oxc_span::{GetSpan, Span};
use rustc_hash::FxHashSet;

use crate::{AstNode, context::LintContext};

fn prefer_mock_return_shorthand_diagnostic(
    span: Span,
    current_property: &str,
    replacement: &str,
) -> OxcDiagnostic {
    let help = format!("Replace `{current_property}` with `{replacement}`.");

    OxcDiagnostic::warn(
        "Mock functions that return simple values should use `mockReturnValue/mockReturnValueOnce`.",
    )
    .with_help(help)
    .with_label(span)
}

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

When working with mocks of functions that return simple values, Jest provides some API sugar functions to reduce the amount of boilerplate you have to write.

### Why is this bad?

Not using Jest's API sugar functions adds unnecessary boilerplate and makes tests harder to read. These helpers clearly express intent
and reduce errors, keeping tests simple and maintainable.

### Examples

Examples of **incorrect** code for this rule:

View on GitHub (pinned to e1e7af627c)

Solutions

1. Replace with the shorthand: `mockReturnValue(42)` / `mockReturnValueOnce(42)`.
2. Keep mockImplementation only when the value must be computed per call or the function takes parameters.
3. If the returned value is a promise, use `mockResolvedValue(v)` instead — a different shorthand that this rule complements.

Example fix

// before
jest.fn().mockImplementation(() => 'ok');

// after
jest.fn().mockReturnValue('ok');

// .oxlintrc.json
{ "rules": { "jest/prefer-mock-return-shorthand": "error" } }

npx oxlint tests/

When it happens

Trigger: A call whose parsed mock property is `mockImplementation`/`mockImplementationOnce` where the implementation is a zero-parameter function whose body is a single return of a simple (non-promise) value — e.g. `jest.fn().mockImplementation(() => 42)`.

Common situations: Mocking config getters and small util functions; refactoring handwritten stubs; developers unaware of the return-value sugar APIs.

Related errors

• Suggest using `toBeCalledWith()` or `toHaveBeenCalledWith()`
• Enforce lowercase test names
• Suggest using `jest.spyOn()` or `vi.spyOn()`.
• Do not use setup or teardown hooks.
• Mocks should not be manually imported from a `__mocks__` dir

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