eslint-plugin-jest 24.4.2 → 26.1.0

package/README.md

@@ -59,23 +59,43 @@ doing:
 This is included in all configs shared by this plugin, so can be omitted if
 extending them.
 
-The behaviour of some rules (specifically `no-deprecated-functions`) change
-depending on the version of `jest` being used.
+### Jest `version` setting
 
-This setting is detected automatically based off the version of the `jest`
-package installed in `node_modules`, but it can also be provided explicitly if
-desired:
+The behaviour of some rules (specifically [`no-deprecated-functions`][]) change
+depending on the version of Jest being used.
+
+By default, this plugin will attempt to determine to locate Jest using
+`require.resolve`, meaning it will start looking in the closest `node_modules`
+folder to the file being linted and work its way up.
+
+Since we cache the automatically determined version, if you're linting
+sub-folders that have different versions of Jest, you may find that the wrong
+version of Jest is considered when linting. You can work around this by
+providing the Jest version explicitly in nested ESLint configs:
 
 ```json
 {
   "settings": {
     "jest": {
-      "version": 26
+      "version": 27
     }
   }
 }
 ```
 
+To avoid hard-coding a number, you can also fetch it from the installed version
+of Jest if you use a JavaScript config file such as `.eslintrc.js`:
+
+```js
+module.exports = {
+  settings: {
+    jest: {
+      version: require('jest/package.json').version,
+    },
+  },
+};
+```
+
 ## Shareable configurations
 
 ### Recommended
