Merge branch 'main' into next

CHANGELOG.md

@@ -60,6 +60,36 @@
 
 * Drop support for Node 10 and 15
 
+# [24.7.0](https://github.com/jest-community/eslint-plugin-jest/compare/v24.6.0...v24.7.0) (2021-10-10)
+
+
+### Features
+
+* create `require-hook` rule ([#929](https://github.com/jest-community/eslint-plugin-jest/issues/929)) ([6204b31](https://github.com/jest-community/eslint-plugin-jest/commit/6204b311e849b51a0e4705015575139f590ae7a4))
+* deprecate `prefer-to-be-null` rule ([4db9161](https://github.com/jest-community/eslint-plugin-jest/commit/4db91612e988e84ac2facbfe466331b22eeccec9))
+* deprecate `prefer-to-be-undefined` rule ([fa08f09](https://github.com/jest-community/eslint-plugin-jest/commit/fa08f0944e89915fb215bbeff970f12459121cb8))
+
+# [24.6.0](https://github.com/jest-community/eslint-plugin-jest/compare/v24.5.2...v24.6.0) (2021-10-09)
+
+
+### Features
+
+* **valid-expect-in-promise:** re-implement rule ([#916](https://github.com/jest-community/eslint-plugin-jest/issues/916)) ([7a49c58](https://github.com/jest-community/eslint-plugin-jest/commit/7a49c5831e3d85a60c11e385203b8f83d98ad580))
+
+## [24.5.2](https://github.com/jest-community/eslint-plugin-jest/compare/v24.5.1...v24.5.2) (2021-10-04)
+
+
+### Bug Fixes
+
+* **lowercase-name:** consider skip and only prefixes for ignores ([#923](https://github.com/jest-community/eslint-plugin-jest/issues/923)) ([8716c24](https://github.com/jest-community/eslint-plugin-jest/commit/8716c24678ea7dc7c9f692b573d1ea19a67efd84))
+
+## [24.5.1](https://github.com/jest-community/eslint-plugin-jest/compare/v24.5.0...v24.5.1) (2021-10-04)
+
+
+### Bug Fixes
+
+* **prefer-to-be:** don't consider RegExp literals as `toBe`-able ([#922](https://github.com/jest-community/eslint-plugin-jest/issues/922)) ([99b6d42](https://github.com/jest-community/eslint-plugin-jest/commit/99b6d429e697d60645b4bc64ee4ae34d7016118c))
+
 # [24.5.0](https://github.com/jest-community/eslint-plugin-jest/compare/v24.4.3...v24.5.0) (2021-09-29)
 
 

README.md

@@ -184,16 +184,15 @@ installations requiring long-term consistency.
 | [prefer-spy-on](docs/rules/prefer-spy-on.md) | Suggest using `jest.spyOn()` | | ![fixable][] |
 | [prefer-strict-equal](docs/rules/prefer-strict-equal.md) | Suggest using `toStrictEqual()` | | ![suggest][] |
 | [prefer-to-be](docs/rules/prefer-to-be.md) | Suggest using `toBe()` for primitive literals | | ![fixable][] |
-| [prefer-to-be-null](docs/rules/prefer-to-be-null.md) | Suggest using `toBeNull()` | ![style][] | ![fixable][] |
-| [prefer-to-be-undefined](docs/rules/prefer-to-be-undefined.md) | Suggest using `toBeUndefined()` | ![style][] | ![fixable][] |
 | [prefer-to-contain](docs/rules/prefer-to-contain.md) | Suggest using `toContain()` | ![style][] | ![fixable][] |
 | [prefer-to-have-length](docs/rules/prefer-to-have-length.md) | Suggest using `toHaveLength()` | ![style][] | ![fixable][] |
 | [prefer-todo](docs/rules/prefer-todo.md) | Suggest using `test.todo` | | ![fixable][] |
+| [require-hook](docs/rules/require-hook.md) | Require setup and teardown code to be within a hook | | |
 | [require-to-throw-message](docs/rules/require-to-throw-message.md) | Require a message for `toThrow()` | | |
 | [require-top-level-describe](docs/rules/require-top-level-describe.md) | Require test cases and hooks to be inside a `describe` block | | |
 | [valid-describe](docs/rules/valid-describe.md) | Enforce valid `describe()` callback | ![recommended][] | |
 | [valid-expect](docs/rules/valid-expect.md) | Enforce valid `expect()` usage | ![recommended][] | |
-| [valid-expect-in-promise](docs/rules/valid-expect-in-promise.md) | Enforce having return statement when testing with promises  | ![recommended][] | |
+| [valid-expect-in-promise](docs/rules/valid-expect-in-promise.md) | Ensure promises that have expectations in their chain are valid | ![recommended][] | |
 | [valid-title](docs/rules/valid-title.md) | Enforce valid titles | ![recommended][] | ![fixable][] |
 
 <!-- end base rules list -->

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

@@ -1,5 +1,9 @@
 # Suggest using `toBeNull()` (`prefer-to-be-null`)
 
+## Deprecated
+
+This rule has been deprecated in favor of [`prefer-to-be`](prefer-to-be.md).
+
 In order to have a better failure message, `toBeNull()` should be used upon
 asserting expectations on null value.
 

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

@@ -1,5 +1,9 @@
 # Suggest using `toBeUndefined()` (`prefer-to-be-undefined`)
 
+## Deprecated
+
+This rule has been deprecated in favor of [`prefer-to-be`](prefer-to-be.md).
+
 In order to have a better failure message, `toBeUndefined()` should be used upon
 asserting expectations on undefined value.
 

docs/rules/require-hook.md

@@ -0,0 +1,149 @@
+# Require setup and teardown code to be within a hook (`require-hook`)
+
+Often while writing tests you have some setup work that needs to happen before
+tests run, and you have some finishing work that needs to happen after tests
+run. Jest provides helper functions to handle this.
+
+It's common when writing tests to need to perform setup work that needs to
+happen before tests run, and finishing work after tests run.
+
+Because Jest executes all `describe` handlers in a test file _before_ it
+executes any of the actual tests, it's important to ensure setup and teardown
+work is done inside `before*` and `after*` handlers respectively, rather than
+inside the `describe` blocks.
+
+## Rule details
+
+This rule flags any expression that is either at the toplevel of a test file or
+directly within the body of a `describe`, _except_ for the following:
+
+- `import` statements
+- `const` variables
+- `let` _declarations_
+- Types
+- Calls to the standard Jest globals
+
+This rule flags any function calls within test files that are directly within
+the body of a `describe`, and suggests wrapping them in one of the four
+lifecycle hooks.
+
+Here is a slightly contrived test file showcasing some common cases that would
+be flagged:
+
+```js
+import { database, isCity } from '../database';
+import { Logger } from '../../../src/Logger';
+import { loadCities } from '../api';
+
+jest.mock('../api');
+
+const initializeCityDatabase = () => {
+ database.addCity('Vienna');
+ database.addCity('San Juan');
+ database.addCity('Wellington');
+};
+
+const clearCityDatabase = () => {
+ database.clear();
+};
+
+initializeCityDatabase();
+
+test('that persists cities', () => {
+ expect(database.cities.length).toHaveLength(3);
+});
+
+test('city database has Vienna', () => {
+ expect(isCity('Vienna')).toBeTruthy();
+});
+
+test('city database has San Juan', () => {
+ expect(isCity('San Juan')).toBeTruthy();
+});
+
+describe('when loading cities from the api', () => {
+ let consoleWarnSpy = jest.spyOn(console, 'warn');
+
+ loadCities.mockResolvedValue(['Wellington', 'London']);
+
+ it('does not duplicate cities', async () => {
+ await database.loadCities();
+
+ expect(database.cities).toHaveLength(4);
+ });
+
+ it('logs any duplicates', async () => {
+ await database.loadCities();
+
+ expect(consoleWarnSpy).toHaveBeenCalledWith(
+ 'Ignored duplicate cities: Wellington',
+ );
+ });
+});
+
+clearCityDatabase();
+```
+
+Here is the same slightly contrived test file showcasing the same common cases
+but in ways that would be **not** flagged:
+
+```js
+import { database, isCity } from '../database';
+import { Logger } from '../../../src/Logger';
+import { loadCities } from '../api';
+
+jest.mock('../api');
+
+const initializeCityDatabase = () => {
+ database.addCity('Vienna');
+ database.addCity('San Juan');
+ database.addCity('Wellington');
+};
+
+const clearCityDatabase = () => {
+ database.clear();
+};
+
+beforeEach(() => {
+ initializeCityDatabase();
+});
+
+test('that persists cities', () => {
+ expect(database.cities.length).toHaveLength(3);
+});
+
+test('city database has Vienna', () => {
+ expect(isCity('Vienna')).toBeTruthy();
+});
+
+test('city database has San Juan', () => {
+ expect(isCity('San Juan')).toBeTruthy();
+});
+
+describe('when loading cities from the api', () => {
+ let consoleWarnSpy;
+
+ beforeEach(() => {
+ consoleWarnSpy = jest.spyOn(console, 'warn');
+ loadCities.mockResolvedValue(['Wellington', 'London']);
+ });
+
+ it('does not duplicate cities', async () => {
+ await database.loadCities();
+
+ expect(database.cities).toHaveLength(4);
+ });
+
+ it('logs any duplicates', async () => {
+ await database.loadCities();
+
+ expect(consoleWarnSpy).toHaveBeenCalledWith(
+ 'Ignored duplicate cities: Wellington',
+ );
+ });
+});
+
+afterEach(() => {
+ clearCityDatabase();
+});
+```

docs/rules/valid-expect-in-promise.md

@@ -1,31 +1,72 @@
-# Enforce having return statement when testing with promises (`valid-expect-in-promise`)
+# Ensure promises that have expectations in their chain are valid (`valid-expect-in-promise`)
 
-Ensure to return promise when having assertions in `then` or `catch` block of
-promise
+Ensure promises that include expectations are returned or awaited.
 
 ## Rule details
 
-This rule looks for tests that have assertions in `then` and `catch` methods on
-promises that are not returned by the test.
+This rule flags any promises within the body of a test that include expectations
+that have either not been returned or awaited.
 
-### Default configuration
-
-The following pattern is considered warning:
+The following patterns is considered warning:
 
 ```js
-it('promise test', () => {
- somePromise.then(data => {
- expect(data).toEqual('foo');
+it('promises a person', () => {
+ api.getPersonByName('bob').then(person => {
+ expect(person).toHaveProperty('name', 'Bob');
+ });
+});
+
+it('promises a counted person', () => {
+ const promise = api.getPersonByName('bob').then(person => {
+ expect(person).toHaveProperty('name', 'Bob');
+ });
+
+ promise.then(() => {
+ expect(analytics.gottenPeopleCount).toBe(1);
  });
 });
+
+it('promises multiple people', () => {
+ const firstPromise = api.getPersonByName('bob').then(person => {
+ expect(person).toHaveProperty('name', 'Bob');
+ });
+ const secondPromise = api.getPersonByName('alice').then(person => {
+ expect(person).toHaveProperty('name', 'Alice');
+ });
+
+ return Promise.any([firstPromise, secondPromise]);
+});
 ```
 
 The following pattern is not warning:
 
 ```js
-it('promise test', () => {
- return somePromise.then(data => {
- expect(data).toEqual('foo');
+it('promises a person', async () => {
+ await api.getPersonByName('bob').then(person => {
+ expect(person).toHaveProperty('name', 'Bob');
  });
 });
+
+it('promises a counted person', () => {
+ let promise = api.getPersonByName('bob').then(person => {
+ expect(person).toHaveProperty('name', 'Bob');
+ });
+
+ promise = promise.then(() => {
+ expect(analytics.gottenPeopleCount).toBe(1);
+ });
+
+ return promise;
+});
+
+it('promises multiple people', () => {
+ const firstPromise = api.getPersonByName('bob').then(person => {
+ expect(person).toHaveProperty('name', 'Bob');
+ });
+ const secondPromise = api.getPersonByName('alice').then(person => {
+ expect(person).toHaveProperty('name', 'Alice');
+ });
+
+ return Promise.allSettled([firstPromise, secondPromise]);
+});
 ```

src/__tests__/__snapshots__/rules.test.ts.snap

@@ -42,11 +42,10 @@ Object {
  "jest/prefer-spy-on": "error",
  "jest/prefer-strict-equal": "error",
  "jest/prefer-to-be": "error",
- "jest/prefer-to-be-null": "error",
- "jest/prefer-to-be-undefined": "error",
  "jest/prefer-to-contain": "error",
  "jest/prefer-to-have-length": "error",
  "jest/prefer-todo": "error",
+ "jest/require-hook": "error",
  "jest/require-to-throw-message": "error",
  "jest/require-top-level-describe": "error",
  "jest/unbound-method": "error",

src/__tests__/rules.test.ts

@@ -2,7 +2,7 @@ import { existsSync } from 'fs';
 import { resolve } from 'path';
 import plugin from '../';
 
-const numberOfRules = 44;
+const numberOfRules = 45;
 const ruleNames = Object.keys(plugin.rules);
 const deprecatedRules = Object.entries(plugin.rules)
  .filter(([, rule]) => rule.meta.deprecated)