Add allow option to no-setup-in-describe

Author: lo1tuma

documentation/rules/no-setup-in-describe.md

@@ -21,7 +21,11 @@ Any setup directly in a `describe` is run before all tests execute. This is unde
 1. When doing TDD in a large codebase, all setup is run for tests that don't have `only` set. This can add a substantial amount of time per iteration.
 2. If global state is altered by the setup of another describe block, your test may be affected.
 
-This rule reports all function calls and use of the dot operator (due to getters and setters) directly in describe blocks. An exception is made for Mocha's suite configuration methods, like `this.timeout();`, which do not represent setup logic.
+For this rule, "setup" means code that executes immediately while the suite callback itself is evaluated. That includes work done directly in the suite body before any tests run, even when the code looks harmless.
+
+In practice, this rule reports direct function calls and direct property access in suite bodies. Property access is included because getters can execute code. Exceptions are made for Mocha's structural calls (`describe`, `it`, hooks, and their supported variants) and Mocha suite configuration calls such as `this.timeout();`, `it(...).timeout();`, or `before(...).timeout();`.
+
+This rule does not make special exceptions for JavaScript builtins. For example, `Symbol()` is still a direct function call in the suite body and is reported by default.
 
 If you're using [dynamically generated tests](https://mochajs.org/#dynamically-generating-tests), you should disable this rule.
 
