eslint-plugin-vitest

ESLint plugin for Vitest

Installation

You'll first need to install ESLint:

npm i eslint --save-dev

Next, install @vitest/eslint-plugin

npm install @vitest/eslint-plugin --save-dev

Usage

Make sure you're running ESLint v9.0.0 or higher for the latest version of this plugin to work. The following example is how your eslint.config.js should be setup for this plugin to work for you.

import { defineConfig } from 'eslint/config'
import vitest from '@vitest/eslint-plugin'

export default defineConfig({
  files: ['tests/**'], // or any other pattern
  plugins: {
    vitest,
  },
  rules: {
    ...vitest.configs.recommended.rules, // you can also use vitest.configs.all.rules to enable all rules
    'vitest/max-nested-describe': ['error', { max: 3 }], // you can also modify rules' behavior using option like this
  },
})

If you're not using the latest version of ESLint (version v8.57.0 or lower) you can setup this plugin using the following configuration

Add vitest to the plugins section of your .eslintrc configuration file. You can omit the eslint-plugin- prefix:

{
  "plugins": ["@vitest"]
}

Then configure the rules you want to use under the rules section.

{
  "rules": {
    "@vitest/max-nested-describe": [
      "error",
      {
        "max": 3
      }
    ]
  }
}

If you're using old ESLint configuration, make sure to use legacy key like the following

{
  "extends": ["plugin:@vitest/legacy-recommended"] // or legacy-all
}

Enabling with Type-Testing

Vitest ships with an optional type-testing feature, which is disabled by default.

If you're using this feature, you should also enabled typecheck in the settings for this plugin. This ensures that rules like expect-expect account for type-related assertions in tests.

import { defineConfig } from 'eslint/config'
import tseslint from 'typescript-eslint'
import vitest from '@vitest/eslint-plugin'

export default defineConfig(
  // see https://typescript-eslint.io
  tseslint.configs.recommended,
  {
    languageOptions: {
      parserOptions: {
        projectService: true,
      },
    },
  },
  {
    files: ['tests/**'], // or any other pattern
    plugins: {
      vitest,
    },
    rules: {
      ...vitest.configs.recommended.rules,
    },
    settings: {
      vitest: {
        typecheck: true,
      },
    },
    languageOptions: {
      globals: {
        ...vitest.environments.env.globals,
      },
    },
  },
)

Custom Fixtures

If you're using custom fixtures in a separate file and importing them in your tests, you can let the plugin know about them by adding them to the vitestImports setting. The property accepts an array of strings or regular expressions that match the module names where your custom fixtures are defined.

import { defineConfig } from 'eslint/config'
import vitest from '@vitest/eslint-plugin'

export default defineConfig({
  files: ['tests/**'], // or any other pattern
  plugins: {
    vitest,
  },
  rules: {
    ...vitest.configs.recommended.rules,
  },
  settings: {
    vitest: {
      vitestImports: ['@/tests/fixtures', /test-extend$/],
    },
  },
})

Shareable Configurations

Recommended

This plugin exports a recommended configuration that enforces good testing practices.

To enable this configuration with eslint.config.js, use vitest.configs.recommended:

import { defineConfig } from 'eslint/config'
import vitest from '@vitest/eslint-plugin'

export default defineConfig({
  files: ['tests/**'], // or any other pattern
  ...vitest.configs.recommended,
})

All

If you want to enable all rules instead of only some you can do so by adding the all configuration to your eslint.config.js config file:

import { defineConfig } from 'eslint/config'
import vitest from '@vitest/eslint-plugin'

export default defineConfig({
  files: ['tests/**'], // or any other pattern
  ...vitest.configs.all,
})

Rules

💼 Configurations enabled in.
⚠️ Configurations set to warn in.
🚫 Configurations disabled in.
🌐 Set in the all configuration.
✅ Set in the recommended configuration.
🔧 Automatically fixable by the --fix CLI option.
💡 Manually fixable by editor suggestions.
💭 Requires type information.
❌ Deprecated.

