@vitest/eslint-plugin

The plugin provides two main pre-configured sets of rules:

1. Recommended: Enforces good testing practices. Use vitest.configs.recommended.
2. All: Enables every available rule in the plugin. Use vitest.configs.all.

In ESLint Flat Config, you can spread these directly into your configuration object.

// Recommended
import vitest from '@vitest/eslint-plugin'
export default defineConfig({
  ...vitest.configs.recommended,
})

// All
import vitest from '@vitest/eslint-plugin'
export default defineConfig({
  ...vitest.configs.all,
})

To use the Vitest ESLint plugin, you must first install ESLint and then the plugin itself as development dependencies.

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

The vitest/prefer-called-once rule enforces more semantic and readable Vitest assertions by requiring the use of toBeCalledOnce() or toHaveBeenCalledOnce() instead of passing 1 to toBeCalledTimes(1) or toHaveBeenCalledTimes(1) most common cases.

This rule is automatically fixable using the ESLint --fix CLI option.

// Incorrect
test('foo', () => {
  const mock = vi.fn()
  mock('foo')
  expect(mock).toBeCalledTimes(1)
  expect(mock).toHaveBeenCalledTimes(1)
})

// Correct
test('foo', () => {
  const mock = vi.fn()
  mock('foo')
  expect(mock).toBeCalledOnce()
  expect(mock).toHaveBeenCalledOnce()
})

If you want to use function or class names as parameters inside describe, test, or it blocks, you must enable Vitest's type checking in your ESLint configuration settings. This allows the rule to correctly resolve the types of the arguments.

import vitest from 'eslint-plugin-vitest'

export default [
  {
    files: ['tests/**'],
    plugins: {
      vitest,
    },
    rules: {
      ...vitest.configs.recommended.rules,
    },
    settings: {
      vitest: {
        typecheck: true,
      },
    },
  },
]

The vitest/valid-title rule enforces valid string titles for describe, it, and test functions. This rule is included in the recommended configuration and is automatically fixable using the ESLint --fix option.

This rule helps prevent empty, purely numeric, or poorly formatted test titles, and can be used to ban specific words (like skip or only) from being used in title strings.

{
  "vitest/valid-title": [
    "error",
    {
      "ignoreTypeOfDescribeName": false,
      "allowArguments": false,
      "disallowedWords": ["skip", "only"],
      "mustNotMatch": ["^\\s+$", "^\\s*\\d+\\s*$"],
      "mustMatch": ["^\\s*\\w+\\s*$"]
    }
  ]
}

For ESLint version v9.0.0 or higher, use the Flat Config format (eslint.config.js). You can import the plugin and apply its recommended or all rules. You can also customize specific rule behaviors using the standard ESLint rule object format.

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, // or vitest.configs.all.rules
    'vitest/max-nested-describe': ['error', { max: 3 }],
  },
})

For legacy ESLint configurations (version v8.57.0 or lower), add @vitest to your plugins array in your .eslintrc file and configure rules using the @vitest/ prefix. You can also use the legacy recommended configurations via the extends key.

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

To use legacy recommended configurations:

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

If you are using the expect(typeof ...).toBe(...) pattern, you can automatically migrate to the preferred Vitest matcher by running ESLint with the --fix flag.

Incorrect pattern:

expect(typeof 'hello').toBe('string')

Correct pattern (after fix):

expect('hello').toBeTypeOf('string')

eslint --fix .

The vitest/prefer-comparison-matcher rule enforces the use of Vitest's built-in comparison matchers instead of checking boolean results of comparison expressions. This improves test readability and provides better error messages when assertions fail.

Supported Matchers:

• toBeGreaterThan
• toBeGreaterThanOrEqual
• toBeLessThan
• toBeLessThanOrEqual

Note on Severity: This rule emits a warning when using the all shareable configuration.

Auto-fixable: This rule can be automatically fixed using the ESLint --fix CLI option.

// Incorrect
expect(x > 5).toBe(true)
expect(x < 7).not.toEqual(true)
expect(x <= y).toStrictEqual(true)

// Correct
expect(x).toBeGreaterThan(5)
expect(x).not.toBeLessThanOrEqual(7)
expect(x).toBeLessThanOrEqual(y)