@@ -75,3 +79,40 @@ describe('something', function () {
     it('should take awhile', function () {});
 });
 ```
+
+## Options
+
+This rule accepts one optional object:
+
+- `allow`: an array of call names that should be allowed directly in suite bodies
+
+Entries may be written with or without `()`. Dotted names are supported.
+
+```json
+{
+    "rules": {
+        "mocha/no-setup-in-describe": ["error", {
+            "allow": ["Symbol", "Object.freeze"]
+        }]
+    }
+}
+```
+
+With this option, the following patterns would not be considered problems:
+
+```js
+describe('something', function () {
+    const token = Symbol('id');
+    Object.freeze(sharedFixture);
+    it('should work', function () {});
+});
+```
+
+The `allow` option only applies to calls. It does not allow bare property access:
+
+```js
+describe('something', function () {
+    Object.freeze;
+    it('should work', function () {});
+});
+```

source/rules/no-setup-in-describe.test.ts

@@ -1,4 +1,5 @@
-import { RuleTester } from 'eslint';
+import { type Rule, RuleTester } from 'eslint';
+import assert from 'node:assert';
 import { noSetupInDescribeRule } from './no-setup-in-describe.js';
 
 const ruleTester = new RuleTester({ languageOptions: { sourceType: 'script' } });
@@ -105,7 +106,23 @@ ruleTester.run('no-setup-in-describe', noSetupInDescribeRule, {
             code: 'describe("", function () { const bar = () => { a.b = "c"; }; it(); })',
             languageOptions: { ecmaVersion: 2015 }
         },
-        'describe("", function () { var bar = function () { a.b = "c"; }; it(); })'
+        'describe("", function () { var bar = function () { a.b = "c"; }; it(); })',
+        {
+            code: 'describe("", function () { const token = Symbol("bar"); it(); })',
+            options: [{ allow: ['Symbol'] }]
+        },
+        {
+            code: 'describe("", function () { const token = Symbol("bar"); it(); })',
+            options: [{ allow: ['Symbol()'] }]
+        },
+        {
+            code: 'describe("", function () { Object.freeze({}); it(); })',
+            options: [{ allow: ['Object.freeze'] }]
+        },
+        {
+            code: 'describe("", function () { Object.freeze({}); it(); })',
+            options: [{ allow: ['Object.freeze()'] }]
+        }
     ],
 
     invalid: [
@@ -282,6 +299,56 @@ ruleTester.run('no-setup-in-describe', noSetupInDescribeRule, {
                     column: 28
                 }
             ]
+        },
+        {
+            code: 'describe("", function () { const token = Symbol("bar"); it(); })',
+            errors: [
+                {
+                    message: 'Unexpected function call in describe block.',
+                    line: 1,
+                    column: 42
+                }
+            ]
+        },
+        {
+            code: 'describe("", function () { const token = Symbol("bar"); helper(); it(); })',
+            options: [{ allow: ['Symbol'] }],
+            errors: [
+                {
+                    message: 'Unexpected function call in describe block.',
+                    line: 1,
+                    column: 57
+                }
+            ]
+        },
+        {
+            code: 'describe("", function () { Object.freeze; it(); })',
+            options: [{ allow: ['Object.freeze'] }],
+            errors: [
+                {
+                    message: memberExpressionError,
+                    line: 1,
+                    column: 28
+                }
+            ]
         }
     ]
 });
+
+describe('no-setup-in-describe create()', function () {
+    it('normalizes non-string allow entries when invoked directly', function () {
+        noSetupInDescribeRule.create({
+            id: 'no-setup-in-describe',
+            options: [{ allow: [42] }],
+            settings: {},
+            sourceCode: {
+                ast: { body: [] },
+                scopeManager: {
+                    globalScope: null
+                }
+            }
+        } as unknown as Rule.RuleContext);
+
+        assert.ok(true);
+    });
+});

source/rules/no-setup-in-describe.ts

@@ -1,10 +1,30 @@
 import type { Rule } from 'eslint';
+import { extractMemberExpressionPath, isConstantPath } from '../ast/member-expression.js';
 import { createMochaVisitors } from '../ast/mocha-visitors.js';
 import type { CallExpression, MemberExpression } from '../ast/node-types.js';
 import { isSuiteConfigCall } from '../mocha/config-call.js';
+import { reformatLastPathSegmentWithCallExpressions } from '../mocha/name-details.js';
+import { convertNameToPathArray, isSamePath } from '../mocha/path.js';
+import { getRuleOption, type InferSchemaOption, type RuleSchema } from '../rule-options.js';
 
 const FUNCTION = 1;
 const DESCRIBE = 2;
+const optionSchema = {
+    type: 'object',
+    properties: {
+        allow: {
+            type: 'array',
+            items: {
+                type: 'string'
+            }
+        }
+    },
+    additionalProperties: false
+} as const satisfies RuleSchema;
+
+type Option = InferSchemaOption<typeof optionSchema>;
+type ResolvedOption = Option & { allow: string[]; };
+const defaultOption: ResolvedOption = { allow: [] };
 
 function isNestedInDescribeBlock(nesting: readonly number[]): boolean {
     return (
@@ -30,6 +50,25 @@ function reportMemberExpression(
     });
 }
 
+function ensureEndsWithParens(value: unknown): string {
+    if (typeof value !== 'string') {
+        return '';
+    }
+
+    if (value.endsWith('()')) {
+        return value;
+    }
+
+    return `${value}()`;
+}
+
+function normalizeAllowedCall(value: unknown): readonly string[] {
+    const path = convertNameToPathArray(ensureEndsWithParens(value));
+    const [lastPathSegment] = path.slice(-1);
+
+    return [...path.slice(0, -1), ensureEndsWithParens(lastPathSegment)];
+}
+
 export const noSetupInDescribeRule: Readonly<Rule.RuleModule> = {
     meta: {
         type: 'suggestion',
@@ -38,19 +77,39 @@ export const noSetupInDescribeRule: Readonly<Rule.RuleModule> = {
             description: 'Disallow setup in describe blocks',
             url: 'https://github.com/lo1tuma/eslint-plugin-mocha/blob/main/documentation/rules/no-setup-in-describe.md'
         },
+        defaultOptions: [defaultOption],
         messages: {
             unexpectedFunctionCall: 'Unexpected function call in describe block.',
             unexpectedMemberExpression:
                 'Unexpected member expression in describe block. Member expressions may call functions via getters.'
         },
-        schema: []
+        schema: [optionSchema]
     },
     create(context) {
+        const { allow } = getRuleOption<ResolvedOption>(context);
+        const allowedCalls = allow.map(normalizeAllowedCall);
         const nesting: number[] = [];
         const suiteNodes = new WeakSet();
 
+        function isAllowedCall(node: Readonly<CallExpression>): boolean {
+            const calleeWithParent = { ...node.callee, parent: node };
+            const path = reformatLastPathSegmentWithCallExpressions(
+                extractMemberExpressionPath(context.sourceCode, calleeWithParent),
+                1
+            );
+
+            return isConstantPath(path) &&
+                allowedCalls.some((allowedCall) => {
+                    return isSamePath(path, allowedCall);
+                });
+        }
+
+        function isAllowedCallMemberExpression(node: Readonly<MemberExpression>): boolean {
+            return node.parent.type === 'CallExpression' && node.parent.callee === node && isAllowedCall(node.parent);
+        }
+
         function handleCallExpressionInDescribe(node: Readonly<CallExpression>): void {
-            if (isNestedInDescribeBlock(nesting) && !isSuiteConfigCall(node)) {
+            if (isNestedInDescribeBlock(nesting) && !isSuiteConfigCall(node) && !isAllowedCall(node)) {
                 reportCallExpression(context, node);
             }
         }
@@ -76,7 +135,8 @@ export const noSetupInDescribeRule: Readonly<Rule.RuleModule> = {
                 if (
                     !suiteNodes.has(node.parent) &&
                     isNestedInDescribeBlock(nesting) &&
-                    !isSuiteConfigCall(node.parent)
+                    !isSuiteConfigCall(node.parent) &&
+                    !isAllowedCallMemberExpression(node)
                 ) {
                     reportMemberExpression(context, node);
                 }