Nutella Peanut-Butter Marshmallow

    eslint-plugin-testing-library

    5.9.1 • Public • Published

    eslint-plugin-testing-library

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


    Build status Package version eslint-remote-tester eslint-plugin-testing-library MIT License
    semantic-release PRs Welcome All Contributors
    Watch on Github Star on Github Tweet

    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 configuration file. You can omit the eslint-plugin- prefix:

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

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

    {
    	"rules": {
    		"testing-library/await-async-query": "error",
    		"testing-library/no-await-sync-query": "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
    {
    	// 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
    {
    	extends: ['plugin:testing-library/dom', 'plugin:testing-library/react'],
    }
    // ✅ Just do this instead
    {
    	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 config file:

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

    Angular

    Enforces recommended rules for Angular Testing Library.

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

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

    React

    Enforces recommended rules for React Testing Library.

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

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

    Vue

    Enforces recommended rules for Vue Testing Library.

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

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

    Marko

    Enforces recommended rules for Marko Testing Library.

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

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

    Supported Rules

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

    Key: 🔧 = fixable

    Configurations: dom-badge = dom, angular-badge = angular, react-badge = react, vue-badge = vue, marko-badge = marko

    Name Description 🔧 Included in configurations
    await-async-query Enforce promises from async queries to be handled dom-badge angular-badge react-badge vue-badge marko-badge
    await-async-utils Enforce promises from async utils to be awaited properly dom-badge angular-badge react-badge vue-badge marko-badge
    await-fire-event Enforce promises from fireEvent methods to be handled vue-badge marko-badge
    consistent-data-testid Ensures consistent usage of data-testid
    no-await-sync-events Disallow unnecessary await for sync events
    no-await-sync-query Disallow unnecessary await for sync queries dom-badge angular-badge react-badge vue-badge marko-badge
    no-container Disallow the use of container methods angular-badge react-badge vue-badge marko-badge
    no-debugging-utils Disallow the use of debugging utilities like debug angular-badge react-badge vue-badge marko-badge
    no-dom-import Disallow importing from DOM Testing Library 🔧 angular-badge react-badge vue-badge marko-badge
    no-global-regexp-flag-in-query Disallow the use of the global RegExp flag (/g) in queries 🔧
    no-manual-cleanup Disallow the use of cleanup
    no-node-access Disallow direct Node access angular-badge react-badge vue-badge marko-badge
    no-promise-in-fire-event Disallow the use of promises passed to a fireEvent method dom-badge angular-badge react-badge vue-badge marko-badge
    no-render-in-setup Disallow the use of render in testing frameworks setup functions angular-badge react-badge vue-badge marko-badge
    no-unnecessary-act Disallow wrapping Testing Library utils or empty callbacks in act react-badge marko-badge
    no-wait-for-empty-callback Disallow empty callbacks for waitFor and waitForElementToBeRemoved dom-badge angular-badge react-badge vue-badge marko-badge
    no-wait-for-multiple-assertions Disallow the use of multiple expect calls inside waitFor dom-badge angular-badge react-badge vue-badge marko-badge
    no-wait-for-side-effects Disallow the use of side effects in waitFor dom-badge angular-badge react-badge vue-badge marko-badge
    no-wait-for-snapshot Ensures no snapshot is generated inside of a waitFor call dom-badge angular-badge react-badge vue-badge marko-badge
    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 🔧 dom-badge angular-badge react-badge vue-badge marko-badge
    prefer-presence-queries Ensure appropriate get*/query* queries are used with their respective matchers dom-badge angular-badge react-badge vue-badge marko-badge
    prefer-query-by-disappearance Suggest using queryBy* queries when waiting for disappearance dom-badge angular-badge react-badge vue-badge marko-badge
    prefer-screen-queries Suggest using screen while querying dom-badge angular-badge react-badge vue-badge marko-badge
    prefer-user-event Suggest using userEvent over fireEvent for simulating user interactions
    prefer-wait-for Use waitFor instead of deprecated wait methods 🔧
    render-result-naming-convention Enforce a valid naming for return value from render angular-badge react-badge vue-badge marko-badge

    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
    {
    	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
    {
    	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
    {
    	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
    {
    	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

    💻 ⚠️ 📖

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

    Install

    npm i eslint-plugin-testing-library

    DownloadsWeekly Downloads

    4,125,812

    Version

    5.9.1

    License

    MIT

    Unpacked Size

    239 kB

    Total Files

    45

    Last publish

    Collaborators

    • belco
    • testing-library-bot
    • eslint-plugin-testing-library-bot