eslint-plugin-jest 24.4.2 → 26.1.0

package/docs/rules/prefer-expect-assertions.md

@@ -58,6 +58,16 @@ test('my test', () => {
 
 ## Options
 
+This rule can be configured to only check tests that match certain patterns that
+typically look like `expect` calls might be missed, such as in promises or
+loops.
+
+By default, none of these options are enabled meaning the rule checks _every_
+test for a call to either `expect.hasAssertions` or `expect.assertions`. If any
+of the options are enabled the rule checks any test that matches _at least one_
+of the patterns represented by the enabled options (think "OR" rather than
+"AND").
+
 #### `onlyFunctionsWithAsyncKeyword`
 
 When `true`, this rule will only warn for tests that use the `async` keyword.
@@ -97,3 +107,119 @@ test('my test', async () => {
   expect(result).toBe('foo');
 });
 ```
+
+#### `onlyFunctionsWithExpectInLoop`
+
+When `true`, this rule will only warn for tests that have `expect` calls within
+a native loop.
+
+```json
+{
+  "rules": {
+    "jest/prefer-expect-assertions": [
+      "warn",
+      { "onlyFunctionsWithAsyncKeyword": true }
+    ]
+  }
+}
+```
+
+Examples of **incorrect** code when `'onlyFunctionsWithExpectInLoop'` is `true`:
+
+```js
+describe('getNumbers', () => {
+  it('only returns numbers that are greater than zero', () => {
+    const numbers = getNumbers();
+
+    for (const number in numbers) {
+      expect(number).toBeGreaterThan(0);
+    }
+  });
+});
+```
+
+Examples of **correct** code when `'onlyFunctionsWithExpectInLoop'` is `true`:
+
+```js
+describe('getNumbers', () => {
+  it('only returns numbers that are greater than zero', () => {
+    expect.hasAssertions();
+
+    const numbers = getNumbers();
+
+    for (const number in numbers) {
+      expect(number).toBeGreaterThan(0);
+    }
+  });
+
+  it('returns more than one number', () => {
+    expect(getNumbers().length).toBeGreaterThan(1);
+  });
+});
+```
+
+#### `onlyFunctionsWithExpectInCallback`
+
+When `true`, this rule will only warn for tests that have `expect` calls within
+a callback.
+
+```json
+{
+  "rules": {
+    "jest/prefer-expect-assertions": [
+      "warn",
+      { "onlyFunctionsWithExpectInCallback": true }
+    ]
+  }
+}
+```
+
+Examples of **incorrect** code when `'onlyFunctionsWithExpectInCallback'` is
+`true`:
+
+```js
+describe('getNumbers', () => {
+  it('only returns numbers that are greater than zero', () => {
+    const numbers = getNumbers();
+
+    getNumbers().forEach(number => {
+      expect(number).toBeGreaterThan(0);
+    });
+  });
+});
+
+describe('/users', () => {
+  it.each([1, 2, 3])('returns ok', id => {
+    client.get(`/users/${id}`, response => {
+      expect(response.status).toBe(200);
+    });
+  });
+});
+```
+
+Examples of **correct** code when `'onlyFunctionsWithExpectInCallback'` is
+`true`:
+
+```js
+describe('getNumbers', () => {
+  it('only returns numbers that are greater than zero', () => {
+    expect.hasAssertions();
+
+    const numbers = getNumbers();
+
+    getNumbers().forEach(number => {
+      expect(number).toBeGreaterThan(0);
+    });
+  });
+});
+
+describe('/users', () => {
+  it.each([1, 2, 3])('returns ok', id => {
+    expect.assertions(3);
+
+    client.get(`/users/${id}`, response => {
+      expect(response.status).toBe(200);
+    });
+  });
+});
+```

package/docs/rules/prefer-expect-resolves.md

@@ -0,0 +1,53 @@
+# Prefer `await expect(...).resolves` over `expect(await ...)` syntax (`prefer-expect-resolves`)
+
+When working with promises, there are two primary ways you can test the resolved
+value:
+
+1. use the `resolve` modifier on `expect`
+   (`await expect(...).resolves.<matcher>` style)
+2. `await` the promise and assert against its result
+   (`expect(await ...).<matcher>` style)
+
+While the second style is arguably less dependent on `jest`, if the promise
+rejects it will be treated as a general error, resulting in less predictable
+behaviour and output from `jest`.
+
+Additionally, favoring the first style ensures consistency with its `rejects`
+counterpart, as there is no way of "awaiting" a rejection.
+
+## Rule details
+
+This rule triggers a warning if an `await` is done within an `expect`, and
+recommends using `resolves` instead.
+
+Examples of **incorrect** code for this rule
+
+```js
+it('passes', async () => {
+  expect(await someValue()).toBe(true);
+});
+
+it('is true', async () => {
+  const myPromise = Promise.resolve(true);
+
+  expect(await myPromise).toBe(true);
+});
+```
+
+Examples of **correct** code for this rule
+
+```js
+it('passes', async () => {
+  await expect(someValue()).resolves.toBe(true);
+});
+
+it('is true', async () => {
+  const myPromise = Promise.resolve(true);
+
+  await expect(myPromise).resolves.toBe(true);
+});
+
+it('errors', async () => {
+  await expect(Promise.rejects('oh noes!')).rejects.toThrow('oh noes!');
+});
+```

package/docs/rules/prefer-hooks-on-top.md

@@ -1,6 +1,10 @@
 # Suggest having hooks before any test cases (`prefer-hooks-on-top`)
 
-All hooks should be defined before the start of the tests
+While hooks can be setup anywhere in a test file, they are always called in a
+specific order which means it can be confusing if they're intermixed with test
+cases.
+
+This rule helps to ensure that hooks are always defined before test cases.
 
 ## Rule Details
 
@@ -11,47 +15,51 @@ Examples of **incorrect** code for this rule
 
 describe('foo', () => {
   beforeEach(() => {
-    //some hook code
-  });
-  test('bar', () => {
-    some_fn();
+    seedMyDatabase();
   });
-  beforeAll(() => {
-    //some hook code
-  });
-  test('bar', () => {
-    some_fn();
+
+  it('accepts this input', () => {
+    // ...
   });
-});
 
-// Nested describe scenario
-describe('foo', () => {
   beforeAll(() => {
-    //some hook code
+    createMyDatabase();
   });
-  test('bar', () => {
-    some_fn();
+
+  it('returns that value', () => {
+    // ...
   });
-  describe('inner_foo', () => {
+
+  describe('when the database has specific values', () => {
+    const specificValue = '...';
+
     beforeEach(() => {
-      //some hook code
+      seedMyDatabase(specificValue);
     });
-    test('inner bar', () => {
-      some_fn();
+
+    it('accepts that input', () => {
+      // ...
     });
-    test('inner bar', () => {
-      some_fn();
+
+    it('throws an error', () => {
+      // ...
     });
-    beforeAll(() => {
-      //some hook code
+
+    afterEach(() => {
+      clearLogger();
     });
-    afterAll(() => {
-      //some hook code
+    beforeEach(() => {
+      mockLogger();
     });
-    test('inner bar', () => {
-      some_fn();
+
+    it('logs a message', () => {
+      // ...
     });
   });
+
+  afterAll(() => {
+    removeMyDatabase();
+  });
 });
 ```
 
@@ -61,35 +69,51 @@ Examples of **correct** code for this rule
 /* eslint jest/prefer-hooks-on-top: "error" */
 
 describe('foo', () => {
-  beforeEach(() => {
-    //some hook code
+  beforeAll(() => {
+    createMyDatabase();
   });
 
-  // Not affected by rule
-  someSetup();
-
-  afterEach(() => {
-    //some hook code
+  beforeEach(() => {
+    seedMyDatabase();
   });
-  test('bar', () => {
-    some_fn();
+
+  afterAll(() => {
+    clearMyDatabase();
   });
-});
 
-// Nested describe scenario
-describe('foo', () => {
-  beforeEach(() => {
-    //some hook code
+  it('accepts this input', () => {
+    // ...
   });
-  test('bar', () => {
-    some_fn();
+
+  it('returns that value', () => {
+    // ...
   });
-  describe('inner_foo', () => {
+
+  describe('when the database has specific values', () => {
+    const specificValue = '...';
+
     beforeEach(() => {
-      //some hook code
+      seedMyDatabase(specificValue);
     });
-    test('inner bar', () => {
-      some_fn();
+
+    beforeEach(() => {
+      mockLogger();
+    });
+
+    afterEach(() => {
+      clearLogger();
+    });
+
+    it('accepts that input', () => {
+      // ...
+    });
+
+    it('throws an error', () => {
+      // ...
+    });
+
+    it('logs a message', () => {
+      // ...
     });
   });
 });

package/docs/rules/{lowercase-name.md → prefer-lowercase-title.md}

@@ -1,4 +1,4 @@
-# Enforce lowercase test names (`lowercase-name`)
+# Enforce lowercase test names (`prefer-lowercase-title`)
 
 ## Rule details
 
@@ -26,7 +26,7 @@ it('adds 1 + 2 to equal 3', () => {
 
 ```json
 {
-  "jest/lowercase-name": [
+  "jest/prefer-lowercase-title": [
     "error",
     {
       "ignore": ["describe", "test"]
@@ -50,7 +50,7 @@ By default, none of these options are enabled (the equivalent of
 Example of **correct** code for the `{ "ignore": ["describe"] }` option:
 
 ```js
-/* eslint jest/lowercase-name: ["error", { "ignore": ["describe"] }] */
+/* eslint jest/prefer-lowercase-title: ["error", { "ignore": ["describe"] }] */
 
 describe('Uppercase description');
 ```
@@ -58,7 +58,7 @@ describe('Uppercase description');
 Example of **correct** code for the `{ "ignore": ["test"] }` option:
 
 ```js
-/* eslint jest/lowercase-name: ["error", { "ignore": ["test"] }] */
+/* eslint jest/prefer-lowercase-title: ["error", { "ignore": ["test"] }] */
 
 test('Uppercase description');
 ```
@@ -66,7 +66,7 @@ test('Uppercase description');
 Example of **correct** code for the `{ "ignore": ["it"] }` option:
 
 ```js
-/* eslint jest/lowercase-name: ["error", { "ignore": ["it"] }] */
+/* eslint jest/prefer-lowercase-title: ["error", { "ignore": ["it"] }] */
 
 it('Uppercase description');
 ```
@@ -82,7 +82,7 @@ By default, nothing is allowed (the equivalent of `{ "allowedPrefixes": [] }`).
 Example of **correct** code for the `{ "allowedPrefixes": ["GET"] }` option:
 
 ```js
-/* eslint jest/lowercase-name: ["error", { "allowedPrefixes": ["GET"] }] */
+/* eslint jest/prefer-lowercase-title: ["error", { "allowedPrefixes": ["GET"] }] */
 
 describe('GET /live');
 ```
@@ -95,7 +95,7 @@ title starting with an upper-case letter.
 Example of **correct** code for the `{ "ignoreTopLevelDescribe": true }` option:
 
 ```js
-/* eslint jest/lowercase-name: ["error", { "ignoreTopLevelDescribe": true }] */
+/* eslint jest/prefer-lowercase-title: ["error", { "ignoreTopLevelDescribe": true }] */
 describe('MyClass', () => {
   describe('#myMethod', () => {
     it('does things', () => {

package/docs/rules/prefer-snapshot-hint.md

@@ -0,0 +1,188 @@
+# Prefer including a hint with external snapshots (`prefer-snapshot-hint`)
+
+When working with external snapshot matchers it's considered best practice to
+provide a hint (as the last argument to the matcher) describing the expected
+snapshot content that will be included in the snapshots name by Jest.
+
+This makes it easier for reviewers to verify the snapshots during review, and
+for anyone to know whether an outdated snapshot is the correct behavior before
+updating.
+
+## Rule details
+
+This rule looks for any use of an external snapshot matcher (e.g.
+`toMatchSnapshot` and `toThrowErrorMatchingSnapshot`) and checks if they include
+a snapshot hint.
+
+## Options
+
+### `'always'`
+
+Require a hint to _always_ be provided when using external snapshot matchers.
+
+Examples of **incorrect** code for the `'always'` option:
+
+```js
+const snapshotOutput = ({ stdout, stderr }) => {
+  expect(stdout).toMatchSnapshot();
+  expect(stderr).toMatchSnapshot();
+};
+
+describe('cli', () => {
+  describe('--version flag', () => {
+    it('prints the version', async () => {
+      snapshotOutput(await runCli(['--version']));
+    });
+  });
+
+  describe('--config flag', () => {
+    it('reads the config', async () => {
+      const { stdout, parsedConfig } = await runCli([
+        '--config',
+        'jest.config.js',
+      ]);
+
+      expect(stdout).toMatchSnapshot();
+      expect(parsedConfig).toMatchSnapshot();
+    });
+
+    it('prints nothing to stderr', async () => {
+      const { stderr } = await runCli(['--config', 'jest.config.js']);
+
+      expect(stderr).toMatchSnapshot();
+    });
+
+    describe('when the file does not exist', () => {
+      it('throws an error', async () => {
+        await expect(
+          runCli(['--config', 'does-not-exist.js']),
+        ).rejects.toThrowErrorMatchingSnapshot();
+      });
+    });
+  });
+});
+```
+
+Examples of **correct** code for the `'always'` option:
+
+```js
+const snapshotOutput = ({ stdout, stderr }, hints) => {
+  expect(stdout).toMatchSnapshot({}, `stdout: ${hints.stdout}`);
+  expect(stderr).toMatchSnapshot({}, `stderr: ${hints.stderr}`);
+};
+
+describe('cli', () => {
+  describe('--version flag', () => {
+    it('prints the version', async () => {
+      snapshotOutput(await runCli(['--version']), {
+        stdout: 'version string',
+        stderr: 'empty',
+      });
+    });
+  });
+
+  describe('--config flag', () => {
+    it('reads the config', async () => {
+      const { stdout } = await runCli(['--config', 'jest.config.js']);
+
+      expect(stdout).toMatchSnapshot({}, 'stdout: config settings');
+    });
+
+    it('prints nothing to stderr', async () => {
+      const { stderr } = await runCli(['--config', 'jest.config.js']);
+
+      expect(stderr).toMatchInlineSnapshot();
+    });
+
+    describe('when the file does not exist', () => {
+      it('throws an error', async () => {
+        await expect(
+          runCli(['--config', 'does-not-exist.js']),
+        ).rejects.toThrowErrorMatchingSnapshot('stderr: config error');
+      });
+    });
+  });
+});
+```
+
+### `'multi'` (default)
+
+Require a hint to be provided when there are multiple external snapshot matchers
+within the scope (meaning it includes nested calls).
+
+Examples of **incorrect** code for the `'multi'` option:
+
+```js
+const snapshotOutput = ({ stdout, stderr }) => {
+  expect(stdout).toMatchSnapshot();
+  expect(stderr).toMatchSnapshot();
+};
+
+describe('cli', () => {
+  describe('--version flag', () => {
+    it('prints the version', async () => {
+      snapshotOutput(await runCli(['--version']));
+    });
+  });
+
+  describe('--config flag', () => {
+    it('reads the config', async () => {
+      const { stdout, parsedConfig } = await runCli([
+        '--config',
+        'jest.config.js',
+      ]);
+
+      expect(stdout).toMatchSnapshot();
+      expect(parsedConfig).toMatchSnapshot();
+    });
+
+    it('prints nothing to stderr', async () => {
+      const { stderr } = await runCli(['--config', 'jest.config.js']);
+
+      expect(stderr).toMatchSnapshot();
+    });
+  });
+});
+```
+
+Examples of **correct** code for the `'multi'` option:
+
+```js
+const snapshotOutput = ({ stdout, stderr }, hints) => {
+  expect(stdout).toMatchSnapshot({}, `stdout: ${hints.stdout}`);
+  expect(stderr).toMatchSnapshot({}, `stderr: ${hints.stderr}`);
+};
+
+describe('cli', () => {
+  describe('--version flag', () => {
+    it('prints the version', async () => {
+      snapshotOutput(await runCli(['--version']), {
+        stdout: 'version string',
+        stderr: 'empty',
+      });
+    });
+  });
+
+  describe('--config flag', () => {
+    it('reads the config', async () => {
+      const { stdout } = await runCli(['--config', 'jest.config.js']);
+
+      expect(stdout).toMatchSnapshot();
+    });
+
+    it('prints nothing to stderr', async () => {
+      const { stderr } = await runCli(['--config', 'jest.config.js']);
+
+      expect(stderr).toMatchInlineSnapshot();
+    });
+
+    describe('when the file does not exist', () => {
+      it('throws an error', async () => {
+        await expect(
+          runCli(['--config', 'does-not-exist.js']),
+        ).rejects.toThrowErrorMatchingSnapshot();
+      });
+    });
+  });
+});
+```

package/docs/rules/prefer-to-be.md

@@ -0,0 +1,53 @@
+# Suggest using `toBe()` for primitive literals (`prefer-to-be`)
+
+When asserting against primitive literals such as numbers and strings, the
+equality matchers all operate the same, but read slightly differently in code.
+
+This rule recommends using the `toBe` matcher in these situations, as it forms
+the most grammatically natural sentence. For `null`, `undefined`, and `NaN` this
+rule recommends using their specific `toBe` matchers, as they give better error
+messages as well.
+
+## Rule details
+
+This rule triggers a warning if `toEqual()` or `toStrictEqual()` are used to
+assert a primitive literal value such as numbers, strings, and booleans.
+
+The following patterns are considered warnings:
+
+```js
+expect(value).not.toEqual(5);
+expect(getMessage()).toStrictEqual('hello world');
+expect(loadMessage()).resolves.toEqual('hello world');
+```
+
+The following pattern is not warning:
+
+```js
+expect(value).not.toBe(5);
+expect(getMessage()).toBe('hello world');
+expect(loadMessage()).resolves.toBe('hello world');
+expect(didError).not.toBe(true);
+
+expect(catchError()).toStrictEqual({ message: 'oh noes!' });
+```
+
+For `null`, `undefined`, and `NaN`, this rule triggers a warning if `toBe` is
+used to assert against those literal values instead of their more specific
+`toBe` counterparts:
+
+```js
+expect(value).not.toBe(undefined);
+expect(getMessage()).toBe(null);
+expect(countMessages()).resolves.not.toBe(NaN);
+```
+
+The following pattern is not warning:
+
+```js
+expect(value).toBeDefined();
+expect(getMessage()).toBeNull();
+expect(countMessages()).resolves.not.toBeNaN();
+
+expect(catchError()).toStrictEqual({ message: undefined });
+```