1 | <div align="center">
|
2 | <a href="https://eslint.org/">
|
3 | <img height="150" src="https://eslint.org/assets/images/logo/eslint-logo-color.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 | [![Actions Status](https://github.com/jest-community/eslint-plugin-jest/actions/workflows/nodejs.yml/badge.svg?branch=main)](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 | #### Aliased Jest globals
|
63 |
|
64 | You can tell this plugin about any global Jests you have aliased using the
|
65 | `globalAliases` setting:
|
66 |
|
67 | ```json
|
68 | {
|
69 | "settings": {
|
70 | "jest": {
|
71 | "globalAliases": {
|
72 | "describe": ["context"],
|
73 | "fdescribe": ["fcontext"],
|
74 | "xdescribe": ["xcontext"]
|
75 | }
|
76 | }
|
77 | }
|
78 | }
|
79 | ```
|
80 |
|
81 | ### Running rules only on test-related files
|
82 |
|
83 | The rules provided by this plugin assume that the files they are checking are
|
84 | test-related. This means it's generally not suitable to include them in your
|
85 | top-level configuration as that applies to all files being linted which can
|
86 | include source files.
|
87 |
|
88 | You can use
|
89 | [overrides](https://eslint.org/docs/user-guide/configuring/configuration-files#how-do-overrides-work)
|
90 | to have ESLint apply additional rules to specific files:
|
91 |
|
92 | ```json
|
93 | {
|
94 | "extends": ["eslint:recommended"],
|
95 | "overrides": [
|
96 | {
|
97 | "files": ["test/**"],
|
98 | "plugins": ["jest"],
|
99 | "extends": ["plugin:jest/recommended"],
|
100 | "rules": { "jest/prefer-expect-assertions": "off" }
|
101 | }
|
102 | ],
|
103 | "rules": {
|
104 | "indent": ["error", 2]
|
105 | }
|
106 | }
|
107 | ```
|
108 |
|
109 | ### Jest `version` setting
|
110 |
|
111 | The behaviour of some rules (specifically [`no-deprecated-functions`][]) change
|
112 | depending on the version of Jest being used.
|
113 |
|
114 | By default, this plugin will attempt to determine to locate Jest using
|
115 | `require.resolve`, meaning it will start looking in the closest `node_modules`
|
116 | folder to the file being linted and work its way up.
|
117 |
|
118 | Since we cache the automatically determined version, if you're linting
|
119 | sub-folders that have different versions of Jest, you may find that the wrong
|
120 | version of Jest is considered when linting. You can work around this by
|
121 | providing the Jest version explicitly in nested ESLint configs:
|
122 |
|
123 | ```json
|
124 | {
|
125 | "settings": {
|
126 | "jest": {
|
127 | "version": 27
|
128 | }
|
129 | }
|
130 | }
|
131 | ```
|
132 |
|
133 | To avoid hard-coding a number, you can also fetch it from the installed version
|
134 | of Jest if you use a JavaScript config file such as `.eslintrc.js`:
|
135 |
|
136 | ```js
|
137 | module.exports = {
|
138 | settings: {
|
139 | jest: {
|
140 | version: require('jest/package.json').version,
|
141 | },
|
142 | },
|
143 | };
|
144 | ```
|
145 |
|
146 | ## Shareable configurations
|
147 |
|
148 | ### Recommended
|
149 |
|
150 | This plugin exports a recommended configuration that enforces good testing
|
151 | practices.
|
152 |
|
153 | To enable this configuration use the `extends` property in your `.eslintrc`
|
154 | config file:
|
155 |
|
156 | ```json
|
157 | {
|
158 | "extends": ["plugin:jest/recommended"]
|
159 | }
|
160 | ```
|
161 |
|
162 | ### Style
|
163 |
|
164 | This plugin also exports a configuration named `style`, which adds some
|
165 | stylistic rules, such as `prefer-to-be-null`, which enforces usage of `toBeNull`
|
166 | over `toBe(null)`.
|
167 |
|
168 | To enable this configuration use the `extends` property in your `.eslintrc`
|
169 | config file:
|
170 |
|
171 | ```json
|
172 | {
|
173 | "extends": ["plugin:jest/style"]
|
174 | }
|
175 | ```
|
176 |
|
177 | See
|
178 | [ESLint documentation](https://eslint.org/docs/user-guide/configuring/configuration-files#extending-configuration-files)
|
179 | for more information about extending configuration files.
|
180 |
|
181 | ### All
|
182 |
|
183 | If you want to enable all rules instead of only some you can do so by adding the
|
184 | `all` configuration to your `.eslintrc` config file:
|
185 |
|
186 | ```json
|
187 | {
|
188 | "extends": ["plugin:jest/all"]
|
189 | }
|
190 | ```
|
191 |
|
192 | While the `recommended` and `style` configurations only change in major versions
|
193 | the `all` configuration may change in any release and is thus unsuited for
|
194 | installations requiring long-term consistency.
|
195 |
|
196 | ## Rules
|
197 |
|
198 |
|
199 |
|
200 | | Rule | Description | Configurations | Fixable |
|
201 | | ---------------------------------------------------------------------------- | ------------------------------------------------------------------- | ---------------- | ------------ |
|
202 | | [consistent-test-it](docs/rules/consistent-test-it.md) | Have control over `test` and `it` usages | | ![fixable][] |
|
203 | | [expect-expect](docs/rules/expect-expect.md) | Enforce assertion to be made in a test body | ![recommended][] | |
|
204 | | [max-expects](docs/rules/max-expects.md) | Enforces a maximum number assertion calls in a test body | | |
|
205 | | [max-nested-describe](docs/rules/max-nested-describe.md) | Enforces a maximum depth to nested describe calls | | |
|
206 | | [no-alias-methods](docs/rules/no-alias-methods.md) | Disallow alias methods | ![recommended][] | ![fixable][] |
|
207 | | [no-commented-out-tests](docs/rules/no-commented-out-tests.md) | Disallow commented out tests | ![recommended][] | |
|
208 | | [no-conditional-expect](docs/rules/no-conditional-expect.md) | Prevent calling `expect` conditionally | ![recommended][] | |
|
209 | | [no-conditional-in-test](docs/rules/no-conditional-in-test.md) | Disallow conditional logic in tests | | |
|
210 | | [no-deprecated-functions](docs/rules/no-deprecated-functions.md) | Disallow use of deprecated functions | ![recommended][] | ![fixable][] |
|
211 | | [no-disabled-tests](docs/rules/no-disabled-tests.md) | Disallow disabled tests | ![recommended][] | |
|
212 | | [no-done-callback](docs/rules/no-done-callback.md) | Avoid using a callback in asynchronous tests and hooks | ![recommended][] | ![suggest][] |
|
213 | | [no-duplicate-hooks](docs/rules/no-duplicate-hooks.md) | Disallow duplicate setup and teardown hooks | | |
|
214 | | [no-export](docs/rules/no-export.md) | Disallow using `exports` in files containing tests | ![recommended][] | |
|
215 | | [no-focused-tests](docs/rules/no-focused-tests.md) | Disallow focused tests | ![recommended][] | ![suggest][] |
|
216 | | [no-hooks](docs/rules/no-hooks.md) | Disallow setup and teardown hooks | | |
|
217 | | [no-identical-title](docs/rules/no-identical-title.md) | Disallow identical titles | ![recommended][] | |
|
218 | | [no-if](docs/rules/no-if.md) | Disallow conditional logic | ![deprecated][] | |
|
219 | | [no-interpolation-in-snapshots](docs/rules/no-interpolation-in-snapshots.md) | Disallow string interpolation inside snapshots | ![recommended][] | |
|
220 | | [no-jasmine-globals](docs/rules/no-jasmine-globals.md) | Disallow Jasmine globals | ![recommended][] | ![fixable][] |
|
221 | | [no-large-snapshots](docs/rules/no-large-snapshots.md) | disallow large snapshots | | |
|
222 | | [no-mocks-import](docs/rules/no-mocks-import.md) | Disallow manually importing from `__mocks__` | ![recommended][] | |
|
223 | | [no-restricted-jest-methods](docs/rules/no-restricted-jest-methods.md) | Disallow specific `jest.` methods | | |
|
224 | | [no-restricted-matchers](docs/rules/no-restricted-matchers.md) | Disallow specific matchers & modifiers | | |
|
225 | | [no-standalone-expect](docs/rules/no-standalone-expect.md) | Disallow using `expect` outside of `it` or `test` blocks | ![recommended][] | |
|
226 | | [no-test-prefixes](docs/rules/no-test-prefixes.md) | Use `.only` and `.skip` over `f` and `x` | ![recommended][] | ![fixable][] |
|
227 | | [no-test-return-statement](docs/rules/no-test-return-statement.md) | Disallow explicitly returning from tests | | |
|
228 | | [prefer-called-with](docs/rules/prefer-called-with.md) | Suggest using `toBeCalledWith()` or `toHaveBeenCalledWith()` | | |
|
229 | | [prefer-comparison-matcher](docs/rules/prefer-comparison-matcher.md) | Suggest using the built-in comparison matchers | | ![fixable][] |
|
230 | | [prefer-each](docs/rules/prefer-each.md) | Prefer using `.each` rather than manual loops | | |
|
231 | | [prefer-equality-matcher](docs/rules/prefer-equality-matcher.md) | Suggest using the built-in equality matchers | | ![suggest][] |
|
232 | | [prefer-expect-assertions](docs/rules/prefer-expect-assertions.md) | Suggest using `expect.assertions()` OR `expect.hasAssertions()` | | ![suggest][] |
|
233 | | [prefer-expect-resolves](docs/rules/prefer-expect-resolves.md) | Prefer `await expect(...).resolves` over `expect(await ...)` syntax | | ![fixable][] |
|
234 | | [prefer-hooks-in-order](docs/rules/prefer-hooks-in-order.md) | Prefer having hooks in a consistent order | | |
|
235 | | [prefer-hooks-on-top](docs/rules/prefer-hooks-on-top.md) | Suggest having hooks before any test cases | | |
|
236 | | [prefer-lowercase-title](docs/rules/prefer-lowercase-title.md) | Enforce lowercase test names | | ![fixable][] |
|
237 | | [prefer-mock-promise-shorthand](docs/rules/prefer-mock-promise-shorthand.md) | Prefer mock resolved/rejected shorthands for promises | | ![fixable][] |
|
238 | | [prefer-snapshot-hint](docs/rules/prefer-snapshot-hint.md) | Prefer including a hint with external snapshots | | |
|
239 | | [prefer-spy-on](docs/rules/prefer-spy-on.md) | Suggest using `jest.spyOn()` | | ![fixable][] |
|
240 | | [prefer-strict-equal](docs/rules/prefer-strict-equal.md) | Suggest using `toStrictEqual()` | | ![suggest][] |
|
241 | | [prefer-to-be](docs/rules/prefer-to-be.md) | Suggest using `toBe()` for primitive literals | ![style][] | ![fixable][] |
|
242 | | [prefer-to-contain](docs/rules/prefer-to-contain.md) | Suggest using `toContain()` | ![style][] | ![fixable][] |
|
243 | | [prefer-to-have-length](docs/rules/prefer-to-have-length.md) | Suggest using `toHaveLength()` | ![style][] | ![fixable][] |
|
244 | | [prefer-todo](docs/rules/prefer-todo.md) | Suggest using `test.todo` | | ![fixable][] |
|
245 | | [require-hook](docs/rules/require-hook.md) | Require setup and teardown code to be within a hook | | |
|
246 | | [require-to-throw-message](docs/rules/require-to-throw-message.md) | Require a message for `toThrow()` | | |
|
247 | | [require-top-level-describe](docs/rules/require-top-level-describe.md) | Require test cases and hooks to be inside a `describe` block | | |
|
248 | | [valid-describe-callback](docs/rules/valid-describe-callback.md) | Enforce valid `describe()` callback | ![recommended][] | |
|
249 | | [valid-expect](docs/rules/valid-expect.md) | Enforce valid `expect()` usage | ![recommended][] | |
|
250 | | [valid-expect-in-promise](docs/rules/valid-expect-in-promise.md) | Ensure promises that have expectations in their chain are valid | ![recommended][] | |
|
251 | | [valid-title](docs/rules/valid-title.md) | Enforce valid titles | ![recommended][] | ![fixable][] |
|
252 |
|
253 |
|
254 |
|
255 | ## TypeScript Rules
|
256 |
|
257 | In addition to the above rules, this plugin also includes a few advanced rules
|
258 | that are powered by type-checking information provided by TypeScript.
|
259 |
|
260 | In order to use these rules, you must be using `@typescript-eslint/parser` &
|
261 | adjust your eslint config as outlined
|
262 | [here](https://github.com/typescript-eslint/typescript-eslint/blob/main/docs/linting/TYPED_LINTING.md).
|
263 |
|
264 | Note that unlike the type-checking rules in `@typescript-eslint/eslint-plugin`,
|
265 | the rules here will fallback to doing nothing if type information is not
|
266 | available, meaning it's safe to include them in shared configs that could be
|
267 | used on JavaScript and TypeScript projects.
|
268 |
|
269 | Also note that `unbound-method` depends on `@typescript-eslint/eslint-plugin`,
|
270 | as it extends the original `unbound-method` rule from that plugin.
|
271 |
|
272 |
|
273 |
|
274 | | Rule | Description | Configurations | Fixable |
|
275 | | ---------------------------------------------- | ------------------------------------------------------------ | -------------- | ------- |
|
276 | | [unbound-method](docs/rules/unbound-method.md) | Enforce unbound methods are called with their expected scope | | |
|
277 |
|
278 |
|
279 |
|
280 | ## Credit
|
281 |
|
282 | - [eslint-plugin-mocha](https://github.com/lo1tuma/eslint-plugin-mocha)
|
283 | - [eslint-plugin-jasmine](https://github.com/tlvince/eslint-plugin-jasmine)
|
284 |
|
285 | ## Related Projects
|
286 |
|
287 | ### eslint-plugin-jest-extended
|
288 |
|
289 | This is a sister plugin to `eslint-plugin-jest` that provides support for the
|
290 | matchers provided by
|
291 | [`jest-extended`](https://github.com/jest-community/jest-extended).
|
292 |
|
293 | https://github.com/jest-community/eslint-plugin-jest-extended
|
294 |
|
295 | ### eslint-plugin-jest-formatting
|
296 |
|
297 | This project aims to provide formatting rules (auto-fixable where possible) to
|
298 | ensure consistency and readability in jest test suites.
|
299 |
|
300 | https://github.com/dangreenisrael/eslint-plugin-jest-formatting
|
301 |
|
302 | ### eslint-plugin-istanbul
|
303 |
|
304 | A set of rules to enforce good practices for Istanbul, one of the code coverage
|
305 | tools used by Jest.
|
306 |
|
307 | https://github.com/istanbuljs/eslint-plugin-istanbul
|
308 |
|
309 | [recommended]: https://img.shields.io/badge/-recommended-lightgrey.svg
|
310 | [suggest]: https://img.shields.io/badge/-suggest-yellow.svg
|
311 | [fixable]: https://img.shields.io/badge/-fixable-green.svg
|
312 | [style]: https://img.shields.io/badge/-style-blue.svg
|
313 | [deprecated]: https://img.shields.io/badge/-deprecated-red.svg
|
314 | [`no-deprecated-functions`]: docs/rules/no-deprecated-functions.md
|