eslint-plugin-jest 25.0.0-next.4 → 25.0.0

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/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-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/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/no-deprecated-functions.js

@@ -3,39 +3,21 @@
 Object.defineProperty(exports, "__esModule", {
   value: true
 });
-exports.default = exports._clearCachedJestVersion = void 0;
+exports.default = void 0;
 
 var _experimentalUtils = require("@typescript-eslint/experimental-utils");
 
-var _utils = require("./utils");
-
-let cachedJestVersion = null;
-/** @internal */
+var _detectJestVersion = require("./detectJestVersion");
 
-const _clearCachedJestVersion = () => cachedJestVersion = null;
-
-exports._clearCachedJestVersion = _clearCachedJestVersion;
+var _utils = require("./utils");
 
-const detectJestVersion = () => {
-  if (cachedJestVersion) {
-    return cachedJestVersion;
+const parseJestVersion = rawVersion => {
+  if (typeof rawVersion === 'number') {
+    return rawVersion;
   }
 
-  try {
-    const jestPath = require.resolve('jest/package.json', {
-      paths: [process.cwd()]
-    });
-
-    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');
+  const [majorVersion] = rawVersion.split('.');
+  return parseInt(majorVersion, 10);
 };
 
 var _default = (0, _utils.createRule)({
@@ -58,7 +40,7 @@ var _default = (0, _utils.createRule)({
   create(context) {
     var _context$settings, _context$settings$jes;
 
-    const jestVersion = ((_context$settings = context.settings) === null || _context$settings === void 0 ? void 0 : (_context$settings$jes = _context$settings.jest) === null || _context$settings$jes === void 0 ? void 0 : _context$settings$jes.version) || detectJestVersion();
+    const jestVersion = parseJestVersion(((_context$settings = context.settings) === null || _context$settings === void 0 ? void 0 : (_context$settings$jes = _context$settings.jest) === null || _context$settings$jes === void 0 ? void 0 : _context$settings$jes.version) || (0, _detectJestVersion.detectJestVersion)());
     const deprecations = { ...(jestVersion >= 15 && {
         'jest.resetModuleRegistry': 'jest.resetModules'
       }),

package/lib/rules/no-identical-title.js

@@ -5,8 +5,6 @@ Object.defineProperty(exports, "__esModule", {
 });
 exports.default = void 0;
 
-var _experimentalUtils = require("@typescript-eslint/experimental-utils");
-
 var _utils = require("./utils");
 
 const newDescribeContext = () => ({
@@ -35,13 +33,15 @@ var _default = (0, _utils.createRule)({
     const contexts = [newDescribeContext()];
     return {
       CallExpression(node) {
+        var _getNodeName;
+
         const currentLayer = contexts[contexts.length - 1];
 
         if ((0, _utils.isDescribeCall)(node)) {
           contexts.push(newDescribeContext());
         }
 
-        if (node.callee.type === _experimentalUtils.AST_NODE_TYPES.TaggedTemplateExpression) {
+        if ((_getNodeName = (0, _utils.getNodeName)(node.callee)) !== null && _getNodeName !== void 0 && _getNodeName.endsWith('.each')) {
           return;
         }
 

package/lib/rules/no-large-snapshots.js

@@ -100,8 +100,6 @@ var _default = (0, _utils.createRule)({
 
     return {
       CallExpression(node) {
-        var _matcher$node$parent;
-
         if (!(0, _utils.isExpectCall)(node)) {
           return;
         }
@@ -110,7 +108,7 @@ var _default = (0, _utils.createRule)({
           matcher
         } = (0, _utils.parseExpectCall)(node);
 
-        if ((matcher === null || matcher === void 0 ? void 0 : (_matcher$node$parent = matcher.node.parent) === null || _matcher$node$parent === void 0 ? void 0 : _matcher$node$parent.type) !== _experimentalUtils.AST_NODE_TYPES.CallExpression) {
+        if ((matcher === null || matcher === void 0 ? void 0 : matcher.node.parent.type) !== _experimentalUtils.AST_NODE_TYPES.CallExpression) {
           return;
         }
 

package/lib/rules/prefer-expect-resolves.js

@@ -0,0 +1,48 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.default = void 0;
+
+var _experimentalUtils = require("@typescript-eslint/experimental-utils");
+
+var _utils = require("./utils");
+
+var _default = (0, _utils.createRule)({
+  name: __filename,
+  meta: {
+    docs: {
+      category: 'Best Practices',
+      description: 'Prefer `await expect(...).resolves` over `expect(await ...)` syntax',
+      recommended: false
+    },
+    fixable: 'code',
+    messages: {
+      expectResolves: 'Use `await expect(...).resolves instead.'
+    },
+    schema: [],
+    type: 'suggestion'
+  },
+  defaultOptions: [],
+  create: context => ({
+    CallExpression(node) {
+      const [awaitNode] = node.arguments;
+
+      if ((0, _utils.isExpectCall)(node) && (awaitNode === null || awaitNode === void 0 ? void 0 : awaitNode.type) === _experimentalUtils.AST_NODE_TYPES.AwaitExpression) {
+        context.report({
+          node: node.arguments[0],
+          messageId: 'expectResolves',
+
+          fix(fixer) {
+            return [fixer.insertTextBefore(node, 'await '), fixer.removeRange([awaitNode.range[0], awaitNode.argument.range[0]]), fixer.insertTextAfter(node, '.resolves')];
+          }
+
+        });
+      }
+    }
+
+  })
+});
+
+exports.default = _default;

package/lib/rules/{lowercase-name.js → prefer-lowercase-title.js}

@@ -21,6 +21,24 @@ const findNodeNameAndArgument = node => {
   return [(0, _utils.getNodeName)(node).split('.')[0], node.arguments[0]];
 };
 
+const populateIgnores = ignore => {
+  const ignores = [];
+
+  if (ignore.includes(_utils.DescribeAlias.describe)) {
+    ignores.push(...Object.keys(_utils.DescribeAlias));
+  }
+
+  if (ignore.includes(_utils.TestCaseName.test)) {
+    ignores.push(...Object.keys(_utils.TestCaseName));
+  }
+
+  if (ignore.includes(_utils.TestCaseName.it)) {
+    ignores.push(...Object.keys(_utils.TestCaseName));
+  }
+
+  return ignores;
+};
+
 var _default = (0, _utils.createRule)({
   name: __filename,
   meta: {
@@ -70,6 +88,7 @@ var _default = (0, _utils.createRule)({
     allowedPrefixes = [],
     ignoreTopLevelDescribe
   }]) {
+    const ignores = populateIgnores(ignore);
     let numberOfDescribeBlocks = 0;
     return {
       CallExpression(node) {
@@ -96,7 +115,7 @@ var _default = (0, _utils.createRule)({
 
         const firstCharacter = description.charAt(0);
 
-        if (!firstCharacter || firstCharacter === firstCharacter.toLowerCase() || ignore.includes(name)) {
+        if (!firstCharacter || firstCharacter === firstCharacter.toLowerCase() || ignores.includes(name)) {
           return;
         }