feat: create max-nested-describe rule

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][] |              |

docs/rules/max-nested-describe.md

@@ -0,0 +1,111 @@
+# 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": 2 } `):
+
+```js
+describe('foo', () => {
+  describe('bar', () => {
+    describe('baz', () => {
+      it('should get something', () => {
+        expect(getSomething().toBe('Something'));
+      });
+    });
+  });
+});
+
+describe('foo2', function () {
+  describe('bar2', function () {
+    describe('baz2', function () {
+      it('should get something', () => {
+        expect(getSomething().toBe('Something'));
+      });
+    });
+  });
+});
+```
+
+The following patterns are **not** considered warnings (with the default option
+of `{ "max": 2 } `):
+
+```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'));
+  });
+});
+```
+
+## Options
+
+```json
+{
+  "jest/max-nested-describe": [
+    "error",
+    {
+      "max": 3
+    }
+  ]
+}
+```
+
+### `max`
+
+Enforces a maximum depth for nested `describe()`.
+
+This has default value of `2`.
+
+Examples of patterns **not** considered warnings with options set to
+`{ "max": 3 }`:
+
+```js
+describe('foo', () => {
+  describe('bar', () => {
+    describe('baz', () => {
+      it('should get something', () => {
+        expect(getSomething().toBe('Something'))
+      });
+    });
+  });
+});
+
+describe('foo2', function()) {
+  describe('bar2', function() {
+    describe('baz2', function() {
+      it('should get something', function() {
+        expect(getSomething().toBe('Something'))
+      });
+    });
+
+    describe('qux2', function() {
+      it('should get something', function() {
+        expect(getSomething().toBe('Something'))
+      });
+    });
+  });
+});
+
+```

src/rules/__tests__/max-nested-describe.test.ts

@@ -0,0 +1,135 @@
+import { TSESLint } from '@typescript-eslint/experimental-utils';
+import dedent from 'dedent';
+import resolveFrom from 'resolve-from';
+import rule from '../max-nested-describe';
+
+const ruleTester = new TSESLint.RuleTester({
+  parser: resolveFrom(require.resolve('eslint'), 'espree'),
+  parserOptions: {
+    ecmaVersion: 2017,
+  },
+});
+
+ruleTester.run('max-nested-describe', rule, {
+  valid: [
+    dedent`
+      describe('foo', () => {
+        describe('bar', () => {
+          it('hello', async () => {
+            expect('hello').toBe('hello');
+          });
+        });
+      });
+    `,
+    dedent`
+      describe('foo', () => {
+        describe('bar', () => {
+          it('hello', async () => {
+            expect('hello').toBe('hello');
+          });
+        });
+
+        describe('qux', () => {
+          it('something', async () => {
+            expect('something').toBe('something');
+          });
+        });
+      });
+    `,
+    dedent`
+      describe('foo', () => {
+        describe('bar', () => {
+          it('hello', async () => {
+            expect('hello').toBe('hello');
+          });
+        });
+      });
+
+      describe('foo', function() {
+        describe('bar', function() {
+          it('something', async () => {
+            expect('something').toBe('something');
+          });
+        });
+      });
+    `,
+    {
+      code: dedent`
+      describe('foo', () => {
+        describe('bar', () => {
+          describe('baz', () => {
+            it('something', async () => {
+              expect('something').toBe('something');
+            });
+          });
+        });
+      });
+    `,
+      options: [{ max: 3 }],
+    },
+  ],
+  invalid: [
+    {
+      code: dedent`
+        describe('foo', function() {
+          describe('bar', function () {
+            describe('baz', function () {
+              describe('qux', function () {
+                it('should get something', () => {
+                  expect(getSomething().toBe('Something'))
+                });
+              })
+            })
+          })
+        });
+      `,
+      errors: [
+        { messageId: 'exceededMaxDepth', line: 3, column: 5 },
+        { messageId: 'exceededMaxDepth', line: 4, column: 7 },
+      ],
+    },
+    {
+      code: dedent`
+        describe('foo', () => {
+          describe('bar', () => {
+            describe('baz', () => {
+              it('should get something', () => {
+                expect(getSomething().toBe('Something'))
+              });
+            });
+
+            describe('qux', function () {
+              it('should get something', () => {
+                expect(getSomething().toBe('Something'))
+              });
+            });
+          })
+        });
+      `,
+      errors: [
+        { messageId: 'exceededMaxDepth', line: 3, column: 5 },
+        { messageId: 'exceededMaxDepth', line: 9, column: 5 },
+      ],
+    },
+    {
+      code: dedent`
+        describe('foo', () => {
+          describe('bar', () => {
+            describe('baz', () => {
+              it('should get something', () => {
+                expect(getSomething().toBe('Something'))
+              });
+            });
+          });
+        });
+
+        describe('qux', () => {
+          it('should get something', () => {
+            expect(getSomething().toBe('Something'))
+          });
+        });
+      `,
+      errors: [{ messageId: 'exceededMaxDepth', line: 3, column: 5 }],
+    },
+  ],
+});

src/rules/max-nested-describe.ts

@@ -0,0 +1,79 @@
+import { TSESTree } from '@typescript-eslint/experimental-utils';
+import { createRule, isCallExpression, isDescribeCall } from './utils';
+
+export default 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: [
+      {
+        oneOf: [
+          {
+            type: 'integer',
+            minimum: 0,
+          },
+          {
+            type: 'object',
+            properties: {
+              max: {
+                type: 'integer',
+                minimum: 0,
+              },
+            },
+            additionalProperties: false,
+          },
+        ],
+      },
+    ],
+  },
+  defaultOptions: [{ max: 2 }],
+  create(context, [{ max }]) {
+    const describeCallbackStack: number[] = [];
+
+    function pushDescribeCallback(
+      node: TSESTree.ArrowFunctionExpression | TSESTree.FunctionExpression,
+    ) {
+      const { parent } = node;
+
+      if (!isCallExpression(parent) || !isDescribeCall(parent)) {
+        return;
+      }
+
+      describeCallbackStack.push(0);
+
+      if (describeCallbackStack.length > max) {
+        context.report({
+          node: parent,
+          messageId: 'exceededMaxDepth',
+          data: { depth: describeCallbackStack.length, max },
+        });
+      }
+    }
+
+    function popDescribeCallback(
+      node: TSESTree.ArrowFunctionExpression | TSESTree.FunctionExpression,
+    ) {
+      const { parent } = node;
+
+      if (isCallExpression(parent) && isDescribeCall(parent)) {
+        describeCallbackStack.pop();
+      }
+    }
+
+    return {
+      FunctionExpression: pushDescribeCallback,
+      'FunctionExpression:exit': popDescribeCallback,
+      ArrowFunctionExpression: pushDescribeCallback,
+      'ArrowFunctionExpression:exit': popDescribeCallback,
+    };
+  },
+});

src/rules/utils.ts

@@ -648,6 +648,16 @@ export type FunctionExpression =
   | TSESTree.ArrowFunctionExpression
   | TSESTree.FunctionExpression;
 
+export const isCallExpression = (
+  node: TSESTree.Node | undefined,
+): node is TSESTree.CallExpression => {
+  if (!node) {
+    return false;
+  }
+
+  return node.type === AST_NODE_TYPES.CallExpression;
+};
+
 export const isFunction = (node: TSESTree.Node): node is FunctionExpression =>
   node.type === AST_NODE_TYPES.FunctionExpression ||
   node.type === AST_NODE_TYPES.ArrowFunctionExpression;