eslint-plugin-jest 24.4.2 → 26.1.0

package/docs/rules/require-hook.md

@@ -0,0 +1,187 @@
+# 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_, and initializations to `null` or `undefined`
+- Classes
+- 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();
+});
+```
+
+## Options
+
+If there are methods that you want to call outside of hooks and tests, you can
+mark them as allowed using the `allowedFunctionCalls` option.
+
+```json
+{
+  "jest/require-hook": [
+    "error",
+    {
+      "allowedFunctionCalls": ["enableAutoDestroy"]
+    }
+  ]
+}
+```
+
+Examples of **correct** code when using
+`{ "allowedFunctionCalls": ["enableAutoDestroy"] }` option:
+
+```js
+/* eslint jest/require-hook: ["error", { "allowedFunctionCalls": ["enableAutoDestroy"] }] */
+
+import { enableAutoDestroy, mount } from '@vue/test-utils';
+import { initDatabase, tearDownDatabase } from './databaseUtils';
+
+enableAutoDestroy(afterEach);
+
+beforeEach(initDatabase);
+afterEach(tearDownDatabase);
+
+describe('Foo', () => {
+  test('always returns 42', () => {
+    expect(global.getAnswer()).toBe(42);
+  });
+});
+```

package/docs/rules/require-top-level-describe.md

@@ -47,6 +47,34 @@ describe('test suite', () => {
 });
 ```
 
+You can also enforce a limit on the number of describes allowed at the top-level
+using the `maxNumberOfTopLevelDescribes` option:
+
+```json
+{
+  "jest/require-top-level-describe": [
+    "error",
+    {
+      "maxNumberOfTopLevelDescribes": 2
+    }
+  ]
+}
+```
+
+Examples of **incorrect** code with the above config:
+
+```js
+describe('test suite', () => {
+  it('test', () => {});
+});
+
+describe('test suite', () => {});
+
+describe('test suite', () => {});
+```
+
+This option defaults to `Infinity`, allowing any number of top-level describes.
+
 ## When Not To Use It
 
 Don't use this rule on non-jest test files.

package/docs/rules/{valid-describe.md → valid-describe-callback.md}

@@ -1,4 +1,4 @@
-# Enforce valid `describe()` callback (`valid-describe`)
+# Enforce valid `describe()` callback (`valid-describe-callback`)
 
 Using an improper `describe()` callback function can lead to unexpected test
 errors.

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

package/docs/rules/valid-expect.md

@@ -38,6 +38,11 @@ This rule is enabled by default.
       type: 'boolean',
       default: false,
     },
