eslint-plugin-jest 24.3.7 → 24.4.0

package/CHANGELOG.md

@@ -1,3 +1,10 @@
+# [24.4.0](https://github.com/jest-community/eslint-plugin-jest/compare/v24.3.7...v24.4.0) (2021-07-21)
+
+
+### Features
+
+* create `max-nested-describe` rule ([#845](https://github.com/jest-community/eslint-plugin-jest/issues/845)) ([8067405](https://github.com/jest-community/eslint-plugin-jest/commit/8067405deb609cc1800bce596e929c1840d290ab))
+
 ## [24.3.7](https://github.com/jest-community/eslint-plugin-jest/compare/v24.3.6...v24.3.7) (2021-07-21)
 
 

package/README.md

@@ -135,6 +135,7 @@ installations requiring long-term consistency.
 | [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][] |              |

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

@@ -0,0 +1,131 @@
+# Enforces a maximum depth to nested describe calls (`max-nested-describe`)
+
+While it's useful to be able to group your tests together within the same file
+using `describe()`, having too many levels of nesting throughout your tests make
+them difficult to read.
+
+## Rule Details
+
+This rule enforces a maximum depth to nested `describe()` calls to improve code
+clarity in your tests.
+
+The following patterns are considered warnings (with the default option of
+`{ "max": 5 } `):
+
+```js
+describe('foo', () => {
+  describe('bar', () => {
+    describe('baz', () => {
+      describe('qux', () => {
+        describe('quxx', () => {
+          describe('too many', () => {
+            it('should get something', () => {
+              expect(getSomething()).toBe('Something');
+            });
+          });
+        });
+      });
+    });
+  });
+});
+
+describe('foo', function () {
+  describe('bar', function () {
+    describe('baz', function () {
+      describe('qux', function () {
+        describe('quxx', function () {
+          describe('too many', function () {
+            it('should get something', () => {
+              expect(getSomething()).toBe('Something');
+            });
+          });
+        });
+      });
+    });
+  });
+});
+```
+
+The following patterns are **not** considered warnings (with the default option
+of `{ "max": 5 } `):
+
+```js
+describe('foo', () => {
+  describe('bar', () => {
+    it('should get something', () => {
+      expect(getSomething()).toBe('Something');
+    });
+  });
+
+  describe('qux', () => {
+    it('should get something', () => {
+      expect(getSomething()).toBe('Something');
+    });
+  });
+});
+
+describe('foo2', function () {
+  it('should get something', () => {
+    expect(getSomething()).toBe('Something');
+  });
+});
+
+describe('foo', function () {
+  describe('bar', function () {
+    describe('baz', function () {
+      describe('qux', function () {
+        describe('this is the limit', function () {
+          it('should get something', () => {
+            expect(getSomething()).toBe('Something');
+          });
+        });
+      });
+    });
+  });
+});
+```
+
+## Options
+
+```json
+{
+  "jest/max-nested-describe": [
+    "error",
+    {
+      "max": 5
+    }
+  ]
+}
+```
+
+### `max`
+
+Enforces a maximum depth for nested `describe()`.
+
+This has a default value of `5`.
+
+Examples of patterns **not** considered warnings with options set to
+`{ "max": 2 }`:
+
+```js
+describe('foo', () => {
+  describe('bar', () => {
+    it('should get something', () => {
+      expect(getSomething()).toBe('Something');
+    });
+  });
+});
+
+describe('foo2', function()) {
+  describe('bar2', function() {
+    it('should get something', function() {
+      expect(getSomething()).toBe('Something');
+    });
+
+    it('should get  else', function() {
+      expect(getSomething()).toBe('Something');
+    });
+  });
+});
+
+```

package/lib/rules/max-nested-describe.js

@@ -0,0 +1,87 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.default = void 0;
+
+var _experimentalUtils = require("@typescript-eslint/experimental-utils");
+
+var _utils = require("./utils");
+
+var _default = (0, _utils.createRule)({
+  name: __filename,
+  meta: {
+    docs: {
+      category: 'Best Practices',
+      description: 'Enforces a maximum depth to nested describe calls',
+      recommended: false
+    },
+    messages: {
+      exceededMaxDepth: 'Too many nested describe calls ({{ depth }}). Maximum allowed is {{ max }}.'
+    },
+    type: 'suggestion',
+    schema: [{
+      type: 'object',
+      properties: {
+        max: {
+          type: 'integer',
+          minimum: 0
+        }
+      },
+      additionalProperties: false
+    }]
+  },
+  defaultOptions: [{
+    max: 5
+  }],
+
+  create(context, [{
+    max
+  }]) {
+    const describeCallbackStack = [];
+
+    function pushDescribeCallback(node) {
+      const {
+        parent
+      } = node;
+
+      if ((parent === null || parent === void 0 ? void 0 : parent.type) !== _experimentalUtils.AST_NODE_TYPES.CallExpression || !(0, _utils.isDescribeCall)(parent)) {
+        return;
+      }
+
+      describeCallbackStack.push(0);
+
+      if (describeCallbackStack.length > max) {
+        context.report({
+          node: parent,
+          messageId: 'exceededMaxDepth',
+          data: {
+            depth: describeCallbackStack.length,
+            max
+          }
+        });
+      }
+    }
+
+    function popDescribeCallback(node) {
+      const {
+        parent
+      } = node;
+
+      if ((parent === null || parent === void 0 ? void 0 : parent.type) === _experimentalUtils.AST_NODE_TYPES.CallExpression && (0, _utils.isDescribeCall)(parent)) {
+        describeCallbackStack.pop();
+      }
+    }
+
+    return {
+      FunctionExpression: pushDescribeCallback,
+      'FunctionExpression:exit': popDescribeCallback,
+      ArrowFunctionExpression: pushDescribeCallback,
+      'ArrowFunctionExpression:exit': popDescribeCallback
+    };
+  }
+
+});
+
+exports.default = _default;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "eslint-plugin-jest",
-  "version": "24.3.7",
+  "version": "24.4.0",
   "description": "Eslint rules for Jest",
   "keywords": [
     "eslint",