eslint-plugin-jest 26.1.0-next.2 → 26.1.2

package/README.md

@@ -183,6 +183,7 @@ installations requiring long-term consistency.
 | [prefer-expect-resolves](docs/rules/prefer-expect-resolves.md)               | Prefer `await expect(...).resolves` over `expect(await ...)` syntax |                  | ![fixable][] |
 | [prefer-hooks-on-top](docs/rules/prefer-hooks-on-top.md)                     | Suggest having hooks before any test cases                          |                  |              |
 | [prefer-lowercase-title](docs/rules/prefer-lowercase-title.md)               | Enforce lowercase test names                                        |                  | ![fixable][] |
+| [prefer-snapshot-hint](docs/rules/prefer-snapshot-hint.md)                   | Prefer including a hint with external snapshots                     |                  |              |
 | [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                       | ![style][]       | ![fixable][] |

package/docs/rules/prefer-expect-assertions.md

@@ -118,7 +118,7 @@ a native loop.
   "rules": {
     "jest/prefer-expect-assertions": [
       "warn",
-      { "onlyFunctionsWithAsyncKeyword": true }
+      { "onlyFunctionsWithExpectInLoop": true }
     ]
   }
 }

package/docs/rules/prefer-snapshot-hint.md

@@ -0,0 +1,188 @@
+# Prefer including a hint with external snapshots (`prefer-snapshot-hint`)
+
+When working with external snapshot matchers it's considered best practice to
+provide a hint (as the last argument to the matcher) describing the expected
+snapshot content that will be included in the snapshots name by Jest.
+
+This makes it easier for reviewers to verify the snapshots during review, and
+for anyone to know whether an outdated snapshot is the correct behavior before
+updating.
+
+## Rule details
+
+This rule looks for any use of an external snapshot matcher (e.g.
+`toMatchSnapshot` and `toThrowErrorMatchingSnapshot`) and checks if they include
+a snapshot hint.
+
+## Options
+
+### `'always'`
+
+Require a hint to _always_ be provided when using external snapshot matchers.
+
+Examples of **incorrect** code for the `'always'` option:
+
+```js
+const snapshotOutput = ({ stdout, stderr }) => {
+  expect(stdout).toMatchSnapshot();
+  expect(stderr).toMatchSnapshot();
+};
+
+describe('cli', () => {
+  describe('--version flag', () => {
+    it('prints the version', async () => {
+      snapshotOutput(await runCli(['--version']));
+    });
+  });
+
+  describe('--config flag', () => {
+    it('reads the config', async () => {
+      const { stdout, parsedConfig } = await runCli([
+        '--config',
+        'jest.config.js',
+      ]);
+
+      expect(stdout).toMatchSnapshot();
+      expect(parsedConfig).toMatchSnapshot();
+    });
+
+    it('prints nothing to stderr', async () => {
+      const { stderr } = await runCli(['--config', 'jest.config.js']);
+
+      expect(stderr).toMatchSnapshot();
+    });
+
+    describe('when the file does not exist', () => {
+      it('throws an error', async () => {
+        await expect(
+          runCli(['--config', 'does-not-exist.js']),
+        ).rejects.toThrowErrorMatchingSnapshot();
+      });
+    });
+  });
+});
+```
+
+Examples of **correct** code for the `'always'` option:
+
+```js
+const snapshotOutput = ({ stdout, stderr }, hints) => {
+  expect(stdout).toMatchSnapshot({}, `stdout: ${hints.stdout}`);
+  expect(stderr).toMatchSnapshot({}, `stderr: ${hints.stderr}`);
+};
+
+describe('cli', () => {
+  describe('--version flag', () => {
+    it('prints the version', async () => {
+      snapshotOutput(await runCli(['--version']), {
+        stdout: 'version string',
+        stderr: 'empty',
+      });
+    });
+  });
+
+  describe('--config flag', () => {
+    it('reads the config', async () => {
+      const { stdout } = await runCli(['--config', 'jest.config.js']);
+
+      expect(stdout).toMatchSnapshot({}, 'stdout: config settings');
+    });
+
+    it('prints nothing to stderr', async () => {
+      const { stderr } = await runCli(['--config', 'jest.config.js']);
+
+      expect(stderr).toMatchInlineSnapshot();
+    });
+
+    describe('when the file does not exist', () => {
+      it('throws an error', async () => {
+        await expect(
+          runCli(['--config', 'does-not-exist.js']),
+        ).rejects.toThrowErrorMatchingSnapshot('stderr: config error');
+      });
+    });
+  });
+});
+```
+
+### `'multi'` (default)
+
+Require a hint to be provided when there are multiple external snapshot matchers
+within the scope (meaning it includes nested calls).
+
+Examples of **incorrect** code for the `'multi'` option:
+
+```js
+const snapshotOutput = ({ stdout, stderr }) => {
+  expect(stdout).toMatchSnapshot();
+  expect(stderr).toMatchSnapshot();
+};
+
+describe('cli', () => {
+  describe('--version flag', () => {
+    it('prints the version', async () => {
+      snapshotOutput(await runCli(['--version']));
+    });
+  });
+
+  describe('--config flag', () => {
+    it('reads the config', async () => {
+      const { stdout, parsedConfig } = await runCli([
+        '--config',
+        'jest.config.js',
+      ]);
+
+      expect(stdout).toMatchSnapshot();
+      expect(parsedConfig).toMatchSnapshot();
+    });
+
+    it('prints nothing to stderr', async () => {
+      const { stderr } = await runCli(['--config', 'jest.config.js']);
+
+      expect(stderr).toMatchSnapshot();
+    });
+  });
+});
+```
+
+Examples of **correct** code for the `'multi'` option:
+
+```js
+const snapshotOutput = ({ stdout, stderr }, hints) => {
+  expect(stdout).toMatchSnapshot({}, `stdout: ${hints.stdout}`);
+  expect(stderr).toMatchSnapshot({}, `stderr: ${hints.stderr}`);
+};
+
+describe('cli', () => {
+  describe('--version flag', () => {
+    it('prints the version', async () => {
+      snapshotOutput(await runCli(['--version']), {
+        stdout: 'version string',
+        stderr: 'empty',
+      });
+    });
+  });
+
+  describe('--config flag', () => {
+    it('reads the config', async () => {
+      const { stdout } = await runCli(['--config', 'jest.config.js']);
+
+      expect(stdout).toMatchSnapshot();
+    });
+
+    it('prints nothing to stderr', async () => {
+      const { stderr } = await runCli(['--config', 'jest.config.js']);
+
+      expect(stderr).toMatchInlineSnapshot();
+    });
+
+    describe('when the file does not exist', () => {
+      it('throws an error', async () => {
+        await expect(
+          runCli(['--config', 'does-not-exist.js']),
+        ).rejects.toThrowErrorMatchingSnapshot();
+      });
+    });
+  });
+});
+```