| Name                                                | Description | 💼 | ⚠️ | 🚫 | 🔧 | 💡 | 💭 | ❌ | | :----------------------------------------------------------------------------------------------------------------------- | :---------------------------------------------------------------------------------------------- | :-- | :---- | :-- | :-- | :-- | :-- | :-- | | consistent-each-for | enforce using .each or .for consistently | | 🌐 | | | | | | | consistent-test-filename | require test file pattern | | 🌐 | | | | | | | consistent-test-it | enforce using test or it but not both | | 🌐 | | 🔧 | | | | | consistent-vitest-vi | enforce using vitest or vi but not both | | 🌐 | | 🔧 | | | | | expect-expect | enforce having expectation in test body | ✅ | 🌐 | | | | | | | hoisted-apis-on-top | enforce hoisted APIs to be on top of the file | | 🌐 | | | 💡 | | | | max-expects | enforce a maximum number of expect per test | | 🌐 | | | | | | | max-nested-describe | require describe block to be less than set max value or default value | | 🌐 | | | | | | | no-alias-methods | disallow alias methods | | 🌐 | | 🔧 | | | | | no-commented-out-tests | disallow commented out tests | ✅ | 🌐 | | | | | | | no-conditional-expect | disallow conditional expects | ✅ | 🌐 | | | | | | | no-conditional-in-test | disallow conditional tests | | 🌐 | | | | | | | no-conditional-tests | disallow conditional tests | | 🌐 | | | | | | | no-disabled-tests | disallow disabled tests | | 🌐 ✅ | | | | | | | no-done-callback | disallow using a callback in asynchronous tests and hooks | | | | | 💡 | | ❌ | | no-duplicate-hooks | disallow duplicate hooks and teardown hooks | | 🌐 | | | | | | | no-focused-tests | disallow focused tests | ✅ | 🌐 | | 🔧 | | | | | no-hooks | disallow setup and teardown hooks | | 🌐 | | | | | | | no-identical-title | disallow identical titles | ✅ | 🌐 | | 🔧 | | | | | no-import-node-test | disallow importing node:test | ✅ | 🌐 | | 🔧 | | | | | no-importing-vitest-globals | disallow importing Vitest globals | | | 🌐 | 🔧 | | | | | no-interpolation-in-snapshots | disallow string interpolation in snapshots | ✅ | 🌐 | | 🔧 | | | | | no-large-snapshots | disallow large snapshots | | 🌐 | | | | | | | no-mocks-import | disallow importing from mocks directory | ✅ | 🌐 | | | | | | | no-restricted-matchers | disallow the use of certain matchers | | 🌐 | | | | | | | no-restricted-vi-methods | disallow specific vi. methods | | 🌐 | | | | | | | no-standalone-expect | disallow using expect outside of it or test blocks | ✅ | 🌐 | | | | | | | no-test-prefixes | disallow using the f and x prefixes in favour of .only and .skip | | 🌐 | | 🔧 | | | | | no-test-return-statement | disallow return statements in tests | | 🌐 | | | | | | | padding-around-after-all-blocks | Enforce padding around afterAll blocks | | 🌐 | | 🔧 | | | | | padding-around-after-each-blocks | Enforce padding around afterEach blocks | | 🌐 | | 🔧 | | | | | padding-around-all | Enforce padding around vitest functions | | 🌐 | | 🔧 | | | | | padding-around-before-all-blocks | Enforce padding around beforeAll blocks | | 🌐 | | 🔧 | | | | | padding-around-before-each-blocks | Enforce padding around beforeEach blocks | | 🌐 | | 🔧 | | | | | padding-around-describe-blocks | Enforce padding around describe blocks | | 🌐 | | 🔧 | | | | | padding-around-expect-groups | Enforce padding around expect groups | | 🌐 | | 🔧 | | | | | padding-around-test-blocks | Enforce padding around test blocks | | 🌐 | | 🔧 | | | | | prefer-called-exactly-once-with | Prefer toHaveBeenCalledExactlyOnceWith over toHaveBeenCalledOnce and toHaveBeenCalledWith | ✅ | 🌐 | | 🔧 | | | | | prefer-called-once | enforce using toBeCalledOnce() or toHaveBeenCalledOnce() | | | 🌐 | 🔧 | | | | | prefer-called-times | enforce using toBeCalledTimes(1) or toHaveBeenCalledTimes(1) | | 🌐 | | 🔧 | | | | | prefer-called-with | enforce using toBeCalledWith() or toHaveBeenCalledWith() | | 🌐 | | 🔧 | | | | | prefer-comparison-matcher | enforce using the built-in comparison matchers | | 🌐 | | 🔧 | | | | | prefer-describe-function-title | enforce using a function as a describe title over an equivalent string | | 🌐 | | 🔧 | | | | | prefer-each | enforce using each rather than manual loops | | 🌐 | | | | | | | prefer-equality-matcher | enforce using the built-in equality matchers | | 🌐 | | | 💡 | | | | prefer-expect-assertions | enforce using expect assertions instead of callbacks | | 🌐 | | | 💡 | | | | prefer-expect-resolves | enforce using expect().resolves over expect(await ...) syntax | | 🌐 | | 🔧 | | | | | prefer-expect-type-of | enforce using expectTypeOf instead of expect(typeof ...) | | 🌐 | | 🔧 | | | | | prefer-hooks-in-order | enforce having hooks in consistent order | | 🌐 | | | | | | | prefer-hooks-on-top | enforce having hooks before any test cases | | 🌐 | | | | | | | prefer-import-in-mock | prefer dynamic import in mock | | 🌐 | | 🔧 | | | | | prefer-importing-vitest-globals | enforce importing Vitest globals | | 🌐 | | 🔧 | | | | | prefer-lowercase-title | enforce lowercase titles | | 🌐 | | 🔧 | | | | | prefer-mock-promise-shorthand | enforce mock resolved/rejected shorthands for promises | | 🌐 | | 🔧 | | | | | prefer-snapshot-hint | enforce including a hint with external snapshots | | 🌐 | | | | | | | prefer-spy-on | enforce using vi.spyOn | | 🌐 | | 🔧 | | | | | prefer-strict-boolean-matchers | enforce using toBe(true) and toBe(false) over matchers that coerce types to boolean | | 🌐 | | 🔧 | | | | | prefer-strict-equal | enforce strict equal over equal | | 🌐 | | | 💡 | | | | prefer-to-be | enforce using toBe() | | 🌐 | | 🔧 | | | | | prefer-to-be-falsy | enforce using toBeFalsy() | | | 🌐 | 🔧 | | | | | prefer-to-be-object | enforce using toBeObject() | | 🌐 | | 🔧 | | | | | prefer-to-be-truthy | enforce using toBeTruthy | | | 🌐 | 🔧 | | | | | prefer-to-contain | enforce using toContain() | | 🌐 | | 🔧 | | | | | prefer-to-have-length | enforce using toHaveLength() | | 🌐 | | 🔧 | | | | | prefer-todo | enforce using test.todo | | 🌐 | | 🔧 | | | | | prefer-vi-mocked | require vi.mocked() over fn as Mock | | 🌐 | | 🔧 | | 💭 | | | require-awaited-expect-poll | ensure that every expect.poll call is awaited | | 🌐 | | | | | | | require-hook | require setup and teardown to be within a hook | | 🌐 | | | | | | | require-import-vi-mock | require usage of import in vi.mock() | | 🌐 | | 🔧 | | | | | require-local-test-context-for-concurrent-snapshots | require local Test Context for concurrent snapshot tests | ✅ | 🌐 | | | | | | | require-mock-type-parameters | enforce using type parameters with vitest mock functions | | 🌐 | | 🔧 | | | | | require-to-throw-message | require toThrow() to be called with an error message | | 🌐 | | | | | | | require-top-level-describe | enforce that all tests are in a top-level describe | | 🌐 | | | | | | | valid-describe-callback | enforce valid describe callback | ✅ | 🌐 | | | | | | | valid-expect | enforce valid expect() usage | ✅ | 🌐 | | 🔧 | | | | | valid-expect-in-promise | require promises that have expectations in their chain to be valid | ✅ | 🌐 | | | | | | | valid-title | enforce valid titles | ✅ | 🌐 | | 🔧 | | | | | warn-todo | disallow .todo usage | | | | | | | |

Credits

• eslint-plugin-jest: most of the rules in this plugin are essentially ports of Jest plugin rules with minor modifications

Licence

MIT Licence © 2022 - present by veritem and contributors