+    asyncMatchers: {
+      type: 'array',
+      items: { type: 'string' },
+      default: ['toResolve', 'toReject'],
+    },
     minArgs: {
       type: 'number',
       minimum: 1,
@@ -78,6 +83,14 @@ test('test1', async () => {
 test('test2', () => expect(Promise.resolve(2)).resolves.toBe(2));
 ```
 
+### `asyncMatchers`
+
+Allows specifying which matchers return promises, and so should be considered
+async when checking if an `expect` should be returned or awaited.
+
+By default, this has a list of all the async matchers provided by
+`jest-extended` (namely, `toResolve` and `toReject`).
+
 ### `minArgs` & `maxArgs`
 
 Enforces the minimum and maximum number of arguments that `expect` can take, and

package/docs/rules/valid-title.md

@@ -198,8 +198,9 @@ describe('the proper way to handle things', () => {});
 Defaults: `{}`
 
 Allows enforcing that titles must match or must not match a given Regular
-Expression. An object can be provided to apply different Regular Expressions to
-specific Jest test function groups (`describe`, `test`, and `it`).
+Expression, with an optional message. An object can be provided to apply
+different Regular Expressions (with optional messages) to specific Jest test
+function groups (`describe`, `test`, and `it`).
 
 Examples of **incorrect** code when using `mustMatch`:
 
@@ -226,3 +227,30 @@ describe('the tests that will be run', () => {});
 test('that the stuff works', () => {});
 xtest('that errors that thrown have messages', () => {});
 ```
+
+Optionally you can provide a custom message to show for a particular matcher by
+using a tuple at any level where you can provide a matcher:
+
+```js
+const prefixes = ['when', 'with', 'without', 'if', 'unless', 'for'];
+const prefixesList = prefixes.join('  - \n');
+
+module.exports = {
+  rules: {
+    'jest/valid-title': [
+      'error',
+      {
+        mustNotMatch: ['\\.$', 'Titles should not end with a full-stop'],
+        mustMatch: {
+          describe: [
+            new RegExp(`^(?:[A-Z]|\\b(${prefixes.join('|')})\\b`, 'u').source,
+            `Describe titles should either start with a capital letter or one of the following prefixes: ${prefixesList}`,
+          ],
+          test: [/[^A-Z]/u.source],
+          it: /[^A-Z]/u.source,
+        },
+      },
+    ],
+  },
+};
+```

package/lib/index.js

@@ -25,7 +25,7 @@ const importDefault = moduleName => // eslint-disable-next-line @typescript-esli
 interopRequireDefault(require(moduleName)).default;
 
 const rulesDir = (0, _path.join)(__dirname, 'rules');
-const excludedFiles = ['__tests__', 'utils'];
+const excludedFiles = ['__tests__', 'detectJestVersion', 'utils'];
 const rules = (0, _fs.readdirSync)(rulesDir).map(rule => (0, _path.parse)(rule).name).filter(rule => !excludedFiles.includes(rule)).reduce((acc, curr) => ({ ...acc,
   [curr]: importDefault((0, _path.join)(rulesDir, curr))
 }), {});
@@ -52,8 +52,7 @@ module.exports = {
       plugins: ['jest'],
       rules: {
         'jest/no-alias-methods': 'warn',
-        'jest/prefer-to-be-null': 'error',
-        'jest/prefer-to-be-undefined': 'error',
+        'jest/prefer-to-be': 'error',
         'jest/prefer-to-contain': 'error',
         'jest/prefer-to-have-length': 'error'
       }

package/lib/processors/snapshot-processor.js

@@ -3,7 +3,7 @@
 Object.defineProperty(exports, "__esModule", {
   value: true
 });
-exports.postprocess = exports.preprocess = void 0;
+exports.preprocess = exports.postprocess = void 0;
 
 // https://eslint.org/docs/developer-guide/working-with-plugins#processors-in-plugins
 // https://github.com/typescript-eslint/typescript-eslint/issues/808

package/lib/rules/consistent-test-it.js

@@ -5,13 +5,13 @@ Object.defineProperty(exports, "__esModule", {
 });
 exports.default = void 0;
 
-var _experimentalUtils = require("@typescript-eslint/experimental-utils");
+var _utils = require("@typescript-eslint/utils");
 
-var _utils = require("./utils");
+var _utils2 = require("./utils");
 
-const buildFixer = (callee, nodeName, preferredTestKeyword) => fixer => [fixer.replaceText(callee.type === _experimentalUtils.AST_NODE_TYPES.MemberExpression ? callee.object : callee, getPreferredNodeName(nodeName, preferredTestKeyword))];
+const buildFixer = (callee, nodeName, preferredTestKeyword) => fixer => [fixer.replaceText(callee.type === _utils.AST_NODE_TYPES.MemberExpression ? callee.object : callee, getPreferredNodeName(nodeName, preferredTestKeyword))];
 
-var _default = (0, _utils.createRule)({
+var _default = (0, _utils2.createRule)({
   name: __filename,
   meta: {
     docs: {
@@ -28,10 +28,10 @@ var _default = (0, _utils.createRule)({
       type: 'object',
       properties: {
         fn: {
-          enum: [_utils.TestCaseName.it, _utils.TestCaseName.test]
+          enum: [_utils2.TestCaseName.it, _utils2.TestCaseName.test]
         },
         withinDescribe: {
-          enum: [_utils.TestCaseName.it, _utils.TestCaseName.test]
+          enum: [_utils2.TestCaseName.it, _utils2.TestCaseName.test]
         }
       },
       additionalProperties: false
@@ -39,30 +39,30 @@ var _default = (0, _utils.createRule)({
     type: 'suggestion'
   },
   defaultOptions: [{
-    fn: _utils.TestCaseName.test,
-    withinDescribe: _utils.TestCaseName.it
+    fn: _utils2.TestCaseName.test,
+    withinDescribe: _utils2.TestCaseName.it
   }],
 
   create(context) {
     const configObj = context.options[0] || {};
-    const testKeyword = configObj.fn || _utils.TestCaseName.test;
-    const testKeywordWithinDescribe = configObj.withinDescribe || configObj.fn || _utils.TestCaseName.it;
+    const testKeyword = configObj.fn || _utils2.TestCaseName.test;
+    const testKeywordWithinDescribe = configObj.withinDescribe || configObj.fn || _utils2.TestCaseName.it;
     let describeNestingLevel = 0;
     return {
       CallExpression(node) {
-        const nodeName = (0, _utils.getNodeName)(node.callee);
+        const nodeName = (0, _utils2.getNodeName)(node.callee);
 
         if (!nodeName) {
           return;
         }
 
-        if ((0, _utils.isDescribeCall)(node)) {
+        if ((0, _utils2.isDescribeCall)(node)) {
           describeNestingLevel++;
         }
 
-        const funcNode = node.callee.type === _experimentalUtils.AST_NODE_TYPES.TaggedTemplateExpression ? node.callee.tag : node.callee.type === _experimentalUtils.AST_NODE_TYPES.CallExpression ? node.callee.callee : node.callee;
+        const funcNode = node.callee.type === _utils.AST_NODE_TYPES.TaggedTemplateExpression ? node.callee.tag : node.callee.type === _utils.AST_NODE_TYPES.CallExpression ? node.callee.callee : node.callee;
 
-        if ((0, _utils.isTestCaseCall)(node) && describeNestingLevel === 0 && !nodeName.includes(testKeyword)) {
+        if ((0, _utils2.isTestCaseCall)(node) && describeNestingLevel === 0 && !nodeName.includes(testKeyword)) {
           const oppositeTestKeyword = getOppositeTestKeyword(testKeyword);
           context.report({
             messageId: 'consistentMethod',
@@ -75,7 +75,7 @@ var _default = (0, _utils.createRule)({
           });
         }
 
-        if ((0, _utils.isTestCaseCall)(node) && describeNestingLevel > 0 && !nodeName.includes(testKeywordWithinDescribe)) {
+        if ((0, _utils2.isTestCaseCall)(node) && describeNestingLevel > 0 && !nodeName.includes(testKeywordWithinDescribe)) {
           const oppositeTestKeyword = getOppositeTestKeyword(testKeywordWithinDescribe);
           context.report({
             messageId: 'consistentMethodWithinDescribe',
@@ -90,7 +90,7 @@ var _default = (0, _utils.createRule)({
       },
 
       'CallExpression:exit'(node) {
-        if ((0, _utils.isDescribeCall)(node)) {
+        if ((0, _utils2.isDescribeCall)(node)) {
           describeNestingLevel--;
         }
       }
@@ -103,7 +103,7 @@ var _default = (0, _utils.createRule)({
 exports.default = _default;
 
 function getPreferredNodeName(nodeName, preferredTestKeyword) {
-  if (nodeName === _utils.TestCaseName.fit) {
+  if (nodeName === _utils2.TestCaseName.fit) {
     return 'test.only';
   }
 
@@ -111,9 +111,9 @@ function getPreferredNodeName(nodeName, preferredTestKeyword) {
 }
 
 function getOppositeTestKeyword(test) {
-  if (test === _utils.TestCaseName.test) {
-    return _utils.TestCaseName.it;
+  if (test === _utils2.TestCaseName.test) {
+    return _utils2.TestCaseName.it;
   }
 
-  return _utils.TestCaseName.test;
+  return _utils2.TestCaseName.test;
 }

package/lib/rules/detectJestVersion.js

@@ -0,0 +1,29 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.detectJestVersion = void 0;
+let cachedJestVersion = null;
+
+const detectJestVersion = () => {
+  if (cachedJestVersion) {
+    return cachedJestVersion;
+  }
+
+  try {
+    const jestPath = require.resolve('jest/package.json');
+
+    const jestPackageJson = // eslint-disable-next-line @typescript-eslint/no-require-imports
+    require(jestPath);
+
+    if (jestPackageJson.version) {
+      const [majorVersion] = jestPackageJson.version.split('.');
+      return cachedJestVersion = parseInt(majorVersion, 10);
+    }
+  } catch {}
+
+  throw new Error('Unable to detect Jest version - please ensure jest package is installed, or otherwise set version explicitly');
+};
+
+exports.detectJestVersion = detectJestVersion;

package/lib/rules/expect-expect.js

@@ -5,9 +5,9 @@ Object.defineProperty(exports, "__esModule", {
 });
 exports.default = void 0;
 
-var _experimentalUtils = require("@typescript-eslint/experimental-utils");
+var _utils = require("@typescript-eslint/utils");
 
-var _utils = require("./utils");
+var _utils2 = require("./utils");
 
 /*
  * This implementation is adapted from eslint-plugin-jasmine.
@@ -28,7 +28,7 @@ function matchesAssertFunctionName(nodeName, patterns) {
   }).join('\\.')}(\\.|$)`, 'ui').test(nodeName));
 }
 
-var _default = (0, _utils.createRule)({
+var _default = (0, _utils2.createRule)({
   name: __filename,
   meta: {
     docs: {
@@ -47,6 +47,12 @@ var _default = (0, _utils.createRule)({
           items: [{
             type: 'string'
           }]
+        },
+        additionalTestBlockFunctions: {
+          type: 'array',
+          items: {
+            type: 'string'
+          }
         }
       },
       additionalProperties: false
@@ -54,21 +60,23 @@ var _default = (0, _utils.createRule)({
     type: 'suggestion'
   },
   defaultOptions: [{
-    assertFunctionNames: ['expect']
+    assertFunctionNames: ['expect'],
+    additionalTestBlockFunctions: []
   }],
 
   create(context, [{
-    assertFunctionNames = ['expect']
+    assertFunctionNames = ['expect'],
+    additionalTestBlockFunctions = []
   }]) {
     const unchecked = [];
 
     function checkCallExpressionUsed(nodes) {
       for (const node of nodes) {
-        const index = node.type === _experimentalUtils.AST_NODE_TYPES.CallExpression ? unchecked.indexOf(node) : -1;
+        const index = node.type === _utils.AST_NODE_TYPES.CallExpression ? unchecked.indexOf(node) : -1;
 
-        if (node.type === _experimentalUtils.AST_NODE_TYPES.FunctionDeclaration) {
+        if (node.type === _utils.AST_NODE_TYPES.FunctionDeclaration) {
           const declaredVariables = context.getDeclaredVariables(node);
-          const testCallExpressions = (0, _utils.getTestCallExpressionsFromDeclaredVariables)(declaredVariables);
+          const testCallExpressions = (0, _utils2.getTestCallExpressionsFromDeclaredVariables)(declaredVariables);
           checkCallExpressionUsed(testCallExpressions);
         }
 
@@ -81,11 +89,17 @@ var _default = (0, _utils.createRule)({
 
     return {
       CallExpression(node) {
-        const name = (0, _utils.getNodeName)(node.callee);
+        var _getNodeName;
+
+        const name = (_getNodeName = (0, _utils2.getNodeName)(node.callee)) !== null && _getNodeName !== void 0 ? _getNodeName : '';
+
+        if ((0, _utils2.isTestCaseCall)(node) || additionalTestBlockFunctions.includes(name)) {
+          if (node.callee.type === _utils.AST_NODE_TYPES.MemberExpression && (0, _utils2.isSupportedAccessor)(node.callee.property, 'todo')) {
+            return;
+          }
 
-        if (name === _utils.TestCaseName.it || name === _utils.TestCaseName.test) {
           unchecked.push(node);
-        } else if (name && matchesAssertFunctionName(name, assertFunctionNames)) {
+        } else if (matchesAssertFunctionName(name, assertFunctionNames)) {
           // Return early in case of nested `it` statements.
           checkCallExpressionUsed(context.getAncestors());
         }

package/lib/rules/max-nested-describe.js

@@ -5,11 +5,11 @@ Object.defineProperty(exports, "__esModule", {
 });
 exports.default = void 0;
 
-var _experimentalUtils = require("@typescript-eslint/experimental-utils");
+var _utils = require("@typescript-eslint/utils");
 
-var _utils = require("./utils");
+var _utils2 = require("./utils");
 
-var _default = (0, _utils.createRule)({
+var _default = (0, _utils2.createRule)({
   name: __filename,
   meta: {
     docs: {
@@ -46,7 +46,7 @@ var _default = (0, _utils.createRule)({
         parent
       } = node;
 
-      if ((parent === null || parent === void 0 ? void 0 : parent.type) !== _experimentalUtils.AST_NODE_TYPES.CallExpression || !(0, _utils.isDescribeCall)(parent)) {
+      if ((parent === null || parent === void 0 ? void 0 : parent.type) !== _utils.AST_NODE_TYPES.CallExpression || !(0, _utils2.isDescribeCall)(parent)) {
         return;
       }
 
@@ -69,7 +69,7 @@ var _default = (0, _utils.createRule)({
         parent
       } = node;
 
-      if ((parent === null || parent === void 0 ? void 0 : parent.type) === _experimentalUtils.AST_NODE_TYPES.CallExpression && (0, _utils.isDescribeCall)(parent)) {
+      if ((parent === null || parent === void 0 ? void 0 : parent.type) === _utils.AST_NODE_TYPES.CallExpression && (0, _utils2.isDescribeCall)(parent)) {
         describeCallbackStack.pop();
       }
     }