← Back to rules

vitest/hoisted-apis-on-top Correctness

💡 A suggestion is available for this rule.

What it does

Requires hoisted Vitest APIs (vi.mock, vi.unmock, and vi.hoisted) to appear in the top-level of the file.

Why is this bad?

Vitest hoists certain APIs to the top of the file during transformation, so they always run before any imports — regardless of where they appear in the source. Writing them inside conditionals, test bodies, or other runtime locations can be misleading and confusing.

The code looks like it executes at runtime, but it actually runs first. This rule ensures that these hoisted APIs are not allowed in confusing contexts.

Examples

Examples of incorrect code for this rule:

if (condition) {
  vi.mock("some-module", () => {});
}

if (condition) {
  vi.unmock("some-module", () => {});
}

if (condition) {
  vi.hoisted(() => {});
}

describe("suite", () => {
  it("test", async () => {
    vi.mock("some-module", () => {});

    const sm = await import("some-module");
  });
});

Examples of correct code for this rule:

if (condition) {
  vi.doMock("some-module", () => {});
}

vi.mock("some-module", () => {});
if (condition) {
}

vi.unmock("some-module", () => {});
if (condition) {
}

vi.hoisted(() => {});
if (condition) {
}

vi.mock("some-module", () => {});

describe("suite", () => {
  it("test", async () => {
    const sm = await import("some-module");
  });
});

How to use

To enable this rule using the config file or in the CLI, you can use:

Config (.oxlintrc.json)

{
  "plugins": ["vitest"],
  "rules": {
    "vitest/hoisted-apis-on-top": "error"
  }
}

Config (oxlint.config.ts)

import { defineConfig } from "oxlint";

export default defineConfig({
  plugins: ["vitest"],
  rules: {
    "vitest/hoisted-apis-on-top": "error",
  },
});

CLI

oxlint --deny vitest/hoisted-apis-on-top --vitest-plugin

Version

This rule was added in v1.39.0.

References

• Rule Source
• Open rule in Oxc Playground