feat: add should-be-fine support for flat configs (#1505)

* feat: support flat config * fix: redo flat config * docs: add note about flat config support * fix: handle snapshot processor * chore: remove unneeded cast * chore: exclude flat configs from docs * test: use property matches to reduce snapshot size
jest-community · Feb 16, 2024 · 4cc2a1b · 4cc2a1b
1 parent 14eafdd
commit 4cc2a1b
Show file tree

Hide file tree

Showing 5 changed files with 376 additions and 26 deletions.
diff --git a/.eslint-doc-generatorrc.js b/.eslint-doc-generatorrc.js
@@ -3,7 +3,13 @@ const { prettier: prettierRC } = require('./package.json');
 
 /** @type {import('eslint-doc-generator').GenerateOptions} */
 const config = {
-  ignoreConfig: ['all'],
+  ignoreConfig: [
+    'all',
+    'flat/all',
+    'flat/recommended',
+    'flat/style',
+    'flat/snapshots',
+  ],
   ruleDocTitleFormat: 'desc-parens-name',
   ruleDocSectionInclude: ['Rule details'],
   ruleListColumns: [

diff --git a/README.md b/README.md
@@ -22,6 +22,15 @@ yarn add --dev eslint eslint-plugin-jest
 
 ## Usage
 
+> [!NOTE]
+>
+> `eslint.config.js` is supported, though most of the plugin documentation still
+> currently uses `.eslintrc` syntax.
+>
+> Refer to the
+> [ESLint documentation on the new configuration file format](https://eslint.org/docs/latest/use/configure/configuration-files-new)
+> for more.
+
 Add `jest` to the plugins section of your `.eslintrc` configuration file. You
 can omit the `eslint-plugin-` prefix:
 
@@ -85,7 +94,7 @@ test-related. This means it's generally not suitable to include them in your
 top-level configuration as that applies to all files being linted which can
 include source files.
 
-You can use
+For `.eslintrc` configs you can use
 [overrides](https://eslint.org/docs/user-guide/configuring/configuration-files#how-do-overrides-work)
 to have ESLint apply additional rules to specific files:
 
@@ -106,6 +115,30 @@ to have ESLint apply additional rules to specific files:
 }
 ```
 
+For `eslint.config.js` you can use
+[`files` and `ignores`](https://eslint.org/docs/latest/use/configure/configuration-files-new#specifying-files-and-ignores):
+
+```js
+const jest = require('eslint-plugin-jest');
+
+module.exports = [
+  ...require('@eslint/js').configs.recommended,
+  {
+    files: ['test/**'],
+    ...jest.configs['flat/recommended'],
+    rules: {
+      ...jest.configs['flat/recommended'],
+      'jest/prefer-expect-assertions': 'off',
+    },
+  },
+  // you can also configure jest rules in other objects, so long as some of the `files` match
+  {
+    files: ['test/**'],
+    rules: { 'jest/prefer-expect-assertions': 'off' },
+  },
+];
+```
+
 ### Jest `version` setting
 
 The behaviour of some rules (specifically [`no-deprecated-functions`][]) change
@@ -145,20 +178,41 @@ module.exports = {
 
 ## Shareable configurations
 
+> [!NOTE]
+>
+> `eslint.config.js` compatible versions of configs are available prefixed with
+> `flat/` and may be subject to small breaking changes while ESLint v9 is being
+> finalized.
+
 ### Recommended
 
 This plugin exports a recommended configuration that enforces good testing
 practices.
 
-To enable this configuration use the `extends` property in your `.eslintrc`
-config file:
+To enable this configuration with `.eslintrc`, use the `extends` property:
 
 ```json
 {
   "extends": ["plugin:jest/recommended"]
 }
 ```
 
+To enable this configuration with `eslint.config.js`, use
+`jest.configs['flat/recommended']`:
+
+```js
+const jest = require('eslint-plugin-jest');
+
+module.exports = [
+  {
+    files: [
+      /* glob matching your test files */
+    ],
+    ...jest.configs['flat/recommended'],
+  },
+];
+```
+
 ### Style
 
 This plugin also exports a configuration named `style`, which adds some
@@ -174,9 +228,21 @@ config file:
 }
 ```
 
-See
-[ESLint documentation](https://eslint.org/docs/user-guide/configuring/configuration-files#extending-configuration-files)
-for more information about extending configuration files.
+To enable this configuration with `eslint.config.js`, use
+`jest.configs['flat/style']`:
+
+```js
+const jest = require('eslint-plugin-jest');
+
+module.exports = [
+  {
+    files: [
+      /* glob matching your test files */
+    ],
+    ...jest.configs['flat/style'],
+  },
+];
+```
 
 ### All
 
@@ -189,10 +255,55 @@ If you want to enable all rules instead of only some you can do so by adding the
 }
 ```
 
+To enable this configuration with `eslint.config.js`, use
+`jest.configs['flat/all']`:
+
+```js
+const jest = require('eslint-plugin-jest');
+
+module.exports = [
+  {
+    files: [
+      /* glob matching your test files */
+    ],
+    ...jest.configs['flat/all'],
+  },
+];
+```
+
 While the `recommended` and `style` configurations only change in major versions
 the `all` configuration may change in any release and is thus unsuited for
 installations requiring long-term consistency.
 
+## Snapshot processing
+
+> [!NOTE]
+>
+> This is only relevant for `eslint.config.js`
+
+This plugin provides a
+[custom processor](https://eslint.org/docs/latest/extend/custom-processors) to
+allow rules to "lint" snapshot files.
+
+For `.eslintrc` based configs, this is automatically enabled out of the box but
+must be opted into for `eslint.config.js` using the `flat/snapshots` config:
+
+```js
+const jest = require('eslint-plugin-jest');
+
+module.exports = [
+  {
+    ...jest.configs['flat/snapshots'],
+    rules: {
+      'jest/no-large-snapshots': ['error', { maxSize: 1 }],
+    },
+  },
+];
+```
+
+Unlike other configs, this includes a `files` array that matches `.snap` files
+meaning you can use it directly
+
 ## Rules
 
 <!-- begin auto-generated rules list -->

diff --git a/src/__tests__/__snapshots__/rules.test.ts.snap b/src/__tests__/__snapshots__/rules.test.ts.snap
@@ -64,6 +64,182 @@ exports[`rules should export configs that refer to actual rules 1`] = `
       "jest/valid-title": "error",
     },
   },
+  "flat/all": {
+    "languageOptions": {
+      "globals": {
+        "afterAll": false,
+        "afterEach": false,
+        "beforeAll": false,
+        "beforeEach": false,
+        "describe": false,
+        "expect": false,
+        "fit": false,
+        "it": false,
+        "jest": false,
+        "test": false,
+        "xdescribe": false,
+        "xit": false,
+        "xtest": false,
+      },
+    },
+    "plugins": {
+      "jest": ObjectContaining {
+        "meta": {
+          "name": "eslint-plugin-jest",
+          "version": "27.8.0",
+        },
+      },
+    },
+    "rules": {
+      "jest/consistent-test-it": "error",
+      "jest/expect-expect": "error",
+      "jest/max-expects": "error",
+      "jest/max-nested-describe": "error",
+      "jest/no-alias-methods": "error",
+      "jest/no-commented-out-tests": "error",
+      "jest/no-conditional-expect": "error",
+      "jest/no-conditional-in-test": "error",
+      "jest/no-confusing-set-timeout": "error",
+      "jest/no-deprecated-functions": "error",
+      "jest/no-disabled-tests": "error",
+      "jest/no-done-callback": "error",
+      "jest/no-duplicate-hooks": "error",
+      "jest/no-export": "error",
+      "jest/no-focused-tests": "error",
+      "jest/no-hooks": "error",
+      "jest/no-identical-title": "error",
+      "jest/no-interpolation-in-snapshots": "error",
+      "jest/no-jasmine-globals": "error",
+      "jest/no-large-snapshots": "error",
+      "jest/no-mocks-import": "error",
+      "jest/no-restricted-jest-methods": "error",
+      "jest/no-restricted-matchers": "error",
+      "jest/no-standalone-expect": "error",
+      "jest/no-test-prefixes": "error",
+      "jest/no-test-return-statement": "error",
+      "jest/no-untyped-mock-factory": "error",
+      "jest/prefer-called-with": "error",
+      "jest/prefer-comparison-matcher": "error",
+      "jest/prefer-each": "error",
+      "jest/prefer-equality-matcher": "error",
+      "jest/prefer-expect-assertions": "error",
+      "jest/prefer-expect-resolves": "error",
+      "jest/prefer-hooks-in-order": "error",
+      "jest/prefer-hooks-on-top": "error",
+      "jest/prefer-lowercase-title": "error",
+      "jest/prefer-mock-promise-shorthand": "error",
+      "jest/prefer-snapshot-hint": "error",
+      "jest/prefer-spy-on": "error",
+      "jest/prefer-strict-equal": "error",
+      "jest/prefer-to-be": "error",
+      "jest/prefer-to-contain": "error",
+      "jest/prefer-to-have-length": "error",
+      "jest/prefer-todo": "error",
+      "jest/require-hook": "error",
+      "jest/require-to-throw-message": "error",
+      "jest/require-top-level-describe": "error",
+      "jest/unbound-method": "error",
+      "jest/valid-describe-callback": "error",
+      "jest/valid-expect": "error",
+      "jest/valid-expect-in-promise": "error",
+      "jest/valid-title": "error",
+    },
+  },
+  "flat/recommended": {
+    "languageOptions": {
+      "globals": {
+        "afterAll": false,
+        "afterEach": false,
+        "beforeAll": false,
+        "beforeEach": false,
+        "describe": false,
+        "expect": false,
+        "fit": false,
+        "it": false,
+        "jest": false,
+        "test": false,
+        "xdescribe": false,
+        "xit": false,
+        "xtest": false,
+      },
+    },
+    "plugins": {
+      "jest": ObjectContaining {
+        "meta": {
+          "name": "eslint-plugin-jest",
+          "version": "27.8.0",
+        },
+      },
+    },
+    "rules": {
+      "jest/expect-expect": "warn",
+      "jest/no-alias-methods": "error",
+      "jest/no-commented-out-tests": "warn",
+      "jest/no-conditional-expect": "error",
+      "jest/no-deprecated-functions": "error",
+      "jest/no-disabled-tests": "warn",
+      "jest/no-done-callback": "error",
+      "jest/no-export": "error",
+      "jest/no-focused-tests": "error",
+      "jest/no-identical-title": "error",
+      "jest/no-interpolation-in-snapshots": "error",
+      "jest/no-jasmine-globals": "error",
+      "jest/no-mocks-import": "error",
+      "jest/no-standalone-expect": "error",
+      "jest/no-test-prefixes": "error",
+      "jest/valid-describe-callback": "error",
+      "jest/valid-expect": "error",
+      "jest/valid-expect-in-promise": "error",
+      "jest/valid-title": "error",
+    },
+  },
+  "flat/snapshots": {
+    "files": [
+      "**/*.snap",
+    ],
+    "plugins": {
+      "jest": ObjectContaining {
+        "meta": {
+          "name": "eslint-plugin-jest",
+          "version": "27.8.0",
+        },
+      },
+    },
+    "processor": "jest/snapshots",
+  },
+  "flat/style": {
+    "languageOptions": {
+      "globals": {
+        "afterAll": false,
+        "afterEach": false,
+        "beforeAll": false,
+        "beforeEach": false,
+        "describe": false,
+        "expect": false,
+        "fit": false,
+        "it": false,
+        "jest": false,
+        "test": false,
+        "xdescribe": false,
+        "xit": false,
+        "xtest": false,
+      },
+    },
+    "plugins": {
+      "jest": ObjectContaining {
+        "meta": {
+          "name": "eslint-plugin-jest",
+          "version": "27.8.0",
+        },
+      },
+    },
+    "rules": {
+      "jest/no-alias-methods": "warn",
+      "jest/prefer-to-be": "error",
+      "jest/prefer-to-contain": "error",
+      "jest/prefer-to-have-length": "error",
+    },
+  },
   "recommended": {
     "env": {
       "jest/globals": true,