eslint-plugin-testing-library

7.16.2 verified Sat Apr 25 auth: no javascript

An ESLint plugin (v7.16.2) that enforces best practices and catches common mistakes when writing tests with Testing Library (DOM, React, Vue, etc.). Released frequently via semantic-release, it provides over 30 rules to prevent anti-patterns like using wrapper.innerHTML, awaiting async queries incorrectly, or importing from testing-library/dom instead of the framework-specific package. Unlike generic lint rules, it understands Testing Library's query priorities, userEvent vs fireEvent distinction, and the testing file context. Supports ESLint 8, 9, and 10, ships TypeScript types, and offers both ESM and CJS bundles. Requires Node >=18.18.

Common errors

error Error: Failed to load plugin 'testing-library': Cannot find module 'eslint-plugin-testing-library' ↓

cause The plugin is not installed or is installed globally while ESLint is local, or vice versa.

fix

Run npm install --save-dev eslint-plugin-testing-library in the same project where ESLint is installed.

error Warning: The 'testing-library/no-manual-cleanup' rule is deprecated. Please use 'testing-library/render-hooks' instead. ↓

cause The rule was deprecated in v6 and removed in v7.

fix

Replace 'no-manual-cleanup' with 'render-hooks' in your ESLint config.

error Error: ESLint configuration in .eslintrc.js » plugin:testing-library/recommended: Rule 'testing-library/no-debugging-utils' is not found ↓

cause The rule was renamed or moved to a different preset in v7.

fix

Refer to the v7 migration guide: use testing-library/no-debug or check the updated preset rules.

error Parsing error: Unexpected token ... ↓

cause The test file uses modern JavaScript syntax (e.g., optional chaining) that is not supported by the default parser.

fix

Ensure your ESLint config uses a parser that supports the syntax, e.g., @babel/eslint-parser or @typescript-eslint/parser for TypeScript.

Warnings

breaking v7 drops support for Node 16 and ESLint 7. ↓

fix Upgrade Node to ^18.18.0 || ^20.9.0 || >=21.1.0, and ESLint to ^8.57.0 || ^9.0.0 || ^10.0.0.

breaking v7 changed rule configurations: some rules moved to different presets and some rules were renamed. ↓

fix Use the migration guide for v7: https://github.com/testing-library/eslint-plugin-testing-library/blob/main/docs/migration-guides/v7.md

deprecated The rule 'no-manual-cleanup' was deprecated in v6 and removed in v7. Use 'render-hooks' instead. ↓

fix Replace 'testing-library/no-manual-cleanup' with 'testing-library/render-hooks'.

gotcha The plugin must be configured only for test files (via overrides or flat config file patterns), otherwise it will lint all files and produce warnings for non-test code. ↓

fix Use overrides or flat config with file patterns like ['**/*.test.*', '**/*.spec.*'] to restrict the plugin to test files.

gotcha When using flat config (ESLint >= 9), import the plugin's flat configs (e.g. configs['flat/react']) instead of using extends. ↓

fix Use `testingLibrary.configs['flat/react']` for flat config.

gotcha The rule 'prefer-user-event-setup' (added in v7.14.0) requires userEvent to be set up in a setup file; otherwise it will report missing setup. ↓

fix Ensure you have a test setup file that calls `userEvent.setup()` and that the rule is configured correctly.

Install

npm install eslint-plugin-testing-library

yarn add eslint-plugin-testing-library

pnpm add eslint-plugin-testing-library

Imports

plugin (default import)
wrong
```
const testingLibrary = require('eslint-plugin-testing-library');
```
correct
```
import testingLibrary from 'eslint-plugin-testing-library';
```
Since v7.15.0, the plugin is bundled in both CJS and ESM formats. The default export works for both, but using import is preferred for ESM compatibility.
configs
wrong
```
const { configs } = require('eslint-plugin-testing-library');
```
correct
```
import { configs } from 'eslint-plugin-testing-library';
```
configs include presets like 'flat', 'recommended', 'angular', 'react', 'vue'. Use configs['flat/recommended'] for ESLint flat config.

rules

wrong

const rules = require('eslint-plugin-testing-library').rules;

correct

import { rules } from 'eslint-plugin-testing-library';

Rules object contains all rule definitions. Access individual rules like rules['await-async-queries'].

Quickstart

Quick setup using recommended React config, including overrides for test files (legacy) and flat config approach.

// .eslintrc.js - use overrides to target test files
module.exports = {
  plugins: ['testing-library'],
  overrides: [
    {
      files: ['**/__tests__/**/*.[jt]s?(x)', '**/?(*.)+(spec|test).[jt]s?(x)'],
      extends: ['plugin:testing-library/react'],
    },
  ],
};

// With ESLint flat config (eslint.config.js)
import testingLibrary from 'eslint-plugin-testing-library';
export default [
  { files: ['**/*.test.*', '**/*.spec.*'], ...testingLibrary.configs['flat/react'] },
];