ESLint Plugin for Vue Test Utils

1.0.1 · active · verified Sun Apr 19

The `eslint-plugin-vue-test-utils` package is an ESLint plugin dedicated to enforcing best practices and identifying potential issues when using the `@vue/test-utils` library for testing Vue components. It helps developers maintain high-quality and future-proof test suites by flagging deprecated API usages, inconsistent patterns, and common anti-patterns. The current stable version is 1.0.1, indicating a mature initial release. While a strict release cadence isn't explicitly stated, the recent v1.0.1 release with multiple feature additions and documentation improvements suggests active development. Its core differentiator lies in its specialized focus on `@vue/test-utils`, providing rules that are context-aware of VTU's API changes and version-specific behaviors, often with autofixing capabilities. This enables smoother upgrades of `@vue/test-utils` and helps keep test code consistent without needing manual audits for deprecated features. It complements broader ESLint Vue plugins by offering specific, targeted linting for testing concerns.

Common errors

```
ESLint couldn't find the plugin "eslint-plugin-vue-test-utils".
```
cause The plugin package was not installed or is inaccessible to ESLint.

fix Run `npm install --save-dev eslint-plugin-vue-test-utils` or `yarn add --dev eslint-plugin-vue-test-utils`. Verify the package is listed in `devDependencies`.
```
Configuration for rule "vue-test-utils/no-deprecated-wrapper-functions" is invalid:
```
cause The options provided for a specific rule are not valid according to the rule's schema.

fix Check the plugin's documentation for the specific rule (`./docs/rules/index.md` in the package) to understand its accepted options and their formats. Correct your `.eslintrc` rule configuration.
```
Cannot read properties of undefined (reading 'version')
```
cause This error can occur when using `require('@vue/test-utils/package.json').version` in a `.eslintrc.js` file, but `@vue/test-utils` is not installed or the path to its `package.json` is incorrect.

fix Ensure `@vue/test-utils` is correctly installed in your project. If it's installed in a non-standard location (e.g., a hoisted monorepo `node_modules`), adjust the `require` path or provide a static version string.

Warnings

gotcha In monorepo setups or non-standard project structures, `eslint-plugin-vue-test-utils` might fail to auto-detect the `@vue/test-utils` version. This can lead to incorrect linting results for version-specific rules.
Fix: Manually set the Vue Test Utils version in your `.eslintrc` settings: `{"settings": {"vtu": {"version": "1.3.0"}}}`. You can dynamically read the version using `require('@vue/test-utils/package.json').version` in a JavaScript `.eslintrc` file.
gotcha The plugin has a minimum Node.js version requirement (`14.x || >= 16`). Running ESLint with an older Node.js version will result in errors or unexpected behavior.
Fix: Ensure your Node.js environment meets the specified requirement. Upgrade Node.js to version 14.x or 16+.
gotcha The plugin's rules help identify deprecated `@vue/test-utils` APIs. Ignoring these warnings can lead to broken tests or unexpected behavior when upgrading `@vue/test-utils` to a newer major version.
Fix: Always address warnings and errors reported by the plugin, especially those related to deprecated features. Consult the `@vue/test-utils` migration guide for major version upgrades.

Install

npm install eslint-plugin-vue-test-utils npm
yarn add eslint-plugin-vue-test-utils yarn
pnpm add eslint-plugin-vue-test-utils pnpm

Imports

ESLint plugin configuration

wrong:

import vueTestUtilsPlugin from 'eslint-plugin-vue-test-utils'; // Not how ESLint plugins are used
require('eslint-plugin-vue-test-utils'); // Not how ESLint plugins are used directly

correct:

{
  "plugins": ["vue-test-utils"]
}

ESLint plugins are configured via the `plugins` array in your `.eslintrc` file, not imported in JavaScript code.

Recommended configuration
wrong:
```
"extends": ["vue-test-utils/recommended"]
```
correct:
```
{
  "extends": [
    // ...
    "plugin:vue-test-utils/recommended"
  ]
}
```
When extending a plugin's configuration, the full `plugin:{plugin-name}/{config-name}` syntax is required.
Individual rule configuration
wrong:
```
{
  "rules": {
    "no-deprecated-wrapper-functions": "error"
  }
}
```
correct:
```
{
  "rules": {
    "vue-test-utils/no-deprecated-wrapper-functions": "error"
  }
}
```
ESLint rule IDs for plugins must be prefixed with the plugin name (`vue-test-utils/`) followed by the rule ID.
Setting Vue Test Utils version
wrong:
```
{
  "settings": {
    "vueTestUtilsVersion": "1.3.0"
  }
}
```
correct:
```
{
  "settings": {
    "vtu": {
      "version": "1.3.0"
    }
  }
}
```
The setting key for the Vue Test Utils version is specifically `vtu.version` under the `settings` object in `.eslintrc`.

Quickstart

This quickstart demonstrates how to install the plugin, configure it in an `.eslintrc.js` file to use its recommended rules, and manually specify individual rules. It also shows the option to set the Vue Test Utils version manually, which is crucial for correct linting in certain project setups.

npm install --save-dev eslint eslint-plugin-vue-test-utils @vue/test-utils vue

// .eslintrc.js
// Make sure you have @vue/test-utils installed and configured for your project
module.exports = {
  root: true,
  env: {
    node: true,
    'vue/setup-compiler-macros': true, // Essential for Vue 3 SFC setup script syntax
    jest: true // Or 'vitest: true' if using Vitest for tests
  },
  parserOptions: {
    ecmaVersion: 2020,
    sourceType: 'module'
  },
  extends: [
    'eslint:recommended',
    'plugin:vue/vue3-recommended', // Example: Use Vue 3 recommended rules
    'plugin:vue-test-utils/recommended' // Enable all recommended vue-test-utils rules
  ],
  plugins: [
    'vue-test-utils'
  ],
  rules: {
    // Override or add specific vue-test-utils rules
    'vue-test-utils/no-deprecated-wrapper-functions': 'warn',
    'vue-test-utils/no-deprecated-mount-options': 'error'
  },
  settings: {
    // Manually specify Vue Test Utils version if auto-detection fails (e.g., in monorepos).
    // This can be useful for rules that adapt behavior based on the VTU version.
    // "vtu": {
    //   "version": require('@vue/test-utils/package.json').version || "2.0.0"
    // }
  }
};

view raw JSON →