Eslint Plugin Testing Library Save

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

Project README

eslint-plugin-testing-library

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


Package version eslint-remote-tester eslint-plugin-testing-library codecov MIT License
semantic-release PRs Welcome All Contributors

Installation

You'll first need to install ESLint:

$ npm install --save-dev eslint
# or
$ yarn add --dev eslint

Next, install eslint-plugin-testing-library:

$ 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

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'],
};

DOM Testing Library

Enforces recommended rules for DOM Testing Library.

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

module.exports = {
	extends: ['plugin:testing-library/dom'],
};

Angular

Enforces recommended rules for Angular Testing Library.

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

module.exports = {
	extends: ['plugin:testing-library/angular'],
};

React

Enforces recommended rules for React Testing Library.

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

module.exports = {
	extends: ['plugin:testing-library/react'],
};

Vue

Enforces recommended rules for Vue Testing Library.

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

module.exports = {
	extends: ['plugin:testing-library/vue'],
};

Marko

Enforces recommended rules for Marko Testing Library.

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

module.exports = {
	extends: ['plugin:testing-library/marko'],
};

Supported Rules

Remember that all rules from this plugin are prefixed by "testing-library/"

๐Ÿ’ผ Configurations enabled in.
โš ๏ธ Configurations set to warn in.
๐Ÿ”ง Automatically fixable by the --fix CLI option.

Nameย ย ย ย ย ย ย ย ย ย ย ย ย ย ย ย ย ย ย ย ย ย ย ย ย ย ย  Description ๐Ÿ’ผ โš ๏ธ ๐Ÿ”ง
await-async-events Enforce promises from async event methods are handled badge-angular badge-dom badge-marko badge-react badge-vue ๐Ÿ”ง
await-async-queries Enforce promises from async queries to be handled badge-angular badge-dom badge-marko badge-react badge-vue
await-async-utils Enforce promises from async utils to be awaited properly badge-angular badge-dom badge-marko badge-react badge-vue
consistent-data-testid Ensures consistent usage of data-testid
no-await-sync-events Disallow unnecessary await for sync events badge-angular badge-dom badge-react
no-await-sync-queries Disallow unnecessary await for sync queries badge-angular badge-dom badge-marko badge-react badge-vue
no-container Disallow the use of container methods badge-angular badge-marko badge-react badge-vue
no-debugging-utils Disallow the use of debugging utilities like debug badge-angular badge-marko badge-react badge-vue
no-dom-import Disallow importing from DOM Testing Library badge-angular badge-marko badge-react badge-vue ๐Ÿ”ง
no-global-regexp-flag-in-query Disallow the use of the global RegExp flag (/g) in queries badge-angular badge-dom badge-marko badge-react badge-vue ๐Ÿ”ง
no-manual-cleanup Disallow the use of cleanup badge-react badge-vue
no-node-access Disallow direct Node access badge-angular badge-dom badge-marko badge-react badge-vue
no-promise-in-fire-event Disallow the use of promises passed to a fireEvent method badge-angular badge-dom badge-marko badge-react badge-vue
no-render-in-lifecycle Disallow the use of render in testing frameworks setup functions badge-angular badge-marko badge-react badge-vue
no-unnecessary-act Disallow wrapping Testing Library utils or empty callbacks in act badge-marko badge-react
no-wait-for-multiple-assertions Disallow the use of multiple expect calls inside waitFor badge-angular badge-dom badge-marko badge-react badge-vue
no-wait-for-side-effects Disallow the use of side effects in waitFor badge-angular badge-dom badge-marko badge-react badge-vue
no-wait-for-snapshot Ensures no snapshot is generated inside of a waitFor call badge-angular badge-dom badge-marko badge-react badge-vue
prefer-explicit-assert Suggest using explicit assertions rather than standalone queries
prefer-find-by Suggest using find(All)By* query instead of waitFor + get(All)By* to wait for elements badge-angular badge-dom badge-marko badge-react badge-vue ๐Ÿ”ง
prefer-implicit-assert Suggest using implicit assertions for getBy* & findBy* queries
prefer-presence-queries Ensure appropriate get*/query* queries are used with their respective matchers badge-angular badge-dom badge-marko badge-react badge-vue
prefer-query-by-disappearance Suggest using queryBy* queries when waiting for disappearance badge-angular badge-dom badge-marko badge-react badge-vue
prefer-query-matchers Ensure the configured get*/query* query is used with the corresponding matchers
prefer-screen-queries Suggest using screen while querying badge-angular badge-dom badge-marko badge-react badge-vue
prefer-user-event Suggest using userEvent over fireEvent for simulating user interactions
render-result-naming-convention Enforce a valid naming for return value from render badge-angular badge-marko badge-react badge-vue

Aggressive Reporting

In v4 this plugin introduced a new feature called "Aggressive Reporting", which intends to detect Testing Library utils usages even if they don't come directly from a Testing Library package (i.e. using a custom utility file to re-export everything from Testing Library). You can read more about this feature here.

If you are looking to restricting or switching off this feature, please refer to the Shared Settings section to do so.

