eslint-plugin-testing-library

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-jest-dom

This plugin provides ESLint rules for Jest DOM, which is a companion library for Testing Library that provides custom DOM element matchers for Jest. It enforces best practices and consistency for using Jest DOM matchers.

eslint-plugin-jest

This plugin is focused on linting Jest test code. It includes a variety of rules that help enforce best practices and avoid common mistakes when writing tests with Jest, which is a popular testing framework.

eslint-plugin-cypress

This plugin provides linting rules for Cypress, an end-to-end testing framework. It enforces best practices and consistency when writing tests with Cypress, similar to how eslint-plugin-testing-library does for Testing Library.

README

eslint-plugin-testing-library

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

---

Installation

You'll first need to install ESLint:

$ npm i eslint --save-dev

Next, install eslint-plugin-testing-library:

$ npm install eslint-plugin-testing-library --save-dev

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

Usage

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

{
  "plugins": ["testing-library"]
}

Then configure the rules you want to use under the rules section.

{
  "rules": {
    "testing-library/await-async-query": "error",
    "testing-library/no-await-sync-query": "error",
    "testing-library/no-debug": "warn"
  }
}

Shareable configurations

Recommended

This plugin exports a recommended configuration that enforces good Testing Library practices (you can find more info about enabled rules in the Supported Rules section within the Configurations column).

To enable this configuration use the extends property in your .eslintrc config file:

{
  "extends": ["plugin:testing-library/recommended"]
}

Frameworks

Starting from the premise that DOM Testing Library is the base for the rest of Testing Library frameworks wrappers, this plugin also exports different configuration for those frameworks that enforces good practices for specific rules that only apply to them (you can find more info about enabled rules in the Supported Rules section within the Configurations column).

Note that frameworks configurations enable their specific rules + recommended rules.

Available frameworks configurations are:

Angular

To enable this configuration use the extends property in your .eslintrc config file:

{
  "extends": ["plugin:testing-library/angular"]
}

React

To enable this configuration use the extends property in your .eslintrc config file:

{
  "extends": ["plugin:testing-library/react"]
}

Vue

To enable this configuration use the extends property in your .eslintrc config file:

{
  "extends": ["plugin:testing-library/vue"]
}

Supported Rules

Rule	Description	Configurations	Fixable
await-async-query	Enforce async queries to have proper await
await-async-utils	Enforce async utils to be awaited properly
await-fire-event	Enforce async fire event methods to be awaited
consistent-data-testid	Ensure data-testid values match a provided regex.
no-await-sync-query	Disallow unnecessary await for sync queries
no-debug	Disallow the use of debug
no-dom-import	Disallow importing from DOM Testing Library
no-manual-cleanup	Disallow the use of cleanup
no-render-in-setup	Disallow the use of render in setup functions
no-wait-for-empty-callback	Disallow empty callbacks for waitFor and waitForElementToBeRemoved
prefer-explicit-assert	Suggest using explicit assertions rather than just getBy* queries
prefer-find-by	Suggest using findBy* methods instead of the waitFor + getBy queries
prefer-presence-queries	Enforce specific queries when checking element is present or not
prefer-screen-queries	Suggest using screen while using queries
prefer-wait-for	Use waitFor instead of deprecated wait methods

Contributors ✨

Thanks goes to these wonderful people (emoji key):

Mario Beltrán Alarcón 💻 📖 👀 ⚠️ 🚇 🐛	Thomas Lombart 💻 📖 👀 ⚠️ 🚇	Ben Monro 💻 📖 ⚠️	Nicola Molinari 💻 ⚠️ 📖 👀	Aarón García Hervás 📖	Matej Šnuderl 🤔 📖	Adrià Fontcuberta 💻 ⚠️
Jon Aldinger 📖	Thomas Knickman 💻 📖 ⚠️	Kevin Sullivan 📖	Jakub Jastrzębski 💻 📖 ⚠️	Nikolay Stoynov 📖	marudor 💻 ⚠️	Tim Deschryver 💻 📖 🤔 👀 ⚠️ 🐛 🚇 📦
Tobias Deekens 🐛	Victor Cordova 💻 ⚠️ 🐛	Dmitry Lobanov 💻 ⚠️	Kent C. Dodds 🐛	Gonzalo D'Elia 💻 ⚠️ 📖 👀	Jeff Rifwald 📖	Leandro Lourenci 🐛 💻 ⚠️
Miguel Erja González 🐛	Pavel Pustovalov 🐛	Jacob Parish 🐛 💻 ⚠️	Nick McCurdy 🤔 💻 👀	Stefan Cameron 🐛	Mateus Felix 💻 ⚠️ 📖	Renato Augusto Gama dos Santos 🤔 💻 📖 ⚠️
Josh Kelly 💻

This project follows the all-contributors specification. Contributions of any kind welcome!