feat: Allow additional assert function names with expect-expect (#155)

Author: sarayourfriend

README.md

@@ -47,6 +47,24 @@ This plugin bundles two configurations to work with both `@playwright/test` or
 }
 ```
 
+## Global Settings
+
+The plugin reads global settings from your ESLint configuration's shared data under the `playwright` key. It supports the following settings:
+
+- `additionalAssertFunctionNames`: an array of function names to treat as assertion functions for the case of rules like `expect-expect`, which enforces the presence of at least one assertion per test case. This allows such rules to recognise custom assertion functions as valid assertions. The global setting applies to all modules. The [`expect-expect` rule accepts an option by the same name](./rules/expect-expect.md#additionalassertfunctionnames) to enable per-module configuration (.e.g, for module-specific custom assert functions).
+
+You can configure these settings like so:
+
+```json
+{
+    "settings": {
+        "playwright": {
+            "additionalAssertFunctionNames": ["assertCustomCondition"]
+        }
+    }
+}
+```
+
 ## List of Supported Rules
 
 ✔: Enabled in the recommended configuration.\

docs/rules/expect-expect.md

@@ -27,3 +27,42 @@ test('should work with callbacks/async', async () => {
   });
 });
 ```
+
+## Options
+
+```json
+{
+  "playwright/expect-expect": [
+    "error",
+    {
+      "additionalAssertFunctionNames": ["assertCustomCondition"]
+    }
+  ]
+}
+```
+
+### `additionalAssertFunctionNames`
+
+An array of function names to treat as assertion functions. Only standalone functions are supported. Configure globally acceptable assert function names using [the global setting](../global-settings.md). You can also customize assert function names per-file. For example: 
+
+```ts
+/* eslint playwright/expect-expect: ["error", { "additionalAssertFunctionNames": ["assertScrolledToBottom"] }] */
+
+function assertScrolledToBottom(page) {
+  // ...
+}
+
+describe('scrolling', () => {
+  test('button click', async ({ page }) => {
+    // ...
+    await assertScrolledToBottom(page)
+  })
+
+  test('another way to scroll', async ({ page }) => {
+    // ...
+    await assertScrolledToBottom(page)
+  })
+})
+```
+
+The rule option and the global setting are merged. On a file level, both are considered.

src/rules/expect-expect.ts

@@ -1,10 +1,24 @@
 import { Rule } from 'eslint';
 import * as ESTree from 'estree';