Shared Settings

There are some configuration options available that will be shared across all the plugin rules. This is achieved using ESLint Shared Settings. These Shared Settings are meant to be used if you need to restrict or switch off the Aggressive Reporting, which is an out of the box advanced feature to lint Testing Library usages in a simpler way for most of the users. So please before configuring any of these settings, read more about the advantages of eslint-plugin-testing-library Aggressive Reporting feature, and how it's affected by these settings.

If you are sure about configuring the settings, these are the options available:

testing-library/utils-module

The name of your custom utility file from where you re-export everything from the Testing Library package, or "off" to switch related Aggressive Reporting mechanism off. Relates to Aggressive Imports Reporting.

// .eslintrc.js
module.exports = {
	settings: {
		'testing-library/utils-module': 'my-custom-test-utility-file',
	},
};

You can find more details about the utils-module setting here.

testing-library/custom-renders

A list of function names that are valid as Testing Library custom renders, or "off" to switch related Aggressive Reporting mechanism off. Relates to Aggressive Renders Reporting.

// .eslintrc.js
module.exports = {
	settings: {
		'testing-library/custom-renders': ['display', 'renderWithProviders'],
	},
};

You can find more details about the custom-renders setting here.

testing-library/custom-queries

A list of query names/patterns that are valid as Testing Library custom queries, or "off" to switch related Aggressive Reporting mechanism off. Relates to Aggressive Reporting - Queries

// .eslintrc.js
module.exports = {
	settings: {
		'testing-library/custom-queries': ['ByIcon', 'getByComplexText'],
	},
};

You can find more details about the custom-queries setting here.

Switching all Aggressive Reporting mechanisms off

Since each Shared Setting is related to one Aggressive Reporting mechanism, and they accept "off" to opt out of that mechanism, you can switch the entire feature off by doing:

// .eslintrc.js
module.exports = {
	settings: {
		'testing-library/utils-module': 'off',
		'testing-library/custom-renders': 'off',
		'testing-library/custom-queries': 'off',
	},
};

Troubleshooting

Errors reported in non-testing files

If you find ESLint errors related to eslint-plugin-testing-library in files other than testing, this could be caused by Aggressive Reporting.

You can avoid this by:

  1. running eslint-plugin-testing-library only against testing files
  2. limiting the scope of Aggressive Reporting through Shared Settings
  3. switching Aggressive Reporting feature off

If you think the error you are getting is not related to this at all, please fill a new issue with as many details as possible.

False positives in testing files

If you are getting false positive ESLint errors in your testing files, this could be caused by Aggressive Reporting.

You can avoid this by:

  1. limiting the scope of Aggressive Reporting through Shared Settings
  2. switching Aggressive Reporting feature off

If you think the error you are getting is not related to this at all, please fill a new issue with as many details as possible.

Other documentation

Contributors โœจ

Thanks goes to these wonderful people (emoji key):

Mario Beltrรกn Alarcรณn
Mario Beltrรกn Alarcรณn

๐Ÿ’ป ๐Ÿ“– ๐Ÿ‘€ โš ๏ธ ๐Ÿš‡ ๐Ÿ› ๐Ÿšง
Thomas Lombart
Thomas Lombart

๐Ÿ’ป ๐Ÿ“– ๐Ÿ‘€ โš ๏ธ ๐Ÿš‡
Ben Monro
Ben Monro

๐Ÿ’ป ๐Ÿ“– โš ๏ธ
Nicola Molinari
Nicola Molinari

๐Ÿ’ป โš ๏ธ ๐Ÿ“– ๐Ÿ‘€
Aarรณn Garcรญa Hervรกs
Aarรณn Garcรญa Hervรกs

๐Ÿ“–
Matej ล nuderl
Matej ล nuderl

๐Ÿค” ๐Ÿ“–
Adriร  Fontcuberta
Adriร  Fontcuberta

๐Ÿ’ป โš ๏ธ
Jon Aldinger
Jon Aldinger

๐Ÿ“–
Thomas Knickman
Thomas Knickman

๐Ÿ’ป ๐Ÿ“– โš ๏ธ
Kevin Sullivan
Kevin Sullivan

๐Ÿ“–
Jakub Jastrzฤ™bski
Jakub Jastrzฤ™bski

๐Ÿ’ป ๐Ÿ“– โš ๏ธ
Nikolay Stoynov
Nikolay Stoynov

๐Ÿ“–
marudor
marudor

๐Ÿ’ป โš ๏ธ
Tim Deschryver
Tim Deschryver

๐Ÿ’ป ๐Ÿ“– ๐Ÿค” ๐Ÿ‘€ โš ๏ธ ๐Ÿ› ๐Ÿš‡ ๐Ÿ“ฆ
Tobias Deekens
Tobias Deekens

๐Ÿ›
Victor Cordova
Victor Cordova

๐Ÿ’ป โš ๏ธ ๐Ÿ›
Dmitry Lobanov
Dmitry Lobanov

๐Ÿ’ป โš ๏ธ
Kent C. Dodds
Kent C. Dodds

