eslint-plugin-jest 21.21.0 → 21.24.0

package/README.md

@@ -83,6 +83,7 @@ for more information about extending configuration files.
 | [consistent-test-it][]       | Enforce consistent test or it keyword                             |                  | ![fixable-green][]  |
 | [expect-expect][]            | Enforce assertion to be made in a test body                       |                  |                     |
 | [lowercase-name][]           | Disallow capitalized test names                                   |                  | ![fixable-green][]  |
+| [no-alias-methods][]         | Disallow alias methods                                            |                  |                     |
 | [no-disabled-tests][]        | Disallow disabled tests                                           | ![recommended][] |                     |
 | [no-focused-tests][]         | Disallow focused tests                                            | ![recommended][] |                     |
 | [no-hooks][]                 | Disallow setup and teardown hooks                                 |                  |                     |
@@ -98,6 +99,7 @@ for more information about extending configuration files.
 | [prefer-to-be-undefined][]   | Suggest using `toBeUndefined()`                                   |                  | ![fixable-green][]  |
 | [prefer-to-have-length][]    | Suggest using `toHaveLength()`                                    | ![recommended][] | ![fixable-green][]  |
 | [prefer-inline-snapshots][]  | Suggest using `toMatchInlineSnapshot()`                           |                  | ![fixable-green][]  |
+| [require-tothrow-message][]  | Require that `toThrow()` and `toThrowError` includes a message    |                  |                     |
 | [valid-describe][]           | Enforce valid `describe()` callback                               |                  |                     |
 | [valid-expect-in-promise][]  | Enforce having return statement when testing with promises        |                  |                     |
 | [valid-expect][]             | Enforce valid `expect()` usage                                    | ![recommended][] |                     |
@@ -110,6 +112,7 @@ for more information about extending configuration files.
 [consistent-test-it]: docs/rules/consistent-test-it.md
 [expect-expect]: docs/rules/expect-expect.md
 [lowercase-name]: docs/rules/lowercase-name.md
+[no-alias-methods]: docs/rules/no-alias-methods.md
 [no-disabled-tests]: docs/rules/no-disabled-tests.md
 [no-focused-tests]: docs/rules/no-focused-tests.md
 [no-hooks]: docs/rules/no-hooks.md
@@ -125,6 +128,7 @@ for more information about extending configuration files.
 [prefer-to-be-undefined]: docs/rules/prefer-to-be-undefined.md
 [prefer-to-have-length]: docs/rules/prefer-to-have-length.md
 [prefer-inline-snapshots]: docs/rules/prefer-inline-snapshots.md
+[require-tothrow-message]: docs/rules/require-tothrow-message.md
 [valid-describe]: docs/rules/valid-describe.md
 [valid-expect-in-promise]: docs/rules/valid-expect-in-promise.md
 [valid-expect]: docs/rules/valid-expect.md

package/docs/rules/expect-expect.md

@@ -7,9 +7,7 @@ Ensure that there is at least one `expect` call made in a test.
 This rule triggers when there is no call made to `expect` in a test, to prevent
 users from forgetting to add assertions.
 
-### Default configuration
-
-The following patterns are considered warnings:
+Examples of **incorrect** code for this rule:
 
 ```js
 it('should be a test', () => {
@@ -18,7 +16,7 @@ it('should be a test', () => {
 test('should assert something', () => {});
 ```
 
-The following patterns are not warnings:
+Examples of **correct** code for this rule:
 
 ```js
 it('should be a test', () => {
@@ -28,3 +26,52 @@ it('should work with callbacks/async', () => {
   somePromise().then(res => expect(res).toBe('passed'));
 });
 ```
