jest-community · G-Rath · Jul 26, 2020 · Jul 12, 2020 · Jul 12, 2020 · Jul 12, 2020
diff --git a/.github/workflows/lint.yml b/.github/workflows/lint.yml
@@ -13,6 +13,24 @@ jobs:
           configFile: './package.json'
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+  docs:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v2
+        with:
+          fetch-depth: 0
+      - uses: actions/[email protected]
+        with:
+          node-version: 12.x
+      - name: install
+        run: yarn
+      - name: regenerate docs
+        run: yarn tools:regenerate-docs
+      - name: report regenerated docs
+        run: |
+          git diff --name-only \
+            | xargs -I '{}' bash -c \
+              'echo "::error file={}::This needs to be regenerated by running \`tools:regenerate-docs\`" && false'
   danger:
     runs-on: ubuntu-latest
     steps:

diff --git a/README.md b/README.md
@@ -46,7 +46,8 @@ Then configure the rules you want to use under the rules section.
 }
 ```
 
-You can also whitelist the environment variables provided by Jest by doing:
+You can also tell ESLint about the environment variables provided by Jest by
+doing:
 
 ```json
 {
@@ -138,32 +139,32 @@ installations requiring long-term consistency.
 | [no-deprecated-functions](docs/rules/no-deprecated-functions.md)       | Disallow use of deprecated functions                            |                  | ![fixable][] |
 | [no-disabled-tests](docs/rules/no-disabled-tests.md)                   | Disallow disabled tests                                         | ![recommended][] |              |
 | [no-duplicate-hooks](docs/rules/no-duplicate-hooks.md)                 | Disallow duplicate setup and teardown hooks                     |                  |              |
-| [no-export](docs/rules/no-export.md)                                   | Prevent exporting from test files                               | ![recommended][] |              |
+| [no-export](docs/rules/no-export.md)                                   | Disallow using `exports` in files containing tests              | ![recommended][] |              |
 | [no-focused-tests](docs/rules/no-focused-tests.md)                     | Disallow focused tests                                          | ![recommended][] | ![fixable][] |
 | [no-hooks](docs/rules/no-hooks.md)                                     | Disallow setup and teardown hooks                               |                  |              |
 | [no-identical-title](docs/rules/no-identical-title.md)                 | Disallow identical titles                                       | ![recommended][] |              |
 | [no-if](docs/rules/no-if.md)                                           | Disallow conditional logic                                      |                  |              |
 | [no-jasmine-globals](docs/rules/no-jasmine-globals.md)                 | Disallow Jasmine globals                                        | ![recommended][] | ![fixable][] |
 | [no-jest-import](docs/rules/no-jest-import.md)                         | Disallow importing Jest                                         | ![recommended][] |              |
 | [no-large-snapshots](docs/rules/no-large-snapshots.md)                 | disallow large snapshots                                        |                  |              |
-| [no-mocks-import](docs/rules/no-mocks-import.md)                       | Disallow manually importing from **mocks**                      | ![recommended][] |              |
+| [no-mocks-import](docs/rules/no-mocks-import.md)                       | Disallow manually importing from `__mocks__`                    | ![recommended][] |              |
 | [no-restricted-matchers](docs/rules/no-restricted-matchers.md)         | Disallow specific matchers & modifiers                          |                  |              |
-| [no-standalone-expect](docs/rules/no-standalone-expect.md)             | Prevents expects that are outside of an it or test block.       | ![recommended][] |              |
+| [no-standalone-expect](docs/rules/no-standalone-expect.md)             | Disallow using `expect` outside of `it` or `test` blocks        | ![recommended][] |              |
 | [no-test-callback](docs/rules/no-test-callback.md)                     | Avoid using a callback in asynchronous tests                    | ![recommended][] | ![suggest][] |
 | [no-test-prefixes](docs/rules/no-test-prefixes.md)                     | Use `.only` and `.skip` over `f` and `x`                        | ![recommended][] | ![fixable][] |
 | [no-test-return-statement](docs/rules/no-test-return-statement.md)     | Disallow explicitly returning from tests                        |                  |              |
-| [prefer-called-with](docs/rules/prefer-called-with.md)                 | Suggest using `toBeCalledWith()` OR `toHaveBeenCalledWith()`    |                  |              |
+| [prefer-called-with](docs/rules/prefer-called-with.md)                 | Suggest using `toBeCalledWith()` or `toHaveBeenCalledWith()`    |                  |              |
 | [prefer-expect-assertions](docs/rules/prefer-expect-assertions.md)     | Suggest using `expect.assertions()` OR `expect.hasAssertions()` |                  | ![suggest][] |
-| [prefer-hooks-on-top](docs/rules/prefer-hooks-on-top.md)               | Suggest to have all hooks at top level                          |                  |              |
+| [prefer-hooks-on-top](docs/rules/prefer-hooks-on-top.md)               | Suggest having hooks before any test cases                      |                  |              |
 | [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-strict-equal](docs/rules/prefer-strict-equal.md)               | Suggest using `toStrictEqual()`                                 |                  | ![suggest][] |
 | [prefer-to-be-null](docs/rules/prefer-to-be-null.md)                   | Suggest using `toBeNull()`                                      | ![style][]       | ![fixable][] |
 | [prefer-to-be-undefined](docs/rules/prefer-to-be-undefined.md)         | Suggest using `toBeUndefined()`                                 | ![style][]       | ![fixable][] |
 | [prefer-to-contain](docs/rules/prefer-to-contain.md)                   | Suggest using `toContain()`                                     | ![style][]       | ![fixable][] |
 | [prefer-to-have-length](docs/rules/prefer-to-have-length.md)           | Suggest using `toHaveLength()`                                  | ![style][]       | ![fixable][] |
 | [prefer-todo](docs/rules/prefer-todo.md)                               | Suggest using `test.todo`                                       |                  | ![fixable][] |
 | [require-to-throw-message](docs/rules/require-to-throw-message.md)     | Require a message for `toThrow()`                               |                  |              |
-| [require-top-level-describe](docs/rules/require-top-level-describe.md) | Prevents test cases and hooks to be outside of a describe block |                  |              |
+| [require-top-level-describe](docs/rules/require-top-level-describe.md) | Require test cases and hooks to be inside a `describe` block    |                  |              |
 | [valid-describe](docs/rules/valid-describe.md)                         | Enforce valid `describe()` callback                             | ![recommended][] |              |
 | [valid-expect](docs/rules/valid-expect.md)                             | Enforce valid `expect()` usage                                  | ![recommended][] |              |
 | [valid-expect-in-promise](docs/rules/valid-expect-in-promise.md)       | Enforce having return statement when testing with promises      | ![recommended][] |              |

diff --git a/docs/rules/consistent-test-it.md b/docs/rules/consistent-test-it.md
@@ -12,18 +12,18 @@ This rule gives you control over the usage of these keywords in your codebase.
 
 This rule can be configured as follows
 
-```js
+```json5
 {
-    type: 'object',
-    properties: {
-        fn: {
-            enum: ['it', 'test'],
-        },
-        withinDescribe: {
-            enum: ['it', 'test'],
-        },
+  type: 'object',
+  properties: {
+    fn: {
+      enum: ['it', 'test'],
+    },
+    withinDescribe: {
+      enum: ['it', 'test'],
     },
-    additionalProperties: false,
+  },
+  additionalProperties: false,
 }
 ```
 
@@ -33,7 +33,7 @@ Decides whether to use `test` or `it`.
 
 #### withinDescribe
 
-Decides whether to use `test` or `it` within a describe scope.
+Decides whether to use `test` or `it` within a `describe` scope.
 
 ```js
 /*eslint jest/consistent-test-it: ["error", {"fn": "test"}]*/
@@ -71,8 +71,8 @@ describe('foo', function() {
 
 ### Default configuration
 
-The default configuration forces top level test to use `test` and all tests
-nested within describe to use `it`.
+The default configuration forces all top-level tests to use `test` and all tests
+nested within `describe` to use `it`.
 
 ```js
 /*eslint jest/consistent-test-it: ["error"]*/

diff --git a/docs/rules/expect-expect.md b/docs/rules/expect-expect.md
@@ -42,9 +42,9 @@ it('should work with callbacks/async', () => {
 
 ### `assertFunctionNames`
 
-This array option whitelists the assertion function names to look for. Function
-names can use wildcards like `request.*.expect`, `request.**.expect`,
-`request.*.expect*`
+This array option specifies the names of functions that should be considered to
+be asserting functions. Function names can use wildcards i.e `request.*.expect`,
+`request.**.expect`, `request.*.expect*`
 
 Examples of **incorrect** code for the `{ "assertFunctionNames": ["expect"] }`
 option:
@@ -55,11 +55,11 @@ option:
 import { expectSaga } from 'redux-saga-test-plan';
 import { addSaga } from '../src/sagas';
 
-test('returns sum', () =>
+test('returns sum', () => {
   expectSaga(addSaga, 1, 1)
     .returns(2)
     .run();
-);
+});
 ```
 
 Examples of **correct** code for the
@@ -71,11 +71,11 @@ Examples of **correct** code for the
 import { expectSaga } from 'redux-saga-test-plan';
 import { addSaga } from '../src/sagas';
 
-test('returns sum', () =>
+test('returns sum', () => {
   expectSaga(addSaga, 1, 1)
     .returns(2)
     .run();
-);
+});
 ```
 
 Examples of **correct** code for working with the HTTP assertions library

diff --git a/docs/rules/lowercase-name.md b/docs/rules/lowercase-name.md
@@ -37,8 +37,8 @@ it('adds 1 + 2 to equal 3', () => {
 
 ### `ignore`
 
-This array option whitelists function names so that this rule does not report
-their usage as being incorrect. There are three possible values:
+This array option controls which Jest functions are checked by this rule. There
+are three possible values:
 
 - `"describe"`
 - `"test"`
@@ -73,9 +73,9 @@ it('Uppercase description');
 
 ### `allowedPrefixes`
 
-This array option whitelists prefixes that titles can start with with capitals.
-This can be useful when writing tests for api endpoints, where you'd like to
-prefix with the HTTP method.
+This array option allows specifying prefixes which contain capitals that titles
+can start with. This can be useful when writing tests for api endpoints, where
+you'd like to prefix with the HTTP method.
 
 By default, nothing is allowed (the equivalent of `{ "allowedPrefixes": [] }`).
 

diff --git a/docs/rules/no-alias-methods.md b/docs/rules/no-alias-methods.md
@@ -1,4 +1,4 @@
-# Don't use alias methods (`no-alias-methods`)
+# Disallow 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

diff --git a/docs/rules/no-duplicate-hooks.md b/docs/rules/no-duplicate-hooks.md
@@ -1,6 +1,6 @@
 # Disallow duplicate setup and teardown hooks (`no-duplicate-hooks`)
 
-A describe block should not contain duplicate hooks.
+A `describe` block should not contain duplicate hooks.
 
 ## Rule Details
 

diff --git a/docs/rules/no-export.md b/docs/rules/no-export.md
@@ -1,14 +1,13 @@
-# Prevent exporting from test files (`no-export`)
+# Disallow using `exports` in files containing tests (`no-export`)
 
-Prevents exports from test files. If a file has at least 1 test in it, then this
-rule will prevent exports.
+Prevents using `exports` if a file has one or more tests in it.
 
 ## Rule Details
 
 This rule aims to eliminate duplicate runs of tests by exporting things from
 test files. If you import from a test file, then all the tests in that file will
 be run in each imported instance, so bottom line, don't export from a test, but
-instead move helper functions into a seperate file when they need to be shared
+instead move helper functions into a separate file when they need to be shared
 across tests.
 
 Examples of **incorrect** code for this rule:

diff --git a/docs/rules/no-hooks.md b/docs/rules/no-hooks.md
@@ -101,8 +101,8 @@ describe('foo', () => {
 
 ### `allow`
 
-This array option whitelists setup and teardown hooks so that this rule does not
-report their usage as being incorrect. There are four possible values:
+This array option controls which Jest hooks are checked by this rule. There are
+four possible values:
 
 - `"beforeAll"`
 - `"beforeEach"`

diff --git a/docs/rules/no-large-snapshots.md b/docs/rules/no-large-snapshots.md
@@ -1,10 +1,10 @@
 # disallow large snapshots (`no-large-snapshots`)
 
 When using Jest's snapshot capability one should be mindful of the size of
-created snapshots. As a best practice snapshots should be limited in size in
-order to be more manageable and reviewable. A stored snapshot is only as good as
-its review and as such keeping it short, sweet, and readable is important to
-allow for thorough reviews.
+created snapshots. As a general best practice snapshots should be limited in
+size in order to be more manageable and reviewable. A stored snapshot is only as
+good as its review and as such keeping it short, sweet, and readable is
+important to allow for thorough reviews.
 
 ## Usage
 
@@ -15,9 +15,11 @@ you should set `parserOptions` in your config to at least allow ES2015 in order
 to use this rule:
 
 ```js
-parserOptions: {
-  ecmaVersion: 2015,
-},
+module.exports = {
+  parserOptions: {
+    ecmaVersion: 2015,
+  },
+};
 ```
 
 ## Rule Details
@@ -104,11 +106,11 @@ snapshot:
 In an `eslintrc` file:
 
 ```json
-...
+{
   "rules": {
     "jest/no-large-snapshots": ["warn", { "maxSize": 12, "inlineMaxSize": 6 }]
   }
-...
+}
 ```
 
 Max number of lines allowed could be defined by snapshot type (Inline and
@@ -119,48 +121,52 @@ size and `maxSize` for
 If only `maxSize` is provided on options, the value of `maxSize` will be used to
 both snapshot types (Inline and External).
 
-In addition there is an option for whitelisting large snapshot files. Since
-`//eslint` comments will be removed when a `.snap` file is updated, this option
-provides a way of whitelisting large snapshots. The list of whitelistedSnapshots
-is keyed first on the absolute filepath of the snapshot file. You can then
-provide an array of strings to match the snapshot names against. If you're using
-a `.eslintrc.js` file, you can use regular expressions AND strings.
+Since `eslint-disable` comments are not preserved by Jest when updating
+snapshots, you can use the `whitelistedSnapshots` option to have specific
+snapshots allowed regardless of their size.
+
+This option takes a map, with the key being the absolute filepath to a snapshot
+file, and the value an array of values made up of strings and regular
+expressions to compare to the names of the snapshots in the `.snap` file when
+checking if the snapshots size should be allowed.
+
+Note that regular expressions can only be passed in via `.eslintrc.js` as
+instances of `RegExp`.
 
 In an `.eslintrc.js` file:
 
 ```javascript
-...
-
-  "rules": {
-    "jest/no-large-snapshots": ["error",
+module.exports = {
+  rules: {
+    'jest/no-large-snapshots': [
+      'error',
       {
-        "whitelistedSnapshots": {
-          "/path/to/file.js.snap": ["snapshot name 1", /a big snapshot \d+/]
-        }
-      }]
-  }
-
-...
+        whitelistedSnapshots: {
+          '/path/to/file.js.snap': ['snapshot name 1', /a big snapshot \d+/],
+        },
+      },
+    ],
+  },
+};
 ```
 
-Note: If you store your paths as relative paths, you can use `path.resolve` so
-that it can be shared between computers. For example, suppose you have your
-whitelisted snapshots in a file called `allowed-snaps.js` which stores them as
-relative paths. To convert them to absolute paths you can do something like the
-following:
+Since absolute paths are typically not very portable, you can use the builtin
+`path.resolve` function to expand relative paths into absolutes like so:
 
 ```javascript
 const path = require('path');
-const {mapKeys} = require('lodash');
-
-
-const allowedSnapshots = require('./allowed-snaps.js');
-const whitelistedSnapshots = mapKeys(allowedSnapshots, (val, file) => path.resolve(__dirname, file));
 
-...
+module.exports = {
   rules: {
-    "jest/no-large-snapshots": ["error",
-      { whitelistedSnapshots }
-    ]
-  }
+    'jest/no-large-snapshots': [
+      'error',
+      {
+        whitelistedSnapshots: {
+          [path.resolve('test/__snapshots__/get.js.snap')]: ['full request'],
+          [path.resolve('test/__snapshots__/put.js.snap')]: ['full request'],
+        },
+      },
+    ],
+  },
+};
 ```
diff --git a/docs/rules/no-standalone-expect.md b/docs/rules/no-standalone-expect.md
@@ -1,4 +1,4 @@
-# No standalone expect in a describe block (`no-standalone-expect`)
+# Disallow using `expect` outside of `it` or `test` blocks (`no-standalone-expect`)
 
 Prevents `expect` statements outside of a `test` or `it` block. An `expect`
 within a helper function (but outside of a `test` or `it` block) will not

diff --git a/docs/rules/prefer-called-with.md b/docs/rules/prefer-called-with.md
@@ -1,4 +1,4 @@
-# Suggest using `toBeCalledWith` OR `toHaveBeenCalledWith` (`prefer-called-with`)
+# Suggest using `toBeCalledWith()` or `toHaveBeenCalledWith()` (`prefer-called-with`)
 
 The `toBeCalled()` matcher is used to assert that a mock function has been
 called one or more times, without checking the arguments passed. The assertion

diff --git a/docs/rules/prefer-expect-assertions.md b/docs/rules/prefer-expect-assertions.md
@@ -32,13 +32,13 @@ test('my test', () => {
 The following patterns are considered warnings:
 
 ```js
-test("my test", () => {
-  expect.assertions("1");
-  expect(someThing()).toEqual("foo");
+test('my test', () => {
+  expect.assertions('1');
+  expect(someThing()).toEqual('foo');
 });
 
-test("my test", () => {
-  expect.(someThing()).toEqual("foo");
+test('my test', () => {
+  expect(someThing()).toEqual('foo');
 });
 ```