๐Ÿ›
Gonzalo D'Elia
Gonzalo D'Elia

๐Ÿ’ป โš ๏ธ ๐Ÿ“– ๐Ÿ‘€
Jeff Rifwald
Jeff Rifwald

๐Ÿ“–
Leandro Lourenci
Leandro Lourenci

๐Ÿ› ๐Ÿ’ป โš ๏ธ
Miguel Erja Gonzรกlez
Miguel Erja Gonzรกlez

๐Ÿ›
Pavel Pustovalov
Pavel Pustovalov

๐Ÿ›
Jacob Parish
Jacob Parish

๐Ÿ› ๐Ÿ’ป โš ๏ธ
Nick McCurdy
Nick McCurdy

๐Ÿค” ๐Ÿ’ป ๐Ÿ‘€
Stefan Cameron
Stefan Cameron

๐Ÿ›
Mateus Felix
Mateus Felix

๐Ÿ’ป โš ๏ธ ๐Ÿ“–
Renato Augusto Gama dos Santos
Renato Augusto Gama dos Santos

๐Ÿค” ๐Ÿ’ป ๐Ÿ“– โš ๏ธ
Josh Kelly
Josh Kelly

๐Ÿ’ป
Alessia Bellisario
Alessia Bellisario

๐Ÿ’ป โš ๏ธ ๐Ÿ“–
Spencer Miskoviak
Spencer Miskoviak

๐Ÿ’ป โš ๏ธ ๐Ÿ“– ๐Ÿค”
Giorgio Polvara
Giorgio Polvara

๐Ÿ’ป โš ๏ธ ๐Ÿ“–
Josh David
Josh David

๐Ÿ“–
Michaรซl De Boey
Michaรซl De Boey

๐Ÿ’ป ๐Ÿ“ฆ ๐Ÿšง ๐Ÿš‡ ๐Ÿ‘€
Jian Huang
Jian Huang

๐Ÿ’ป โš ๏ธ ๐Ÿ“–
Philipp Fritsche
Philipp Fritsche

๐Ÿ’ป
Tomas Zaicevas
Tomas Zaicevas

๐Ÿ› ๐Ÿ’ป โš ๏ธ ๐Ÿ“–
Gareth Jones
Gareth Jones

๐Ÿ’ป ๐Ÿ“– โš ๏ธ
HonkingGoose
HonkingGoose

๐Ÿ“– ๐Ÿšง
Julien Wajsberg
Julien Wajsberg

๐Ÿ› ๐Ÿ’ป โš ๏ธ
Marat Dyatko
Marat Dyatko

๐Ÿ› ๐Ÿ’ป
David Tolman
David Tolman

๐Ÿ›
Ari Perkkiรถ
Ari Perkkiรถ

โš ๏ธ
Diego Castillo
Diego Castillo

๐Ÿ’ป
Bruno Pinto
Bruno Pinto

๐Ÿ’ป โš ๏ธ
themagickoala
themagickoala

๐Ÿ’ป โš ๏ธ
Prashant Ashok
Prashant Ashok

๐Ÿ’ป โš ๏ธ
Ivan Aprea
Ivan Aprea

๐Ÿ’ป โš ๏ธ
Dmitry Semigradsky
Dmitry Semigradsky

๐Ÿ’ป โš ๏ธ ๐Ÿ“–
Senja
Senja

๐Ÿ’ป โš ๏ธ ๐Ÿ“–
Breno Cota
Breno Cota

๐Ÿ’ป โš ๏ธ
Nick Bolles
Nick Bolles

๐Ÿ’ป โš ๏ธ ๐Ÿ“–
Bryan Mishkin
Bryan Mishkin

๐Ÿ“– ๐Ÿ”ง
Nim G
Nim G

๐Ÿ“–
Patrick Ahmetovic
Patrick Ahmetovic

๐Ÿค” ๐Ÿ’ป โš ๏ธ
Josh Justice
Josh Justice

๐Ÿ’ป โš ๏ธ ๐Ÿ“– ๐Ÿค”
Dale Karp
Dale Karp

๐Ÿ’ป โš ๏ธ ๐Ÿ“–
Nathan
Nathan

๐Ÿ’ป โš ๏ธ
justintoman
justintoman

๐Ÿ’ป โš ๏ธ
Anthony Devick
Anthony Devick

๐Ÿ’ป โš ๏ธ ๐Ÿ“–
Richard Maisano
Richard Maisano

๐Ÿ’ป โš ๏ธ
Aleksei Androsov
Aleksei Androsov

๐Ÿ’ป โš ๏ธ
Nicolas Bonduel
Nicolas Bonduel

๐Ÿ“–
Alexey Ryabov
Alexey Ryabov

๐Ÿšง
Jemi Salo
Jemi Salo

๐Ÿ’ป โš ๏ธ

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

Open Source Agenda is not affiliated with "Eslint Plugin Testing Library" Project. README Source: testing-library/eslint-plugin-testing-library

Open Source Agenda Badge

Open Source Agenda Rating