oxc-project/oxc · warning · OxcDiagnostic

Mocks should not be manually imported from a `__mocks__` dir

Error message

Mocks should not be manually imported from a `__mocks__` directory.

What it means

Diagnostic from oxlint rule `jest/no-mocks-import` (shared with vitest) in crates/oxc_linter/src/rules/shared/jest_vitest/no_mocks_import.rs:11. Files under a `__mocks__` directory are consumed automatically by Jest's module resolution adjacent to the real module; importing them by hand both bypasses and confuses the automatic mocking system. The rule reports any import whose specifier path contains a `__mocks__` path component.

Source

Thrown at crates/oxc_linter/src/rules/shared/jest_vitest/no_mocks_import.rs:10

use std::path::PathBuf;

use oxc_ast::{AstKind, ast::Argument};
use oxc_diagnostics::OxcDiagnostic;
use oxc_span::Span;

use crate::context::LintContext;

fn no_mocks_import_diagnostic(span: Span) -> OxcDiagnostic {
    OxcDiagnostic::warn("Mocks should not be manually imported from a `__mocks__` directory.")
        .with_help("Instead use `jest.mock` or `vi.mock` and import from the original module path.")
        .with_label(span)
}

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

This rule reports imports from a path containing a `__mocks__` component.

### Why is this bad?

Manually importing mocks from a `__mocks__` directory can lead to unexpected behavior
and breaks Jest's automatic mocking system. Jest is designed to automatically resolve
and use mocks from `__mocks__` directories when `jest.mock()` is called. Directly
importing from these directories bypasses Jest's module resolution system and can cause
inconsistencies between test and production environments.

### Examples

View on GitHub (pinned to e1e7af627c)

Solutions

1. Delete the manual import and rely on automatic mocking: for node modules adjacent __mocks__/fs.js is used automatically; for local modules add jest.mock('../fs') at the top
2. Import from the original module path in the test after registering the mock: jest.mock('../fs'); import fs from '../fs';
3. If you need the real implementation in the same file, use jest.requireActual('../fs') (or vi.importActual) rather than reaching into __mocks__

Example fix

// before
import fs from '../__mocks__/fs';

// after
jest.mock('fs'); // or: jest.mock('../fs') for a local sibling mock
import fs from 'fs';

rg -n "['\"/]__mocks__/" src/ tests/

When it happens

Trigger: An import (or require/dynamic import argument) whose path string contains a `__mocks__` segment, e.g. import foo from '../__mocks__/fs' or jest.requireActual style references with __mocks__ in the path. The rule inspects call/import arguments and matches the path (PathBuf component check) before labeling the span.

Common situations: Manually pulling in a manual mock that Jest already wires automatically; porting tests from a framework without automatic mocks; sibling-adjacent __mocks__ directories (e.g. for node modules like fs) being imported directly by newcomers.

Related errors

• Suggest using `toBeCalledWith()` or `toHaveBeenCalledWith()`
• Mock functions that return simple values should use `mockRet
• Suggest using `jest.spyOn()` or `vi.spyOn()`.
• Matchers must be called to assert.
• Expect has an unknown modifier.

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