@@ -108,7 +128,7 @@ config file:
 ```
 
 See
-[ESLint documentation](http://eslint.org/docs/user-guide/configuring#extending-configuration-files)
+[ESLint documentation](https://eslint.org/docs/user-guide/configuring/configuration-files#extending-configuration-files)
 for more information about extending configuration files.
 
 ### All
@@ -130,49 +150,53 @@ installations requiring long-term consistency.
 
 <!-- begin base rules list -->
 
-| Rule                                                                         | Description                                                     | Configurations   | Fixable      |
-| ---------------------------------------------------------------------------- | --------------------------------------------------------------- | ---------------- | ------------ |
-| [consistent-test-it](docs/rules/consistent-test-it.md)                       | Have control over `test` and `it` usages                        |                  | ![fixable][] |
-| [expect-expect](docs/rules/expect-expect.md)                                 | Enforce assertion to be made in a test body                     | ![recommended][] |              |
-| [lowercase-name](docs/rules/lowercase-name.md)                               | Enforce lowercase test names                                    |                  | ![fixable][] |
-| [max-nested-describe](docs/rules/max-nested-describe.md)                     | Enforces a maximum depth to nested describe calls               |                  |              |
-| [no-alias-methods](docs/rules/no-alias-methods.md)                           | Disallow alias methods                                          | ![style][]       | ![fixable][] |
-| [no-commented-out-tests](docs/rules/no-commented-out-tests.md)               | Disallow commented out tests                                    | ![recommended][] |              |
-| [no-conditional-expect](docs/rules/no-conditional-expect.md)                 | Prevent calling `expect` conditionally                          | ![recommended][] |              |
-| [no-deprecated-functions](docs/rules/no-deprecated-functions.md)             | Disallow use of deprecated functions                            | ![recommended][] | ![fixable][] |
-| [no-disabled-tests](docs/rules/no-disabled-tests.md)                         | Disallow disabled tests                                         | ![recommended][] |              |
-| [no-done-callback](docs/rules/no-done-callback.md)                           | Avoid using a callback in asynchronous tests and hooks          | ![recommended][] | ![suggest][] |
-| [no-duplicate-hooks](docs/rules/no-duplicate-hooks.md)                       | Disallow duplicate setup and teardown hooks                     |                  |              |
-| [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][] | ![suggest][] |
-| [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-interpolation-in-snapshots](docs/rules/no-interpolation-in-snapshots.md) | Disallow string interpolation inside snapshots                  | ![recommended][] |              |
-| [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-restricted-matchers](docs/rules/no-restricted-matchers.md)               | Disallow specific matchers & modifiers                          |                  |              |
-| [no-standalone-expect](docs/rules/no-standalone-expect.md)                   | Disallow using `expect` outside of `it` or `test` blocks        | ![recommended][] |              |
-| [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-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 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-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)       | 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][] |              |
-| [valid-title](docs/rules/valid-title.md)                                     | Enforce valid titles                                            | ![recommended][] | ![fixable][] |
+| Rule                                                                         | Description                                                         | Configurations   | Fixable      |
+| ---------------------------------------------------------------------------- | ------------------------------------------------------------------- | ---------------- | ------------ |
+| [consistent-test-it](docs/rules/consistent-test-it.md)                       | Have control over `test` and `it` usages                            |                  | ![fixable][] |
+| [expect-expect](docs/rules/expect-expect.md)                                 | Enforce assertion to be made in a test body                         | ![recommended][] |              |
+| [max-nested-describe](docs/rules/max-nested-describe.md)                     | Enforces a maximum depth to nested describe calls                   |                  |              |
+| [no-alias-methods](docs/rules/no-alias-methods.md)                           | Disallow alias methods                                              | ![style][]       | ![fixable][] |
+| [no-commented-out-tests](docs/rules/no-commented-out-tests.md)               | Disallow commented out tests                                        | ![recommended][] |              |
+| [no-conditional-expect](docs/rules/no-conditional-expect.md)                 | Prevent calling `expect` conditionally                              | ![recommended][] |              |
+| [no-conditional-in-test](docs/rules/no-conditional-in-test.md)               | Disallow conditional logic in tests                                 |                  |              |
+| [no-deprecated-functions](docs/rules/no-deprecated-functions.md)             | Disallow use of deprecated functions                                | ![recommended][] | ![fixable][] |
+| [no-disabled-tests](docs/rules/no-disabled-tests.md)                         | Disallow disabled tests                                             | ![recommended][] |              |
+| [no-done-callback](docs/rules/no-done-callback.md)                           | Avoid using a callback in asynchronous tests and hooks              | ![recommended][] | ![suggest][] |
+| [no-duplicate-hooks](docs/rules/no-duplicate-hooks.md)                       | Disallow duplicate setup and teardown hooks                         |                  |              |
+| [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][] | ![suggest][] |
+| [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-interpolation-in-snapshots](docs/rules/no-interpolation-in-snapshots.md) | Disallow string interpolation inside snapshots                      | ![recommended][] |              |
+| [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-restricted-matchers](docs/rules/no-restricted-matchers.md)               | Disallow specific matchers & modifiers                              |                  |              |
+| [no-standalone-expect](docs/rules/no-standalone-expect.md)                   | Disallow using `expect` outside of `it` or `test` blocks            | ![recommended][] |              |
+| [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-comparison-matcher](docs/rules/prefer-comparison-matcher.md)         | Suggest using the built-in comparison matchers                      |                  | ![fixable][] |
+| [prefer-equality-matcher](docs/rules/prefer-equality-matcher.md)             | Suggest using the built-in equality matchers                        |                  | ![suggest][] |
+| [prefer-expect-assertions](docs/rules/prefer-expect-assertions.md)           | Suggest using `expect.assertions()` OR `expect.hasAssertions()`     |                  | ![suggest][] |
+| [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][] |
+| [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-hook](docs/rules/require-hook.md)                                   | Require setup and teardown code to be within a hook                 |                  |              |
+| [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)       | Require test cases and hooks to be inside a `describe` block        |                  |              |
+| [valid-describe-callback](docs/rules/valid-describe-callback.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)             | Ensure promises that have expectations in their chain are valid     | ![recommended][] |              |
+| [valid-title](docs/rules/valid-title.md)                                     | Enforce valid titles                                                | ![recommended][] | ![fixable][] |
 
 <!-- end base rules list -->
 
@@ -226,3 +250,4 @@ https://github.com/istanbuljs/eslint-plugin-istanbul
 [suggest]: https://img.shields.io/badge/-suggest-yellow.svg
 [fixable]: https://img.shields.io/badge/-fixable-green.svg
 [style]: https://img.shields.io/badge/-style-blue.svg
+[`no-deprecated-functions`]: docs/rules/no-deprecated-functions.md

package/docs/rules/expect-expect.md

@@ -34,7 +34,8 @@ it('should work with callbacks/async', () => {
   "jest/expect-expect": [
     "error",
     {
-      "assertFunctionNames": ["expect"]
+      "assertFunctionNames": ["expect"],
+      "additionalTestBlockFunctions": []
     }
   ]
 }
@@ -102,3 +103,43 @@ describe('GET /user', function () {
   });
 });
 ```
