eslint-plugin-vitest-2

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
no-unneeded-async-expect-function	Disallow unnecessary async function wrapper for expected promises
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 expect(...).toBeTypeOf(...) instead of expect(typeof ...).toBe(...)
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-mock-return-shorthand	Prefer mock return shorthands
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-been-called-times	Suggest using toHaveBeenCalledTimes()
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-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-test-timeout	require tests to declare a timeout
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
unbound-method	enforce unbound methods are called with their expected scope
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