Huge News!Announcing our $40M Series B led by Abstract Ventures.Learn More →

eslint-plugin-testing-library

Package Overview

Dependencies

Advanced tools

Install Socket

Detect and block malicious and high-risk dependencies

Install

eslint-plugin-testing-library

ESLint plugin to follow best practices and anticipate common mistakes when writing tests with Testing Library

7.1.1
latest
Source
npm

Version published: last week

Maintainers: 2

Created: 5 years ago

What is eslint-plugin-testing-library?

The eslint-plugin-testing-library package is an ESLint plugin that provides linting rules for writing tests with the Testing Library, which is a set of utilities for testing UI components in a user-centric way. This plugin helps enforce best practices and eliminate common mistakes when writing tests with Testing Library.

What are eslint-plugin-testing-library's main functionalities?

Enforce consistent usage of Testing Library queries

This rule enforces the use of the `screen` object for querying DOM elements, which provides better consistency and avoids destructuring render result.

/* eslint testing-library/prefer-screen-queries: 'error' */
// Bad
const { getByText } = render(<App />);
getByText('Hello World');

// Good
const screen = render(<App />);
screen.getByText('Hello World');

Avoid using container methods

This rule prevents direct DOM manipulation by avoiding the use of the `container` method, encouraging the use of queries provided by Testing Library instead.

/* eslint testing-library/no-container: 'error' */
// Bad
const { container } = render(<App />);
container.querySelector('.my-class');

// Good
const { getByClassName } = render(<App />);
getByClassName('my-class');

Ensure async queries are awaited

This rule ensures that asynchronous queries like `findBy*` are properly awaited or returned in tests, which is necessary for correct test execution.

/* eslint testing-library/await-async-query: 'error' */
// Bad
getByText('Loading...');

// Good
await findByText('Loaded');

Prevent the use of debug

This rule warns or errors when the `debug` function is used, as it's intended for debugging purposes and should not be left in the final test code.

/* eslint testing-library/no-debug: 'warn' */
// Bad
const { debug } = render(<App />);
debug();

// Good
// No debug usage

Other packages similar to eslint-plugin-testing-library

eslint-plugin-testing-library

ESLint plugin to follow best practices and anticipate common mistakes when writing tests with Testing Library

Prerequisites

To use this plugin, you must have Node.js (^18.18.0, ^20.9.0, or >=21.1.0) installed.

Installation

You'll first need to install ESLint.

Next, install eslint-plugin-testing-library:

$ pnpm add --save-dev eslint-plugin-testing-library
# or
$ npm install --save-dev eslint-plugin-testing-library
# or
$ yarn add --dev eslint-plugin-testing-library

Note: If you installed ESLint globally (using the -g flag) then you must also install eslint-plugin-testing-library globally.

Migrating

You can find detailed guides for migrating eslint-plugin-testing-library in the migration guide docs:

Usage

Add testing-library to the plugins section of your .eslintrc.js configuration file. You can omit the eslint-plugin- prefix:

module.exports = {
	plugins: ['testing-library'],
};

Then configure the rules you want to use within rules property of your .eslintrc:

module.exports = {
	rules: {
		'testing-library/await-async-queries': 'error',
		'testing-library/no-await-sync-queries': 'error',
		'testing-library/no-debugging-utils': 'warn',
		'testing-library/no-dom-import': 'off',
	},
};

Run the plugin only against test files

With the default setup mentioned before, eslint-plugin-testing-library will be run against your whole codebase. If you want to run this plugin only against your tests files, you have the following options:

ESLint `overrides`

One way of restricting ESLint config by file patterns is by using ESLint overrides.

Assuming you are using the same pattern for your test files as Jest by default, the following config would run eslint-plugin-testing-library only against your test files:

// .eslintrc.js
module.exports = {
	// 1) Here we have our usual config which applies to the whole project, so we don't put testing-library preset here.
	extends: ['airbnb', 'plugin:prettier/recommended'],

	// 2) We load other plugins than eslint-plugin-testing-library globally if we want to.
	plugins: ['react-hooks'],

	overrides: [
		{
			// 3) Now we enable eslint-plugin-testing-library rules or preset only for matching testing files!
			files: ['**/__tests__/**/*.[jt]s?(x)', '**/?(*.)+(spec|test).[jt]s?(x)'],
			extends: ['plugin:testing-library/react'],
		},
	],
};

ESLint Cascading and Hierarchy

Another approach for customizing ESLint config by paths is through ESLint Cascading and Hierarchy. This is useful if all your tests are placed under the same folder, so you can place there another .eslintrc where you enable eslint-plugin-testing-library for applying it only to the files under such folder, rather than enabling it on your global .eslintrc which would apply to your whole project.

Shareable configurations

[!NOTE]

eslint.config.js compatible versions of configs are available prefixed with flat/, though most of the plugin documentation still currently uses .eslintrc syntax.

Refer to the ESLint documentation on the new configuration file format for more.

This plugin exports several recommended configurations that enforce good practices for specific Testing Library packages. You can find more info about enabled rules in the Supported Rules section, under the Configurations column.

Since each one of these configurations is aimed at a particular Testing Library package, they are not extendable between them, so you should use only one of them at once per .eslintrc file. For example, if you want to enable recommended configuration for React, you don't need to combine it somehow with DOM one:

// ❌ Don't do this
module.exports = {
	extends: ['plugin:testing-library/dom', 'plugin:testing-library/react'],
};

// ✅ Just do this instead
module.exports = {
	extends: ['plugin:testing-library/react'],
};