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

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)