eslint-plugin-jest-dom

5.5.0 verified Sat Apr 25 auth: no javascript

ESLint plugin designed to enforce best practices and catch common mistakes when using jest-dom matchers (like toBeChecked, toHaveAttribute) in Testing Library tests. The current stable version is 5.5.0, released in November 2024, with releases every few months. It supports ESLint v6–v9 and provides a recommended configuration as well as flat configs for the new ESLint configuration system. Unlike generic lint rules, this plugin is specifically tailored to the jest-dom API, offering autofixable rules and suggestions to improve test quality. It ships TypeScript definitions and makes @testing-library/dom an optional peer dependency.

Common errors

error Error: Failed to load plugin 'jest-dom' declared in '.eslintrc.yml': Cannot find module 'eslint-plugin-jest-dom' ↓

cause Plugin is not installed or missing from node_modules

fix

Run 'npm install --save-dev eslint-plugin-jest-dom'

error Oops! Something went wrong! :( ESLint: 8.57.0 Error: @testing-library/dom@^9.0.0 is required as a peer dependency ↓

cause Missing peer dependency @testing-library/dom when using v5.0.0

fix

Run 'npm install --save-dev @testing-library/dom@^9.0.0' or upgrade the plugin to v5.1.0+

error Error: Cannot find module 'eslint-plugin-jest-dom/flat/recommended' ↓

cause Using an incorrect import path for flat config before v5.2.0

fix

Use the config via the plugin object: const jestDom = require('eslint-plugin-jest-dom'); ...jestDom.configs['flat/recommended']; or upgrade to v5.2.0+

Warnings

breaking v5.0.0 requires @testing-library/dom@^8.0.0 || ^9.0.0 as a peer dependency ↓

fix Install @testing-library/dom@^8.0.0 || ^9.0.0; or upgrade to v5.1.0+ where it's optional

gotcha Flat config ('flat/recommended') may have subtle differences from legacy config and is subject to breaking changes while ESLint v9 finalizes ↓

fix Watch the changelog and test your config after ESLint updates

deprecated The default export of the plugin object is deprecated in favor of named exports in some contexts; still works but may change ↓

fix Use require('eslint-plugin-jest-dom') without .default

gotcha Rule 'prefer-to-have-style' may flag computed property access incorrectly; false positives possible ↓

fix Upgrade to v5.1.1+ which fixes false positives for variable property names

gotcha TypeScript types only available since v5.5.0; earlier versions ship no types and will cause type errors if importing ↓

fix Upgrade to v5.5.0+ or use @types/eslint-plugin-jest-dom if available

Install

npm install eslint-plugin-jest-dom

yarn add eslint-plugin-jest-dom

pnpm add eslint-plugin-jest-dom

Imports

default (plugin object)

wrong

const plugin = require('eslint-plugin-jest-dom').default;

correct

const plugin = require('eslint-plugin-jest-dom'); // CJS
import plugin from 'eslint-plugin-jest-dom'; // ESM

Plugin object is the default export; no named export for the whole plugin.

configs['flat/recommended']

wrong

require('eslint-plugin-jest-dom/flat/recommended')

correct

const { configs } = require('eslint-plugin-jest-dom');
configs['flat/recommended']

Use the flat config key rather than a separate file path. Available since v5.2.0.

rules

wrong

const { preferChecked } = require('eslint-plugin-jest-dom');

correct

const { rules } = require('eslint-plugin-jest-dom');
// Then access rules['prefer-checked'] etc.

Rules are grouped under a `rules` object keyed by rule name.

TypeScript types for config
```
import type { ESLintPluginJestDom } from 'eslint-plugin-jest-dom';
```
Only available since v5.5.0; types are exported for the plugin object.

Quickstart

Shows how to install and configure eslint-plugin-jest-dom using both legacy .eslintrc and flat config, enabling recommended rules and custom rules.

// Install: npm install --save-dev eslint eslint-plugin-jest-dom @testing-library/dom
// Then in your .eslintrc.js or eslint.config.js:
// .eslintrc.js
module.exports = {
  plugins: ['jest-dom'],
  extends: ['plugin:jest-dom/recommended'],
  rules: {
    'jest-dom/prefer-checked': 'error',
    'jest-dom/prefer-enabled-disabled': 'error',
  },
};

// eslint.config.js (flat config)
const jestDom = require('eslint-plugin-jest-dom');
module.exports = [
  {
    files: ['**/*.test.js', '**/*.spec.js'],
    ...jestDom.configs['flat/recommended'],
    rules: {
      'jest-dom/prefer-checked': 'error',
    },
  },
];