+
+## Options
+
+```json
+{
+  "jest/expect-expect": [
+    "error",
+    {
+      "assertFunctionNames": ["expect"]
+    }
+  ]
+}
+```
+
+### `assertFunctionNames`
+
+This array option whitelists the assertion function names to look for.
+
+Examples of **incorrect** code for the `{ "assertFunctionNames": ["expect"] }`
+option:
+
+```js
+/* eslint jest/expect-expect: ["error", { "assertFunctionNames": ["expect"] }] */
+
+import { expectSaga } from 'redux-saga-test-plan';
+import { addSaga } from '../src/sagas';
+
+test('returns sum', () =>
+  expectSaga(addSaga, 1, 1)
+    .returns(2)
+    .run();
+);
+```
+
+Examples of **correct** code for the
+`{ "assertFunctionNames": ["expect", "expectSaga"] }` option:
+
+```js
+/* eslint jest/expect-expect: ["error", { "assertFunctionNames": ["expect", "expectSaga"] }] */
+
+import { expectSaga } from 'redux-saga-test-plan';
+import { addSaga } from '../src/sagas';
+
+test('returns sum', () =>
+  expectSaga(addSaga, 1, 1)
+    .returns(2)
+    .run();
+);
+```

package/docs/rules/no-alias-methods.md

@@ -0,0 +1,46 @@
+# Don't use alias methods (no-alias-methods)
+
+Several Jest methods have alias names, such as `toThrow` having the alias of
+`toThrowError`. This rule ensures that only the canonical name as used in the
+Jest documentation is used in the code. This makes it easier to search for all
+occurrences of the method within code, and it ensures consistency among the
+method names used.
+
+## Rule details
+
+This rule triggers a warning if the alias name, rather than the canonical name,
+of a method is used.
+
+### Default configuration
+
+The following patterns are considered warnings:
+
+```js
+expect(a).toBeCalled();
+expect(a).toBeCalledTimes();
+expect(a).toBeCalledWith();
+expect(a).lastCalledWith();
+expect(a).nthCalledWith();
+expect(a).toReturn();
+expect(a).toReturnTimes();
+expect(a).toReturnWith();
+expect(a).lastReturnedWith();
+expect(a).nthReturnedWith();
+expect(a).toThrowError();
+```
+
+The following patterns are not considered warnings:
+
+```js
+expect(a).toHaveBeenCalled();
+expect(a).toHaveBeenCalledTimes();
+expect(a).toHaveBeenCalledWith();
+expect(a).toHaveBeenLastCalledWith();
+expect(a).toHaveBeenNthCalledWith();
+expect(a).toHaveReturned();
+expect(a).toHaveReturnedTimes();
+expect(a).toHaveReturnedWith();
+expect(a).toHaveLastReturnedWith();
+expect(a).toHaveNthReturnedWith();
+expect(a).toThrow();
+```

package/docs/rules/require-tothrow-message.md

@@ -0,0 +1,29 @@
+# Require a message for `toThrow()` (require-tothrow-message)
+
+`toThrow()`, and its alias `toThrowError()`, are used to check if an error is
+thrown by a function call, such as in `expect(() => a()).toThrow()`. However, if
+no message is defined, then the test will pass for any thrown error. Requiring a
+message ensures that the intended error is thrown.
+
+## Rule details
+
+This rule triggers a warning if `toThrow()` or `toThrowError()` is used without
+an error message.
+
+### Default configuration
+
+The following patterns are considered warnings:
+
+```js
+expect(() => a()).toThrow();
+
+expect(() => a()).toThrowError();
+```
+
+The following patterns are not considered warnings:
+
+```js
+expect(() => a()).toThrow('a');
+
+expect(() => a()).toThrowError('a');
+```

package/index.js

@@ -21,6 +21,8 @@ const preferExpectAssertions = require('./rules/prefer-expect-assertions');
 const validExpectInPromise = require('./rules/valid-expect-in-promise');
 const preferInlineSnapshots = require('./rules/prefer-inline-snapshots');
 const preferStrictEqual = require('./rules/prefer-strict-equal');
+const requireTothrowMessage = require('./rules/require-tothrow-message');
+const noAliasMethods = require('./rules/no-alias-methods');
 
 const snapshotProcessor = require('./processors/snapshot-processor');
 
@@ -89,5 +91,7 @@ module.exports = {
     'valid-expect-in-promise': validExpectInPromise,
     'prefer-inline-snapshots': preferInlineSnapshots,
     'prefer-strict-equal': preferStrictEqual,
+    'require-tothrow-message': requireTothrowMessage,
+    'no-alias-methods': noAliasMethods,
   },
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "eslint-plugin-jest",
-  "version": "21.21.0",
+  "version": "21.24.0",
   "description": "Eslint rules for Jest",
   "repository": "jest-community/eslint-plugin-jest",
   "license": "MIT",