-import { isExpectCall, isTest } from '../utils/ast';
+import { isExpectCall, isIdentifier, isTest } from '../utils/ast';
+import { getAdditionalAssertFunctionNames } from '../utils/misc';
+
+function isAssertionCall(
+  node: ESTree.CallExpression,
+  additionalAssertFunctionNames: string[]
+) {
+  return (
+    isExpectCall(node) ||
+    additionalAssertFunctionNames.find((name) =>
+      isIdentifier(node.callee, name)
+    )
+  );
+}
 
 export default {
   create(context) {
     const unchecked: ESTree.CallExpression[] = [];
+    const additionalAssertFunctionNames = getAdditionalAssertFunctionNames(context)
 
     function checkExpressions(nodes: ESTree.Node[]) {
       for (const node of nodes) {
@@ -22,7 +36,7 @@ export default {
       CallExpression(node) {
         if (isTest(node, ['fixme', 'only', 'skip'])) {
           unchecked.push(node);
-        } else if (isExpectCall(node)) {
+        } else if (isAssertionCall(node, additionalAssertFunctionNames)) {
           checkExpressions(context.getAncestors());
         }
       },
@@ -43,6 +57,18 @@ export default {
     messages: {
       noAssertions: 'Test has no assertions',
     },
+    schema: [
+      {
+        additionalProperties: false,
+        properties: {
+          additionalAssertFunctionNames: {
+            items: [{ type: 'string' }],
+            type: 'array',
+          },
+        },
+        type: 'object',
+      },
+    ],
     type: 'problem',
   },
 } as Rule.RuleModule;

src/utils/misc.ts

@@ -1,4 +1,19 @@
+import { Rule } from 'eslint';
+
+import { Settings } from './types';
+
 export const getAmountData = (amount: number) => ({
   amount: amount.toString(),
   s: amount === 1 ? '' : 's',
 });
+
+interface AssertFunctionNamesOptions {
+  additionalAssertFunctionNames?: string[];
+};
+
+export function getAdditionalAssertFunctionNames(context: Rule.RuleContext): string[] {
+  const globalSettings = (context.settings as Settings).playwright?.additionalAssertFunctionNames ?? [] as string[]
+  const ruleSettings = (context.options[0] as AssertFunctionNamesOptions | undefined)?.additionalAssertFunctionNames ?? [] as string[]
+
+  return [...globalSettings, ...ruleSettings]
+}

src/utils/types.ts

@@ -12,3 +12,9 @@ export type TypedNodeWithParent<T extends ESTree.Node['type']> = Extract<
 export type KnownCallExpression = ESTree.CallExpression & {
   callee: ESTree.MemberExpression;
 };
+
+export interface Settings {
+  playwright?: {
+    additionalAssertFunctionNames?: readonly string[]
+  }
+}

test/spec/expect-expect.spec.ts

@@ -12,6 +12,49 @@ runRuleTester('expect-expect', rule, {
       code: 'test.skip("should fail", () => {});',
       errors: [{ messageId: 'noAssertions' }],
     },
+    {
+      code: dedent`
+        test('should fail', async ({ page }) => {
+          await assertCustomCondition(page)
+        })
+      `,
+      errors: [{ messageId: 'noAssertions' }],
+    },
+    {
+      name: 'Global settings no false positives',
+      code: dedent`
+        test('should fail', async ({ page }) => {
+          await assertCustomCondition(page)
+        })
+      `,
+      errors: [{ messageId: 'noAssertions' }],
+      settings: {
+        playwright: { additionalAssertFunctionNames: ['wayComplexCustomCondition'] },
+      },
+    },
+    {
+      name: 'Rule settings no false positives',
+      code: dedent`
+        test('should fail', async ({ page }) => {
+          await assertCustomCondition(page)
+        })
+      `,
+      errors: [{ messageId: 'noAssertions' }],
+      options: [{ additionalAssertFunctionNames: ['wayComplexCustomCondition'] }],
+    },
+    {
+      name: 'Global settings no false positives',
+      code: dedent`
+        test('should fail', async ({ page }) => {
+          await assertCustomCondition(page)
+        })
+      `,
+      errors: [{ messageId: 'noAssertions' }],
+      settings: {
+        playwright: { additionalAssertFunctionNames: ['wayComplexGlobalCustomCondition'] },
+      },
+      options: [{ additionalAssertFunctionNames: ['wayComplexRuleCustomCondition'] }],
+    },
   ],
   valid: [
     'foo();',
@@ -36,5 +79,41 @@ runRuleTester('expect-expect', rule, {
         });
       `,
     },
+    {
+      name: 'Global settings only',
+      code: dedent`
+        test('should fail', async ({ page }) => {
+          await assertCustomCondition(page)
+        })
+      `,
+      settings: {
+        playwright: { additionalAssertFunctionNames: ['assertCustomCondition'] }
+      }
+    },
+    {
+      name: 'Rule settings only',
+      code: dedent`
+        test('should fail', async ({ page }) => {
+          await assertCustomCondition(page)
+        })
+      `,
+      options: [{ additionalAssertFunctionNames: ['assertCustomCondition'] }],
+    },
+    {
+      name: 'Global and rule settings combine rather than override',
+      code: dedent`
+        test('should fail', async ({ page }) => {
+          await assertCustomCondition(page)
+        })
+
+        test('complex failure', async ({ page }) => {
+          await wayComplexCustomCondition(page)
+        })
+      `,
+      settings: {
+        playwright: { additionalAssertFunctionNames: ['assertCustomCondition'] },
+      },
+      options: [{ additionalAssertFunctionNames: ['wayComplexCustomCondition'] }],
+    },
   ],
 });