package/lib/rules/prefer-snapshot-hint.js

@@ -0,0 +1,128 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.default = void 0;
+
+var _utils = require("./utils");
+
+const snapshotMatchers = ['toMatchSnapshot', 'toThrowErrorMatchingSnapshot'];
+
+const isSnapshotMatcher = matcher => {
+  return snapshotMatchers.includes(matcher.name);
+};
+
+const isSnapshotMatcherWithoutHint = matcher => {
+  if (!matcher.arguments || matcher.arguments.length === 0) {
+    return true;
+  } // this matcher only supports one argument which is the hint
+
+
+  if (matcher.name !== 'toMatchSnapshot') {
+    return matcher.arguments.length !== 1;
+  } // if we're being passed two arguments,
+  // the second one should be the hint
+
+
+  if (matcher.arguments.length === 2) {
+    return false;
+  }
+
+  const [arg] = matcher.arguments; // the first argument to `toMatchSnapshot` can be _either_ a snapshot hint or
+  // an object with asymmetric matchers, so we can't just assume that the first
+  // argument is a hint when it's by itself.
+
+  return !(0, _utils.isStringNode)(arg);
+};
+
+const messages = {
+  missingHint: 'You should provide a hint for this snapshot'
+};
+
+var _default = (0, _utils.createRule)({
+  name: __filename,
+  meta: {
+    docs: {
+      category: 'Best Practices',
+      description: 'Prefer including a hint with external snapshots',
+      recommended: false
+    },
+    messages,
+    type: 'suggestion',
+    schema: [{
+      type: 'string',
+      enum: ['always', 'multi']
+    }]
+  },
+  defaultOptions: ['multi'],
+
+  create(context, [mode]) {
+    const snapshotMatchers = [];
+    let expressionDepth = 0;
+
+    const reportSnapshotMatchersWithoutHints = () => {
+      for (const snapshotMatcher of snapshotMatchers) {
+        if (isSnapshotMatcherWithoutHint(snapshotMatcher)) {
+          context.report({
+            messageId: 'missingHint',
+            node: snapshotMatcher.node.property
+          });
+        }
+      }
+    };
+
+    const enterExpression = () => {
+      expressionDepth++;
+    };
+
+    const exitExpression = () => {
+      expressionDepth--;
+
+      if (mode === 'always') {
+        reportSnapshotMatchersWithoutHints();
+        snapshotMatchers.length = 0;
+      }
+
+      if (mode === 'multi' && expressionDepth === 0) {
+        if (snapshotMatchers.length > 1) {
+          reportSnapshotMatchersWithoutHints();
+        }
+
+        snapshotMatchers.length = 0;
+      }
+    };
+
+    return {
+      'Program:exit'() {
+        enterExpression();
+        exitExpression();
+      },
+
+      FunctionExpression: enterExpression,
+      'FunctionExpression:exit': exitExpression,
+      ArrowFunctionExpression: enterExpression,
+      'ArrowFunctionExpression:exit': exitExpression,
+
+      CallExpression(node) {
+        if (!(0, _utils.isExpectCall)(node)) {
+          return;
+        }
+
+        const {
+          matcher
+        } = (0, _utils.parseExpectCall)(node);
+
+        if (!matcher || !isSnapshotMatcher(matcher)) {
+          return;
+        }
+
+        snapshotMatchers.push(matcher);
+      }
+
+    };
+  }
+
+});
+
+exports.default = _default;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "eslint-plugin-jest",
-  "version": "26.1.0-next.2",
+  "version": "26.1.2",
   "description": "ESLint rules for Jest",
   "keywords": [
     "eslint",
@@ -118,7 +118,7 @@
     "jest": "^27.0.0",
     "jest-runner-eslint": "^1.0.0",
     "lint-staged": "^12.0.0",
-    "pinst": "^2.0.0",
+    "pinst": "^3.0.0",
     "prettier": "^2.0.5",
     "rimraf": "^3.0.0",
     "semantic-release": "^19.0.0",
@@ -163,5 +163,5 @@
     "@typescript-eslint/experimental-utils": "^5.0.0",
     "fsevents/node-gyp": "^7.0.0"
   },
-  "packageManager": "yarn@3.1.1"
+  "packageManager": "yarn@3.2.0"
 }