eslint-plugin-jest 24.6.0 → 24.7.0

package/CHANGELOG.md

@@ -1,3 +1,12 @@
+# [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)
 
 

package/README.md

@@ -184,11 +184,10 @@ 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][] |              |

package/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.
 

package/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.
 

package/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();
+});
+```

package/lib/rules/prefer-to-be-null.js

@@ -33,6 +33,8 @@ var _default = (0, _utils.createRule)({
     messages: {
       useToBeNull: 'Use toBeNull() instead'
     },
+    deprecated: true,
+    replacedBy: ['prefer-to-be'],
     fixable: 'code',
     type: 'suggestion',
     schema: []

package/lib/rules/prefer-to-be-undefined.js

@@ -33,6 +33,8 @@ var _default = (0, _utils.createRule)({
     messages: {
       useToBeUndefined: 'Use toBeUndefined() instead'
     },
+    deprecated: true,
+    replacedBy: ['prefer-to-be'],
     fixable: 'code',
     type: 'suggestion',
     schema: []

package/lib/rules/require-hook.js

@@ -0,0 +1,87 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.default = void 0;
+
+var _experimentalUtils = require("@typescript-eslint/experimental-utils");
+
+var _utils = require("./utils");
+
+const isJestFnCall = node => {
+  var _getNodeName;
+
+  if ((0, _utils.isDescribeCall)(node) || (0, _utils.isTestCaseCall)(node) || (0, _utils.isHook)(node)) {
+    return true;
+  }
+
+  return !!((_getNodeName = (0, _utils.getNodeName)(node)) !== null && _getNodeName !== void 0 && _getNodeName.startsWith('jest.'));
+};
+
+const shouldBeInHook = node => {
+  switch (node.type) {
+    case _experimentalUtils.AST_NODE_TYPES.ExpressionStatement:
+      return shouldBeInHook(node.expression);
+
+    case _experimentalUtils.AST_NODE_TYPES.CallExpression:
+      return !isJestFnCall(node);
+
+    default:
+      return false;
+  }
+};
+
+var _default = (0, _utils.createRule)({
+  name: __filename,
+  meta: {
+    docs: {
+      category: 'Best Practices',
+      description: 'Require setup and teardown code to be within a hook',
+      recommended: false
+    },
+    messages: {
+      useHook: 'This should be done within a hook'
+    },
+    type: 'suggestion',
+    schema: []
+  },
+  defaultOptions: [],
+
+  create(context) {
+    const checkBlockBody = body => {
+      for (const statement of body) {
+        if (shouldBeInHook(statement)) {
+          context.report({
+            node: statement,
+            messageId: 'useHook'
+          });
+        }
+      }
+    };
+
+    return {
+      Program(program) {
+        checkBlockBody(program.body);
+      },
+
+      CallExpression(node) {
+        if (!(0, _utils.isDescribeCall)(node) || node.arguments.length < 2) {
+          return;
+        }
+
+        const [, testFn] = node.arguments;
+
+        if (!(0, _utils.isFunction)(testFn) || testFn.body.type !== _experimentalUtils.AST_NODE_TYPES.BlockStatement) {
+          return;
+        }
+
+        checkBlockBody(testFn.body.body);
+      }
+
+    };
+  }
+
+});
+
+exports.default = _default;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "eslint-plugin-jest",
-  "version": "24.6.0",
+  "version": "24.7.0",
   "description": "Eslint rules for Jest",
   "keywords": [
     "eslint",