+
+### `additionalTestBlockFunctions`
+
+This array can be used to specify the names of functions that should also be
+treated as test blocks:
+
+```json
+{
+  "rules": {
+    "jest/expect-expect": [
+      "error",
+      { "additionalTestBlockFunctions": ["theoretically"] }
+    ]
+  }
+}
+```
+
+The following is _correct_ when using the above configuration:
+
+```js
+import theoretically from 'jest-theories';
+
+describe('NumberToLongString', () => {
+  const theories = [
+    { input: 100, expected: 'One hundred' },
+    { input: 1000, expected: 'One thousand' },
+    { input: 10000, expected: 'Ten thousand' },
+    { input: 100000, expected: 'One hundred thousand' },
+  ];
+
+  theoretically(
+    'the number {input} is correctly translated to string',
+    theories,
+    theory => {
+      const output = NumberToLongString(theory.input);
+      expect(output).toBe(theory.expected);
+    },
+  );
+});
+```

package/docs/rules/max-nested-describe.md

@@ -116,16 +116,15 @@ describe('foo', () => {
   });
 });
 
-describe('foo2', function()) {
-  describe('bar2', function() {
-    it('should get something', function() {
+describe('foo2', function () {
+  describe('bar2', function () {
+    it('should get something', function () {
       expect(getSomething()).toBe('Something');
     });
 
-    it('should get  else', function() {
+    it('should get  else', function () {
       expect(getSomething()).toBe('Something');
     });
   });
 });
-
 ```

package/docs/rules/no-conditional-expect.md

@@ -8,9 +8,9 @@ assumed to be promises.
 
 ## Rule Details
 
-Jest considered a test to have failed if it throws an error, rather than on if
-any particular function is called, meaning conditional calls to `expect` could
-result in tests silently being skipped.
+Jest only considers a test to have failed if it throws an error, meaning if
+calls to assertion functions like `expect` occur in conditional code such as a
+`catch` statement, tests can end up passing but not actually test anything.
 
 Additionally, conditionals tend to make tests more brittle and complex, as they
 increase the amount of mental thinking needed to understand what is actually
@@ -79,3 +79,57 @@ it('throws an error', async () => {
   await expect(foo).rejects.toThrow(Error);
 });
 ```
+
+### How to catch a thrown error for testing without violating this rule
+
+A common situation that comes up with this rule is when wanting to test
+properties on a thrown error, as Jest's `toThrow` matcher only checks the
+`message` property.
+
+Most people write something like this:
+
+```typescript
+describe('when the http request fails', () => {
+  it('includes the status code in the error', async () => {
+    try {
+      await makeRequest(url);
+    } catch (error) {
+      expect(error).toHaveProperty('statusCode', 404);
+    }
+  });
+});
+```
+
+As stated above, the problem with this is that if `makeRequest()` doesn't throw
+the test will still pass as if the `expect` had been called.
+
+While you can use `expect.assertions` & `expect.hasAssertions` for these
+situations, they only work with `expect`.
+
+A better way to handle this situation is to introduce a wrapper to handle the
+catching, and otherwise returns a specific "no error thrown" error if nothing is
+thrown by the wrapped function:
+
+```typescript
+class NoErrorThrownError extends Error {}
+
+const getError = async <TError>(call: () => unknown): Promise<TError> => {
+  try {
+    await call();
+
+    throw new NoErrorThrownError();
+  } catch (error: unknown) {
+    return error as TError;
+  }
+};
+
+describe('when the http request fails', () => {
+  it('includes the status code in the error', async () => {
+    const error = await getError(async () => makeRequest(url));
+
+    // check that the returned error wasn't that no error was thrown
+    expect(error).not.toBeInstanceOf(NoErrorThrownError);
+    expect(error).toHaveProperty('statusCode', 404);
+  });
+});
+```

package/docs/rules/no-conditional-in-test.md

@@ -0,0 +1,79 @@
+# Disallow conditional logic in tests (`no-conditional-in-test`)
+
+Conditional logic in tests is usually an indication that a test is attempting to
+cover too much, and not testing the logic it intends to. Each branch of code
+executing within a conditional statement will usually be better served by a test
+devoted to it.
+
+## Rule Details
+
+This rule reports on any use of a conditional statement such as `if`, `switch`,
+and ternary expressions.
+
+Examples of **incorrect** code for this rule:
+
+```js
+it('foo', () => {
+  if (true) {
+    doTheThing();
+  }
+});
+
+it('bar', () => {
+  switch (mode) {
+    case 'none':
+      generateNone();
+    case 'single':
+      generateOne();
+    case 'multiple':
+      generateMany();
+  }
+
+  expect(fixtures.length).toBeGreaterThan(-1);
+});
+
+it('baz', async () => {
+  const promiseValue = () => {
+    return something instanceof Promise
+      ? something
+      : Promise.resolve(something);
+  };
+
+  await expect(promiseValue()).resolves.toBe(1);
+});
+```
+
+Examples of **correct** code for this rule:
+
+```js
+describe('my tests', () => {
+  if (true) {
+    it('foo', () => {
+      doTheThing();
+    });
+  }
+});
+
+beforeEach(() => {
+  switch (mode) {
+    case 'none':
+      generateNone();
+    case 'single':
+      generateOne();
+    case 'multiple':
+      generateMany();
+  }
+});
+
+it('bar', () => {
+  expect(fixtures.length).toBeGreaterThan(-1);
+});
+
+const promiseValue = something => {
+  return something instanceof Promise ? something : Promise.resolve(something);
+};
+
+it('baz', async () => {
+  await expect(promiseValue()).resolves.toBe(1);
+});
+```

package/docs/rules/no-deprecated-functions.md

@@ -6,6 +6,11 @@ either been renamed for clarity, or replaced with more powerful APIs.
 While typically these deprecated functions are kept in the codebase for a number
 of majors, eventually they are removed completely.
 
+This rule requires knowing which version of Jest you're using - see
+[this section of the readme](../../README.md#jest-version-setting) for details
+on how that is obtained automatically and how you can explicitly provide a
+version if needed.
+
 ## Rule details
 
 This rule warns about calls to deprecated functions, and provides details on

package/docs/rules/no-done-callback.md

@@ -3,7 +3,7 @@
 When calling asynchronous code in hooks and tests, `jest` needs to know when the
 asynchronous work is complete to progress the current run.
 
-Originally the most common pattern to archive this was to use callbacks:
+Originally the most common pattern to achieve this was to use callbacks:
 
 ```js
 test('the data is peanut butter', done => {
@@ -20,11 +20,11 @@ test('the data is peanut butter', done => {
 });
 ```
 
-This can be very error prone however, as it requires careful understanding of
+This can be very error-prone however, as it requires careful understanding of
 how assertions work in tests or otherwise tests won't behave as expected.
 
 For example, if the `try/catch` was left out of the above code, the test would
-timeout rather than fail. Even with the `try/catch`, forgetting to pass the
+time out rather than fail. Even with the `try/catch`, forgetting to pass the
 caught error to `done` will result in `jest` believing the test has passed.
 
 A more straightforward way to handle asynchronous code is to use Promises:

package/docs/rules/no-if.md

@@ -1,5 +1,10 @@
 # Disallow conditional logic (`no-if`)
 
+## Deprecated
+
+This rule has been deprecated in favor of
+[`no-conditional-in-test`](no-conditional-in-test.md).
+
 Conditional logic in tests is usually an indication that a test is attempting to
 cover too much, and not testing the logic it intends to. Each branch of code
 executing within an if statement will usually be better served by a test devoted

package/docs/rules/no-standalone-expect.md

@@ -8,9 +8,9 @@ trigger this rule.
 
 This rule aims to eliminate `expect` statements that will not be executed. An
 `expect` inside of a `describe` block but outside of a `test` or `it` block or
-outside of a `describe` will not execute and therefore will trigger this rule.
-It is viable, however, to have an `expect` in a helper function that is called
-from within a `test` or `it` block so `expect` statements in a function will not
+outside a `describe` will not execute and therefore will trigger this rule. It
+is viable, however, to have an `expect` in a helper function that is called from
+within a `test` or `it` block so `expect` statements in a function will not
 trigger this rule.
 
 Statements like `expect.hasAssertions()` will NOT trigger this rule since these

package/docs/rules/no-test-return-statement.md

@@ -7,8 +7,7 @@ If you are returning Promises then you should update the test to use
 
 ## Rule details
 
-This rule triggers a warning if you use a return statement inside of a test
-body.
+This rule triggers a warning if you use a return statement inside a test body.
 
 ```js
 /*eslint jest/no-test-return-statement: "error"*/

package/docs/rules/prefer-comparison-matcher.md

@@ -0,0 +1,55 @@
+# Suggest using the built-in comparison matchers (`prefer-comparison-matcher`)
+
+Jest has a number of built-in matchers for comparing numbers which allow for
+more readable tests and error messages if an expectation fails.
+
+## Rule details
+
+This rule checks for comparisons in tests that could be replaced with one of the
+following built-in comparison matchers:
+
+- `toBeGreaterThan`
+- `toBeGreaterThanOrEqual`
+- `toBeLessThan`
+- `toBeLessThanOrEqual`
+
+Examples of **incorrect** code for this rule:
+
+```js
+expect(x > 5).toBe(true);
+expect(x < 7).not.toEqual(true);
+expect(x <= y).toStrictEqual(true);
+```
+
+Examples of **correct** code for this rule:
+
+```js
+expect(x).toBeGreaterThan(5);
+expect(x).not.toBeLessThanOrEqual(7);
+expect(x).toBeLessThanOrEqual(y);
+
+// special case - see below
+expect(x < 'Carl').toBe(true);
+```
+
+Note that these matchers only work with numbers and bigints, and that the rule
+assumes that any variables on either side of the comparison operator are of one
+of those types - this means if you're using the comparison operator with
+strings, the fix applied by this rule will result in an error.
+
+```js
+expect(myName).toBeGreaterThanOrEqual(theirName); // Matcher error: received value must be a number or bigint
+```
+
+The reason for this is that comparing strings with these operators is expected
+to be very rare and would mean not being able to have an automatic fixer for
+this rule.
+
+If for some reason you are using these operators to compare strings, you can
+disable this rule using an inline
+[configuration comment](https://eslint.org/docs/user-guide/configuring/rules#disabling-rules):
+
+```js
+// eslint-disable-next-line jest/prefer-comparison-matcher
+expect(myName > theirName).toBe(true);
+```

package/docs/rules/prefer-equality-matcher.md

@@ -0,0 +1,29 @@
+# Suggest using the built-in equality matchers (`prefer-equality-matcher`)
+
+Jest has built-in matchers for expecting equality which allow for more readable
+tests and error messages if an expectation fails.
+
+## Rule details
+
+This rule checks for _strict_ equality checks (`===` & `!==`) in tests that
+could be replaced with one of the following built-in equality matchers:
+
+- `toBe`
+- `toEqual`
+- `toStrictEqual`
+
+Examples of **incorrect** code for this rule:
+
+```js
+expect(x === 5).toBe(true);
+expect(name === 'Carl').not.toEqual(true);
+expect(myObj !== thatObj).toStrictEqual(true);
+```
+
+Examples of **correct** code for this rule:
+
+```js
+expect(x).toBe(5);
+expect(name).not.toEqual('Carl');
+expect(myObj).toStrictEqual(thatObj);
+```