@@ -46,9 +46,7 @@
     "jest-runner-eslint": "^0.4.0",
     "lint-staged": "^7.0.0",
     "prettier": "^1.10.2",
-    "prettylint": "^1.0.0",
-    "semantic-release": "^15.0.2",
-    "travis-deploy-once": "^4.3.1"
+    "prettylint": "^1.0.0"
   },
   "prettier": {
     "proseWrap": "always",

package/rules/__tests__/expect-expect.test.js

@@ -14,6 +14,15 @@ ruleTester.run('expect-expect', rule, {
     'it("should pass", () => expect(true).toBeDefined())',
     'test("should pass", () => expect(true).toBeDefined())',
     'it("should pass", () => somePromise().then(() => expect(true).toBeDefined()))',
+    {
+      code:
+        'test("should pass", () => { expect(true).toBeDefined(); foo(true).toBe(true); })',
+      options: [{ assertFunctionNames: ['expect', 'foo'] }],
+    },
+    {
+      code: 'it("should return undefined",() => expectSaga(mySaga).returns());',
+      options: [{ assertFunctionNames: ['expectSaga'] }],
+    },
   ],
 
   invalid: [
@@ -44,5 +53,25 @@ ruleTester.run('expect-expect', rule, {
         },
       ],
     },
+    {
+      code: 'test("should fail", () => { foo(true).toBe(true); })',
+      options: [{ assertFunctionNames: ['expect'] }],
+      errors: [
+        {
+          message: 'Test has no assertions',
+          type: 'CallExpression',
+        },
+      ],
+    },
+    {
+      code: 'it("should also fail",() => expectSaga(mySaga).returns());',
+      options: [{ assertFunctionNames: ['expect'] }],
+      errors: [
+        {
+          message: 'Test has no assertions',
+          type: 'CallExpression',
+        },
+      ],
+    },
   ],
 });

package/rules/__tests__/no-alias-methods.test.js

