feat: create prefer-snapshot-hint rule (#1012)

* feat: create `prefer-snapshot-hint` rule

* feat(prefer-snapshot-hint): check nested scope for multiple snapshot matchers

* fix: update import

* test: update number

Author: G-Rath

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][] |

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

src/__tests__/__snapshots__/rules.test.ts.snap

@@ -41,6 +41,7 @@ Object {
       "jest/prefer-expect-resolves": "error",
       "jest/prefer-hooks-on-top": "error",
       "jest/prefer-lowercase-title": "error",
+      "jest/prefer-snapshot-hint": "error",
       "jest/prefer-spy-on": "error",
       "jest/prefer-strict-equal": "error",
       "jest/prefer-to-be": "error",

src/__tests__/rules.test.ts

@@ -2,7 +2,7 @@ import { existsSync } from 'fs';
 import { resolve } from 'path';
 import plugin from '../';
 
-const numberOfRules = 46;
+const numberOfRules = 47;
 const ruleNames = Object.keys(plugin.rules);
 const deprecatedRules = Object.entries(plugin.rules)
   .filter(([, rule]) => rule.meta.deprecated)

src/rules/__tests__/prefer-snapshot-hint.test.ts

@@ -0,0 +1,103 @@
+import {
+  ParsedExpectMatcher,
+  createRule,
+  isExpectCall,
+  parseExpectCall,
+} from './utils';
+
+const snapshotMatchers = ['toMatchSnapshot', 'toThrowErrorMatchingSnapshot'];
+
+const isSnapshotMatcher = (matcher: ParsedExpectMatcher) => {
+  return snapshotMatchers.includes(matcher.name);
+};
+
+const isSnapshotMatcherWithoutHint = (matcher: ParsedExpectMatcher) => {
+  const expectedNumberOfArgumentsWithHint =
+    1 + Number(matcher.name === 'toMatchSnapshot');
+
+  return matcher.arguments?.length !== expectedNumberOfArgumentsWithHint;
+};
+
+const messages = {
+  missingHint: 'You should provide a hint for this snapshot',
+};
+
+export default createRule<[('always' | 'multi')?], keyof typeof messages>({
+  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: ParsedExpectMatcher[] = [];
+    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 (!isExpectCall(node)) {
+          return;
+        }
+
+        const { matcher } = parseExpectCall(node);
+
+        if (!matcher || !isSnapshotMatcher(matcher)) {
+          return;
+        }
+
+        snapshotMatchers.push(matcher);
+      },
+    };
+  },
+});