feat: Add allowed option for no-raw-locators (#189)

* Docs and tests * Update rule
playwright-community · Jan 1, 2024 · ae52f21 · ae52f21
1 parent 5bc9a33
commit ae52f21
Show file tree

Hide file tree

Showing 3 changed files with 128 additions and 1 deletion.
diff --git a/docs/rules/no-raw-locators.md b/docs/rules/no-raw-locators.md
@@ -24,3 +24,37 @@ await page.getByRole('button', {
   name: 'Submit',
 });
 ```
+
+## Options
+
+```json
+{
+  "playwright/no-raw-locators": [
+    "error",
+    {
+      "allowed": ["iframe", "[aria-busy='false']"]
+    }
+  ]
+}
+```
+
+### `allowed`
+
+An array of raw locators that are allowed. This helps for locators such as
+`iframe` which does not have a ARIA role that you can select using `getByRole`.
+
+By default, no raw locators are allowed (the equivalent of `{ "ignore": [] }`).
+
+Example of **incorrect** code for the `{ "allowed": ["[aria-busy=false]"] }`
+option:
+
+```javascript
+page.getByRole('navigation').and(page.locator('iframe'));
+```
+
+Example of **correct** code for the `{ "allowed": ["[aria-busy=false]"] }`
+option:
+
+```javascript
+page.getByRole('navigation').and(page.locator('[aria-busy="false"]'));
+```
diff --git a/src/rules/no-raw-locators.ts b/src/rules/no-raw-locators.ts
@@ -1,14 +1,31 @@
 import { Rule } from 'eslint';
 import { getStringValue, isPageMethod } from '../utils/ast';
 
+/** Normalize data attribute locators */
+function normalize(str: string) {
+  const match = /\[([^=]+?)=['"]?([^'"]+?)['"]?\]/.exec(str);
+  return match ? `[${match[1]}=${match[2]}]` : str;
+}
+
 export default {
   create(context) {
+    const options = {
+      allowed: [] as string[],
+      ...((context.options?.[0] as Record<string, unknown>) ?? {}),
+    };
+
+    function isAllowed(arg: string) {
+      return options.allowed.some((a) => normalize(a) === normalize(arg));
+    }
+
     return {
       CallExpression(node) {
         if (node.callee.type !== 'MemberExpression') return;
         const method = getStringValue(node.callee.property);
+        const arg = getStringValue(node.arguments[0]);
+        const isLocator = isPageMethod(node, 'locator') || method === 'locator';
 
-        if (isPageMethod(node, 'locator') || method === 'locator') {
+        if (isLocator && !isAllowed(arg)) {
           context.report({ messageId: 'noRawLocator', node });
         }
       },
@@ -25,6 +42,18 @@ export default {
       noRawLocator:
         'Usage of raw locator detected. Use methods like .getByRole() or .getByText() instead of raw locators.',
     },
+    schema: [
+      {
+        additionalProperties: false,
+        properties: {
+          allowed: {
+            items: { type: 'string' },
+            type: 'array',
+          },
+        },
+        type: 'object',
+      },
+    ],
     type: 'suggestion',
   },
 } as Rule.RuleModule;
diff --git a/test/spec/no-raw-locators.spec.ts b/test/spec/no-raw-locators.spec.ts
@@ -37,6 +37,28 @@ runRuleTester('no-raw-locators', rule, {
       ),
       errors: [{ column: 77, endColumn: 100, line: 1, messageId }],
     },
+
+    // Allowed
+    {
+      code: test('await page.locator("[aria-busy=false]")'),
+      errors: [{ column: 34, endColumn: 67, line: 1, messageId }],
+      options: [{ allowed: ['iframe'] }],
+    },
+    {
+      code: test(`await page.locator("[aria-busy=false]")`),
+      errors: [{ column: 34, endColumn: 67, line: 1, messageId }],
+      options: [{ allowed: ['iframe'] }],
+    },
+    {
+      code: test(`await page.locator("[aria-busy=false]")`),
+      errors: [{ column: 34, endColumn: 67, line: 1, messageId }],
+      options: [{ allowed: [`[aria-busy=true]`] }],
+    },
+    {
+      code: test(`await page.locator("[aria-busy='false']")`),
+      errors: [{ column: 34, endColumn: 69, line: 1, messageId }],
+      options: [{ allowed: [`[aria-busy=true]`] }],
+    },
   ],
   valid: [
     test('await page.click()'),
@@ -61,5 +83,47 @@ runRuleTester('no-raw-locators', rule, {
 
     // bare calls
     test('() => page.locator'),
+
+    // Allowed
+    {
+      code: test('await page.locator("iframe")'),
+      options: [{ allowed: ['iframe'] }],
+    },
+    {
+      code: test(`await page.locator("[aria-busy=false]")`),
+      options: [{ allowed: [`[aria-busy=false]`] }],
+    },
+    {
+      code: test(`await page.locator("[aria-busy='false']")`),
+      options: [{ allowed: [`[aria-busy=false]`] }],
+    },
+    {
+      code: test(`await page.locator('[aria-busy="false"]')`),
+      options: [{ allowed: [`[aria-busy=false]`] }],
+    },
+    {
+      code: test(`await page.locator("[aria-busy=false]")`),
+      options: [{ allowed: [`[aria-busy='false']`] }],
+    },
+    {
+      code: test(`await page.locator('[aria-busy=false]')`),
+      options: [{ allowed: [`[aria-busy="false"]`] }],
+    },
+    {
+      code: test(`await page.locator("[aria-busy='false']")`),
+      options: [{ allowed: [`[aria-busy='false']`] }],
+    },
+    {
+      code: test(`await page.locator('[aria-busy="false"]')`),
+      options: [{ allowed: [`[aria-busy="false"]`] }],
+    },
+    {
+      code: test(`await page.locator("[aria-busy='false']")`),
+      options: [{ allowed: [`[aria-busy="false"]`] }],
+    },
+    {
+      code: test(`await page.locator('[aria-busy="false"]')`),
+      options: [{ allowed: [`[aria-busy='false']`] }],
+    },
   ],
 });