@@ -0,0 +1,157 @@
+'use strict';
+
+const RuleTester = require('eslint').RuleTester;
+const rule = require('../no-alias-methods');
+
+const ruleTester = new RuleTester();
+
+ruleTester.run('no-alias-methods', rule, {
+  valid: [
+    'expect(a).toHaveBeenCalled()',
+    'expect(a).toHaveBeenCalledTimes()',
+    'expect(a).toHaveBeenCalledWith()',
+    'expect(a).toHaveBeenLastCalledWith()',
+    'expect(a).toHaveBeenNthCalledWith()',
+    'expect(a).toHaveReturned()',
+    'expect(a).toHaveReturnedTimes()',
+    'expect(a).toHaveReturnedWith()',
+    'expect(a).toHaveLastReturnedWith()',
+    'expect(a).toHaveNthReturnedWith()',
+    'expect(a).toThrow()',
+  ],
+
+  invalid: [
+    {
+      code: 'expect(a).toBeCalled()',
+      errors: [
+        {
+          message:
+            'Replace toBeCalled() with its canonical name of toHaveBeenCalled()',
+          column: 11,
+          line: 1,
+        },
+      ],
+      output: 'expect(a).toHaveBeenCalled()',
+    },
+    {
+      code: 'expect(a).toBeCalledTimes()',
+      errors: [
+        {
+          message:
+            'Replace toBeCalledTimes() with its canonical name of toHaveBeenCalledTimes()',
+          column: 11,
+          line: 1,
+        },
+      ],
+      output: 'expect(a).toHaveBeenCalledTimes()',
+    },
+    {
+      code: 'expect(a).toBeCalledWith()',
+      errors: [
+        {
+          message:
+            'Replace toBeCalledWith() with its canonical name of toHaveBeenCalledWith()',
+          column: 11,
+          line: 1,
+        },
+      ],
+      output: 'expect(a).toHaveBeenCalledWith()',
+    },
+    {
+      code: 'expect(a).lastCalledWith()',
+      errors: [
+        {
+          message:
+            'Replace lastCalledWith() with its canonical name of toHaveBeenLastCalledWith()',
+          column: 11,
+          line: 1,
+        },
+      ],
+      output: 'expect(a).toHaveBeenLastCalledWith()',
+    },
+    {
+      code: 'expect(a).nthCalledWith()',
+      errors: [
+        {
+          message:
+            'Replace nthCalledWith() with its canonical name of toHaveBeenNthCalledWith()',
+          column: 11,
+          line: 1,
+        },
+      ],
+      output: 'expect(a).toHaveBeenNthCalledWith()',
+    },
+    {
+      code: 'expect(a).toReturn()',
+      errors: [
+        {
+          message:
+            'Replace toReturn() with its canonical name of toHaveReturned()',
+          column: 11,
+          line: 1,
+        },
+      ],
+      output: 'expect(a).toHaveReturned()',
+    },
+    {
+      code: 'expect(a).toReturnTimes()',
+      errors: [
+        {
+          message:
+            'Replace toReturnTimes() with its canonical name of toHaveReturnedTimes()',
+          column: 11,
+          line: 1,
+        },
+      ],
+      output: 'expect(a).toHaveReturnedTimes()',
+    },
+    {
+      code: 'expect(a).toReturnWith()',
+      errors: [
+        {
+          message:
+            'Replace toReturnWith() with its canonical name of toHaveReturnedWith()',
+          column: 11,
+          line: 1,
+        },
+      ],
+      output: 'expect(a).toHaveReturnedWith()',
+    },
+    {
+      code: 'expect(a).lastReturnedWith()',
+      errors: [
+        {
+          message:
+            'Replace lastReturnedWith() with its canonical name of toHaveLastReturnedWith()',
+          column: 11,
+          line: 1,
+        },
+      ],
+      output: 'expect(a).toHaveLastReturnedWith()',
+    },
+    {
+      code: 'expect(a).nthReturnedWith()',
+      errors: [
+        {
+          message:
+            'Replace nthReturnedWith() with its canonical name of toHaveNthReturnedWith()',
+          column: 11,
+          line: 1,
+        },
+      ],
+      output: 'expect(a).toHaveNthReturnedWith()',
+    },
+    {
+      code: 'expect(a).toThrowError()',
+      errors: [
+        {
+          message:
+            'Replace toThrowError() with its canonical name of toThrow()',
+          column: 11,
+          line: 1,
+        },
+      ],
+      output: 'expect(a).toThrow()',
+    },
+  ],
+});

package/rules/__tests__/no-disabled-tests.test.js

@@ -3,7 +3,11 @@
 const RuleTester = require('eslint').RuleTester;
 const rule = require('../no-disabled-tests');
 
