| 1 | <div align="center">
|
|---|
| 2 | <a href="https://eslint.org/">
|
|---|
| 3 | <img width="150" height="150" src="https://eslint.org/assets/img/logo.svg">
|
|---|
| 4 | </a>
|
|---|
| 5 | <a href="https://facebook.github.io/jest/">
|
|---|
| 6 | <img width="150" height="150" vspace="" hspace="25" src="https://jestjs.io/img/jest.png">
|
|---|
| 7 | </a>
|
|---|
| 8 | <h1>eslint-plugin-jest</h1>
|
|---|
| 9 | <p>ESLint plugin for Jest</p>
|
|---|
| 10 | </div>
|
|---|
| 11 |
|
|---|
| 12 | [](https://github.com/jest-community/eslint-plugin-jest/actions)
|
|---|
| 13 |
|
|---|
| 14 | ## Installation
|
|---|
| 15 |
|
|---|
| 16 | ```bash
|
|---|
| 17 | yarn add --dev eslint eslint-plugin-jest
|
|---|
| 18 | ```
|
|---|
| 19 |
|
|---|
| 20 | **Note:** If you installed ESLint globally then you must also install
|
|---|
| 21 | `eslint-plugin-jest` globally.
|
|---|
| 22 |
|
|---|
| 23 | ## Usage
|
|---|
| 24 |
|
|---|
| 25 | Add `jest` to the plugins section of your `.eslintrc` configuration file. You
|
|---|
| 26 | can omit the `eslint-plugin-` prefix:
|
|---|
| 27 |
|
|---|
| 28 | ```json
|
|---|
| 29 | {
|
|---|
| 30 | "plugins": ["jest"]
|
|---|
| 31 | }
|
|---|
| 32 | ```
|
|---|
| 33 |
|
|---|
| 34 | Then configure the rules you want to use under the rules section.
|
|---|
| 35 |
|
|---|
| 36 | ```json
|
|---|
| 37 | {
|
|---|
| 38 | "rules": {
|
|---|
| 39 | "jest/no-disabled-tests": "warn",
|
|---|
| 40 | "jest/no-focused-tests": "error",
|
|---|
| 41 | "jest/no-identical-title": "error",
|
|---|
| 42 | "jest/prefer-to-have-length": "warn",
|
|---|
| 43 | "jest/valid-expect": "error"
|
|---|
| 44 | }
|
|---|
| 45 | }
|
|---|
| 46 | ```
|
|---|
| 47 |
|
|---|
| 48 | You can also tell ESLint about the environment variables provided by Jest by
|
|---|
| 49 | doing:
|
|---|
| 50 |
|
|---|
| 51 | ```json
|
|---|
| 52 | {
|
|---|
| 53 | "env": {
|
|---|
| 54 | "jest/globals": true
|
|---|
| 55 | }
|
|---|
| 56 | }
|
|---|
| 57 | ```
|
|---|
| 58 |
|
|---|
| 59 | This is included in all configs shared by this plugin, so can be omitted if
|
|---|
| 60 | extending them.
|
|---|
| 61 |
|
|---|
| 62 | ### Jest `version` setting
|
|---|
| 63 |
|
|---|
| 64 | The behaviour of some rules (specifically [`no-deprecated-functions`][]) change
|
|---|
| 65 | depending on the version of Jest being used.
|
|---|
| 66 |
|
|---|
| 67 | By default, this plugin will attempt to determine to locate Jest using
|
|---|
| 68 | `require.resolve`, meaning it will start looking in the closest `node_modules`
|
|---|
| 69 | folder to the file being linted and work its way up.
|
|---|
| 70 |
|
|---|
| 71 | Since we cache the automatically determined version, if you're linting
|
|---|
| 72 | sub-folders that have different versions of Jest, you may find that the wrong
|
|---|
| 73 | version of Jest is considered when linting. You can work around this by
|
|---|
| 74 | providing the Jest version explicitly in nested ESLint configs:
|
|---|
| 75 |
|
|---|
| 76 | ```json
|
|---|
| 77 | {
|
|---|
| 78 | "settings": {
|
|---|
| 79 | "jest": {
|
|---|
| 80 | "version": 27
|
|---|
| 81 | }
|
|---|
| 82 | }
|
|---|
| 83 | }
|
|---|
| 84 | ```
|
|---|
| 85 |
|
|---|
| 86 | To avoid hard-coding a number, you can also fetch it from the installed version
|
|---|
| 87 | of Jest if you use a JavaScript config file such as `.eslintrc.js`:
|
|---|
| 88 |
|
|---|
| 89 | ```js
|
|---|
| 90 | module.exports = {
|
|---|
| 91 | settings: {
|
|---|
| 92 | jest: {
|
|---|
| 93 | version: require('jest/package.json').version,
|
|---|
| 94 | },
|
|---|
| 95 | },
|
|---|
| 96 | };
|
|---|
| 97 | ```
|
|---|
| 98 |
|
|---|
| 99 | ## Shareable configurations
|
|---|
| 100 |
|
|---|
| 101 | ### Recommended
|
|---|
| 102 |
|
|---|
| 103 | This plugin exports a recommended configuration that enforces good testing
|
|---|
| 104 | practices.
|
|---|
| 105 |
|
|---|
| 106 | To enable this configuration use the `extends` property in your `.eslintrc`
|
|---|
| 107 | config file:
|
|---|
| 108 |
|
|---|
| 109 | ```json
|
|---|
| 110 | {
|
|---|
| 111 | "extends": ["plugin:jest/recommended"]
|
|---|
| 112 | }
|
|---|
| 113 | ```
|
|---|
| 114 |
|
|---|
| 115 | ### Style
|
|---|
| 116 |
|
|---|
| 117 | This plugin also exports a configuration named `style`, which adds some
|
|---|
| 118 | stylistic rules, such as `prefer-to-be-null`, which enforces usage of `toBeNull`
|
|---|
| 119 | over `toBe(null)`.
|
|---|
| 120 |
|
|---|
| 121 | To enable this configuration use the `extends` property in your `.eslintrc`
|
|---|
| 122 | config file:
|
|---|
| 123 |
|
|---|
| 124 | ```json
|
|---|
| 125 | {
|
|---|
| 126 | "extends": ["plugin:jest/style"]
|
|---|
| 127 | }
|
|---|
| 128 | ```
|
|---|
| 129 |
|
|---|
| 130 | See
|
|---|
| 131 | [ESLint documentation](https://eslint.org/docs/user-guide/configuring/configuration-files#extending-configuration-files)
|
|---|
| 132 | for more information about extending configuration files.
|
|---|
| 133 |
|
|---|
| 134 | ### All
|
|---|
| 135 |
|
|---|
| 136 | If you want to enable all rules instead of only some you can do so by adding the
|
|---|
| 137 | `all` configuration to your `.eslintrc` config file:
|
|---|
| 138 |
|
|---|
| 139 | ```json
|
|---|
| 140 | {
|
|---|
| 141 | "extends": ["plugin:jest/all"]
|
|---|
| 142 | }
|
|---|
| 143 | ```
|
|---|
| 144 |
|
|---|
| 145 | While the `recommended` and `style` configurations only change in major versions
|
|---|
| 146 | the `all` configuration may change in any release and is thus unsuited for
|
|---|
| 147 | installations requiring long-term consistency.
|
|---|
| 148 |
|
|---|
| 149 | ## Rules
|
|---|
| 150 |
|
|---|
| 151 | <!-- begin base rules list -->
|
|---|
| 152 |
|
|---|
| 153 | | Rule | Description | Configurations | Fixable |
|
|---|
| 154 | | ---------------------------------------------------------------------------- | ------------------------------------------------------------------- | ---------------- | ------------ |
|
|---|
| 155 | | [consistent-test-it](docs/rules/consistent-test-it.md) | Have control over `test` and `it` usages | | ![fixable][] |
|
|---|
| 156 | | [expect-expect](docs/rules/expect-expect.md) | Enforce assertion to be made in a test body | ![recommended][] | |
|
|---|
| 157 | | [max-nested-describe](docs/rules/max-nested-describe.md) | Enforces a maximum depth to nested describe calls | | |
|
|---|
| 158 | | [no-alias-methods](docs/rules/no-alias-methods.md) | Disallow alias methods | ![style][] | ![fixable][] |
|
|---|
| 159 | | [no-commented-out-tests](docs/rules/no-commented-out-tests.md) | Disallow commented out tests | ![recommended][] | |
|
|---|
| 160 | | [no-conditional-expect](docs/rules/no-conditional-expect.md) | Prevent calling `expect` conditionally | ![recommended][] | |
|
|---|
| 161 | | [no-deprecated-functions](docs/rules/no-deprecated-functions.md) | Disallow use of deprecated functions | ![recommended][] | ![fixable][] |
|
|---|
| 162 | | [no-disabled-tests](docs/rules/no-disabled-tests.md) | Disallow disabled tests | ![recommended][] | |
|
|---|
| 163 | | [no-done-callback](docs/rules/no-done-callback.md) | Avoid using a callback in asynchronous tests and hooks | ![recommended][] | ![suggest][] |
|
|---|
| 164 | | [no-duplicate-hooks](docs/rules/no-duplicate-hooks.md) | Disallow duplicate setup and teardown hooks | | |
|
|---|
| 165 | | [no-export](docs/rules/no-export.md) | Disallow using `exports` in files containing tests | ![recommended][] | |
|
|---|
| 166 | | [no-focused-tests](docs/rules/no-focused-tests.md) | Disallow focused tests | ![recommended][] | ![suggest][] |
|
|---|
| 167 | | [no-hooks](docs/rules/no-hooks.md) | Disallow setup and teardown hooks | | |
|
|---|
| 168 | | [no-identical-title](docs/rules/no-identical-title.md) | Disallow identical titles | ![recommended][] | |
|
|---|
| 169 | | [no-if](docs/rules/no-if.md) | Disallow conditional logic | | |
|
|---|
| 170 | | [no-interpolation-in-snapshots](docs/rules/no-interpolation-in-snapshots.md) | Disallow string interpolation inside snapshots | ![recommended][] | |
|
|---|
| 171 | | [no-jasmine-globals](docs/rules/no-jasmine-globals.md) | Disallow Jasmine globals | ![recommended][] | ![fixable][] |
|
|---|
| 172 | | [no-jest-import](docs/rules/no-jest-import.md) | Disallow importing Jest | ![recommended][] | |
|
|---|
| 173 | | [no-large-snapshots](docs/rules/no-large-snapshots.md) | disallow large snapshots | | |
|
|---|
| 174 | | [no-mocks-import](docs/rules/no-mocks-import.md) | Disallow manually importing from `__mocks__` | ![recommended][] | |
|
|---|
| 175 | | [no-restricted-matchers](docs/rules/no-restricted-matchers.md) | Disallow specific matchers & modifiers | | |
|
|---|
| 176 | | [no-standalone-expect](docs/rules/no-standalone-expect.md) | Disallow using `expect` outside of `it` or `test` blocks | ![recommended][] | |
|
|---|
| 177 | | [no-test-prefixes](docs/rules/no-test-prefixes.md) | Use `.only` and `.skip` over `f` and `x` | ![recommended][] | ![fixable][] |
|
|---|
| 178 | | [no-test-return-statement](docs/rules/no-test-return-statement.md) | Disallow explicitly returning from tests | | |
|
|---|
| 179 | | [prefer-called-with](docs/rules/prefer-called-with.md) | Suggest using `toBeCalledWith()` or `toHaveBeenCalledWith()` | | |
|
|---|
| 180 | | [prefer-comparison-matcher](docs/rules/prefer-comparison-matcher.md) | Suggest using the built-in comparison matchers | | ![fixable][] |
|
|---|
| 181 | | [prefer-equality-matcher](docs/rules/prefer-equality-matcher.md) | Suggest using the built-in equality matchers | | ![suggest][] |
|
|---|
| 182 | | [prefer-expect-assertions](docs/rules/prefer-expect-assertions.md) | Suggest using `expect.assertions()` OR `expect.hasAssertions()` | | ![suggest][] |
|
|---|
| 183 | | [prefer-expect-resolves](docs/rules/prefer-expect-resolves.md) | Prefer `await expect(...).resolves` over `expect(await ...)` syntax | | ![fixable][] |
|
|---|
| 184 | | [prefer-hooks-on-top](docs/rules/prefer-hooks-on-top.md) | Suggest having hooks before any test cases | | |
|
|---|
| 185 | | [prefer-lowercase-title](docs/rules/prefer-lowercase-title.md) | Enforce lowercase test names | | ![fixable][] |
|
|---|
| 186 | | [prefer-spy-on](docs/rules/prefer-spy-on.md) | Suggest using `jest.spyOn()` | | ![fixable][] |
|
|---|
| 187 | | [prefer-strict-equal](docs/rules/prefer-strict-equal.md) | Suggest using `toStrictEqual()` | | ![suggest][] |
|
|---|
| 188 | | [prefer-to-be](docs/rules/prefer-to-be.md) | Suggest using `toBe()` for primitive literals | ![style][] | ![fixable][] |
|
|---|
| 189 | | [prefer-to-contain](docs/rules/prefer-to-contain.md) | Suggest using `toContain()` | ![style][] | ![fixable][] |
|
|---|
| 190 | | [prefer-to-have-length](docs/rules/prefer-to-have-length.md) | Suggest using `toHaveLength()` | ![style][] | ![fixable][] |
|
|---|
| 191 | | [prefer-todo](docs/rules/prefer-todo.md) | Suggest using `test.todo` | | ![fixable][] |
|
|---|
| 192 | | [require-hook](docs/rules/require-hook.md) | Require setup and teardown code to be within a hook | | |
|
|---|
| 193 | | [require-to-throw-message](docs/rules/require-to-throw-message.md) | Require a message for `toThrow()` | | |
|
|---|
| 194 | | [require-top-level-describe](docs/rules/require-top-level-describe.md) | Require test cases and hooks to be inside a `describe` block | | |
|
|---|
| 195 | | [valid-describe-callback](docs/rules/valid-describe-callback.md) | Enforce valid `describe()` callback | ![recommended][] | |
|
|---|
| 196 | | [valid-expect](docs/rules/valid-expect.md) | Enforce valid `expect()` usage | ![recommended][] | |
|
|---|
| 197 | | [valid-expect-in-promise](docs/rules/valid-expect-in-promise.md) | Ensure promises that have expectations in their chain are valid | ![recommended][] | |
|
|---|
| 198 | | [valid-title](docs/rules/valid-title.md) | Enforce valid titles | ![recommended][] | ![fixable][] |
|
|---|
| 199 |
|
|---|
| 200 | <!-- end base rules list -->
|
|---|
| 201 |
|
|---|
| 202 | ## TypeScript Rules
|
|---|
| 203 |
|
|---|
| 204 | In addition to the above rules, this plugin also includes a few advanced rules
|
|---|
| 205 | that are powered by type-checking information provided by TypeScript.
|
|---|
| 206 |
|
|---|
| 207 | In order to use these rules, you must be using `@typescript-eslint/parser` &
|
|---|
| 208 | adjust your eslint config as outlined
|
|---|
| 209 | [here](https://github.com/typescript-eslint/typescript-eslint/blob/master/docs/getting-started/linting/TYPED_LINTING.md)
|
|---|
| 210 |
|
|---|
| 211 | Note that unlike the type-checking rules in `@typescript-eslint/eslint-plugin`,
|
|---|
| 212 | the rules here will fallback to doing nothing if type information is not
|
|---|
| 213 | available, meaning its safe to include them in shared configs that could be used
|
|---|
| 214 | on JavaScript and TypeScript projects.
|
|---|
| 215 |
|
|---|
| 216 | Also note that `unbound-method` depends on `@typescript-eslint/eslint-plugin`,
|
|---|
| 217 | as it extends the original `unbound-method` rule from that plugin.
|
|---|
| 218 |
|
|---|
| 219 | <!-- begin type rules list -->
|
|---|
| 220 |
|
|---|
| 221 | | Rule | Description | Configurations | Fixable |
|
|---|
| 222 | | ---------------------------------------------- | ------------------------------------------------------------- | -------------- | ------- |
|
|---|
| 223 | | [unbound-method](docs/rules/unbound-method.md) | Enforces unbound methods are called with their expected scope | | |
|
|---|
| 224 |
|
|---|
| 225 | <!-- end type rules list -->
|
|---|
| 226 |
|
|---|
| 227 | ## Credit
|
|---|
| 228 |
|
|---|
| 229 | - [eslint-plugin-mocha](https://github.com/lo1tuma/eslint-plugin-mocha)
|
|---|
| 230 | - [eslint-plugin-jasmine](https://github.com/tlvince/eslint-plugin-jasmine)
|
|---|
| 231 |
|
|---|
| 232 | ## Related Projects
|
|---|
| 233 |
|
|---|
| 234 | ### eslint-plugin-jest-formatting
|
|---|
| 235 |
|
|---|
| 236 | This project aims to provide formatting rules (auto-fixable where possible) to
|
|---|
| 237 | ensure consistency and readability in jest test suites.
|
|---|
| 238 |
|
|---|
| 239 | https://github.com/dangreenisrael/eslint-plugin-jest-formatting
|
|---|
| 240 |
|
|---|
| 241 | ### eslint-plugin-istanbul
|
|---|
| 242 |
|
|---|
| 243 | A set of rules to enforce good practices for Istanbul, one of the code coverage
|
|---|
| 244 | tools used by Jest.
|
|---|
| 245 |
|
|---|
| 246 | https://github.com/istanbuljs/eslint-plugin-istanbul
|
|---|
| 247 |
|
|---|
| 248 | [recommended]: https://img.shields.io/badge/-recommended-lightgrey.svg
|
|---|
| 249 | [suggest]: https://img.shields.io/badge/-suggest-yellow.svg
|
|---|
| 250 | [fixable]: https://img.shields.io/badge/-fixable-green.svg
|
|---|
| 251 | [style]: https://img.shields.io/badge/-style-blue.svg
|
|---|
| 252 | [`no-deprecated-functions`]: docs/rules/no-deprecated-functions.md
|
|---|