-const ruleTester = new RuleTester();
+const ruleTester = new RuleTester({
+  parserOptions: {
+    sourceType: 'module',
+  },
+});
 
 ruleTester.run('no-disabled-tests', rule, {
   valid: [
@@ -17,6 +21,35 @@ ruleTester.run('no-disabled-tests', rule, {
     'var calledSkip = it.skip; calledSkip.call(it)',
     '({ f: function () {} }).f()',
     '(a || b).f()',
+    [
+      'import { pending } from "actions"',
+      '',
+      'test("foo", () => {',
+      '  expect(pending()).toEqual({})',
+      '})',
+    ].join('\n'),
+    [
+      'const { pending } = require("actions")',
+      '',
+      'test("foo", () => {',
+      '  expect(pending()).toEqual({})',
+      '})',
+    ].join('\n'),
+    [
+      'test("foo", () => {',
+      '  const pending = getPending()',
+      '  expect(pending()).toEqual({})',
+      '})',
+    ].join('\n'),
+    [
+      'test("foo", () => {',
+      '  expect(pending()).toEqual({})',
+      '})',
+      '',
+      'function pending() {',
+      '  return {}',
+      '}',
+    ].join('\n'),
   ],
 
   invalid: [

package/rules/__tests__/prefer-strict-equal.test.js

@@ -6,7 +6,10 @@ const rule = require('../prefer-strict-equal');
 const ruleTester = new RuleTester();
 
 ruleTester.run('prefer-strict-equal', rule, {
-  valid: ['expect(something).toStrictEqual(somethingElse);'],
+  valid: [
+    'expect(something).toStrictEqual(somethingElse);',
+    "a().toEqual('b')",
+  ],
   invalid: [
     {
       code: 'expect(something).toEqual(somethingElse);',

package/rules/__tests__/require-tothrow-message.test.js

@@ -0,0 +1,52 @@
+'use strict';
+
+const RuleTester = require('eslint').RuleTester;
+const rule = require('../require-tothrow-message');
+
+const ruleTester = new RuleTester({
+  parserOptions: {
+    ecmaVersion: 6,
+  },
+});
+
+ruleTester.run('require-tothrow-message', rule, {
+  valid: [
+    // String
+    "expect(() => { throw new Error('a'); }).toThrow('a');",
+    "expect(() => { throw new Error('a'); }).toThrowError('a');",
+
+    // Template literal
+    "const a = 'a'; expect(() => { throw new Error('a'); }).toThrow(`${a}`);",
+
+    // Regex
+    "expect(() => { throw new Error('a'); }).toThrow(/^a$/);",
+
+    // Function
+    "expect(() => { throw new Error('a'); })" +
+      ".toThrow((() => { return 'a'; })());",
+
+    // Allow no message for `not`.
+    "expect(() => { throw new Error('a'); }).not.toThrow();",
+  ],
+
+  invalid: [
+    // Empty toThrow
+    {
+      code: "expect(() => { throw new Error('a'); }).toThrow();",
+      errors: [
+        { message: 'Add an error message to toThrow()', column: 41, line: 1 },
+      ],
+    },
+    // Empty toThrowError
+    {
+      code: "expect(() => { throw new Error('a'); }).toThrowError();",
+      errors: [
+        {
+          message: 'Add an error message to toThrowError()',
+          column: 41,
+          line: 1,
+        },
+      ],
+    },
+  ],
+});

package/rules/expect-expect.js

@@ -12,10 +12,26 @@ module.exports = {
     docs: {
       url: getDocsUrl(__filename),
     },
+    schema: [
+      {
+        type: 'object',
+        properties: {
+          assertFunctionNames: {
+            type: 'array',
+            items: [{ type: 'string' }],
+          },
+        },
+        additionalProperties: false,
+      },
+    ],
   },
   create(context) {
     // variables should be defined here
     const unchecked = [];
+    const assertFunctionNames =
+      context.options[0] && context.options[0].assertFunctionNames
+        ? context.options[0].assertFunctionNames
+        : ['expect'];
 
     //----------------------------------------------------------------------
     // Helpers
@@ -23,8 +39,8 @@ module.exports = {
     const isExpectCall = node =>
       // if we're not calling a function, ignore
       node.type === 'CallExpression' &&
-      // if we're not calling expect, ignore
-      node.callee.name === 'expect';
+      // if we're not calling allowed assertion
+      assertFunctionNames.some(name => name === node.callee.name);
     //----------------------------------------------------------------------
     // Public
     //----------------------------------------------------------------------

package/rules/no-alias-methods.js

@@ -0,0 +1,57 @@
+'use strict';
+
+const expectCase = require('./util').expectCase;
+const getDocsUrl = require('./util').getDocsUrl;
+const method = require('./util').method;
+
+module.exports = {
+  meta: {
+    docs: {
+      url: getDocsUrl(__filename),
+    },
+    fixable: 'code',
+  },
+  create(context) {
+    // The Jest methods which have aliases. The canonical name is the first
+    // index of each item.
+    const methodNames = [
+      ['toHaveBeenCalled', 'toBeCalled'],
+      ['toHaveBeenCalledTimes', 'toBeCalledTimes'],
+      ['toHaveBeenCalledWith', 'toBeCalledWith'],
+      ['toHaveBeenLastCalledWith', 'lastCalledWith'],
+      ['toHaveBeenNthCalledWith', 'nthCalledWith'],
+      ['toHaveReturned', 'toReturn'],
+      ['toHaveReturnedTimes', 'toReturnTimes'],
+      ['toHaveReturnedWith', 'toReturnWith'],
+      ['toHaveLastReturnedWith', 'lastReturnedWith'],
+      ['toHaveNthReturnedWith', 'nthReturnedWith'],
+      ['toThrow', 'toThrowError'],
+    ];
+
+    return {
+      CallExpression(node) {
+        if (!expectCase(node)) {
+          return;
+        }
+
+        // Check if the method used matches any of ours.
+        const propertyName = method(node) && method(node).name;
+        const methodItem = methodNames.find(item => item[1] === propertyName);
+
+        if (methodItem) {
+          context.report({
+            message: `Replace {{ replace }}() with its canonical name of {{ canonical }}()`,
+            data: {
+              replace: methodItem[1],
+              canonical: methodItem[0],
+            },
+            node: method(node),
+            fix(fixer) {
+              return [fixer.replaceText(method(node), methodItem[0])];
+            },
+          });
+        }
+      },
+    };
+  },
+};

package/rules/no-disabled-tests.js

@@ -19,6 +19,33 @@ function getName(node) {
   return null;
 }
 
+function collectReferences(scope) {
+  const locals = new Set();
+  const unresolved = new Set();
+
+  let currentScope = scope;
+
+  while (currentScope !== null) {
+    for (const ref of currentScope.variables) {
+      const isReferenceDefined = ref.defs.some(def => {
+        return def.type !== 'ImplicitGlobalVariable';
+      });
+
+      if (isReferenceDefined) {
+        locals.add(ref.name);
+      }
+    }
+
+    for (const ref of currentScope.through) {
+      unresolved.add(ref.identifier.name);
+    }
+
+    currentScope = currentScope.upper;
+  }
+
+  return { locals, unresolved };
+}
+
 module.exports = {
   meta: {
     docs: {
@@ -58,7 +85,19 @@ module.exports = {
             context.report({ message: 'Skipped test', node });
             break;
 
-          case 'pending':
+          case 'pending': {
+            const references = collectReferences(context.getScope());
+
+            if (
+              // `pending` was found as a local variable or function declaration.
+              references.locals.has('pending') ||
+              // `pending` was not found as an unresolved reference,
+              // meaning it is likely not an implicit global reference.
+              !references.unresolved.has('pending')
+            ) {
+              break;
+            }
+
             if (testDepth > 0) {
               context.report({
                 message: 'Call to pending() within test',
@@ -76,6 +115,7 @@ module.exports = {
               });
             }
             break;
+          }
 
           case 'xdescribe':
             context.report({ message: 'Disabled test suite', node });

package/rules/prefer-strict-equal.js

@@ -1,6 +1,8 @@
 'use strict';
 
+const expectCase = require('./util').expectCase;
 const getDocsUrl = require('./util').getDocsUrl;
+const method = require('./util').method;
 
 module.exports = {
   meta: {
@@ -12,14 +14,19 @@ module.exports = {
   create(context) {
     return {
       CallExpression(node) {
-        const propertyName = node.callee.property && node.callee.property.name;
+        if (!expectCase(node)) {
+          return;
+        }
+
+        const propertyName = method(node) && method(node).name;
+
         if (propertyName === 'toEqual') {
           context.report({
             fix(fixer) {
-              return [fixer.replaceText(node.callee.property, 'toStrictEqual')];
+              return [fixer.replaceText(method(node), 'toStrictEqual')];
             },
             message: 'Use toStrictEqual() instead',
-            node: node.callee.property,
+            node: method(node),
           });
         }
       },

package/rules/require-tothrow-message.js

@@ -0,0 +1,39 @@
+'use strict';
+
+const argument = require('./util').argument;
+const expectCase = require('./util').expectCase;
+const getDocsUrl = require('./util').getDocsUrl;
+const method = require('./util').method;
+
+module.exports = {
+  meta: {
+    docs: {
+      url: getDocsUrl(__filename),
+    },
+  },
+  create(context) {
+    return {
+      CallExpression(node) {
+        if (!expectCase(node)) {
+          return;
+        }
+
+        const propertyName = method(node) && method(node).name;
+
+        // Look for `toThrow` calls with no arguments.
+        if (
+          ['toThrow', 'toThrowError'].indexOf(propertyName) > -1 &&
+          !argument(node)
+        ) {
+          context.report({
+            message: `Add an error message to {{ propertyName }}()`,
+            data: {
+              propertyName,
+            },
+            node: method(node),
+          });
+        }
+      },
+    };
+  },
+};