Add rule to suggest using built-in locators (prefer-native-locators)

README.md

@@ -155,7 +155,8 @@ messages will use the default message defined by the plugin.
 ## Rules
 
 ✅ Set in the `recommended` configuration\
-🔧 Automatically fixable by the [`--fix`](https://eslint.org/docs/latest/user-guide/command-line-interface#--fix)
+🔧 Automatically fixable by the
+[`--fix`](https://eslint.org/docs/latest/user-guide/command-line-interface#--fix)
 CLI option\
 💡 Manually fixable by
 [editor suggestions](https://eslint.org/docs/latest/developer-guide/working-with-rules#providing-suggestions)
@@ -194,6 +195,7 @@ CLI option\
 | [prefer-hooks-in-order](https://github.com/playwright-community/eslint-plugin-playwright/tree/main/docs/rules/prefer-hooks-in-order.md)             | Prefer having hooks in a consistent order                          |     |     |     |
 | [prefer-hooks-on-top](https://github.com/playwright-community/eslint-plugin-playwright/tree/main/docs/rules/prefer-hooks-on-top.md)                 | Suggest having hooks before any test cases                         |     |     |     |
 | [prefer-lowercase-title](https://github.com/playwright-community/eslint-plugin-playwright/tree/main/docs/rules/prefer-lowercase-title.md)           | Enforce lowercase test names                                       |     | 🔧  |     |
+| [prefer-native-locators](https://github.com/playwright-community/eslint-plugin-playwright/tree/main/docs/rules/prefer-native-locators.md)           | Suggest built-in locators over `page.locator()`                    |     | 🔧  |     |
 | [prefer-strict-equal](https://github.com/playwright-community/eslint-plugin-playwright/tree/main/docs/rules/prefer-strict-equal.md)                 | Suggest using `toStrictEqual()`                                    |     |     | 💡  |
 | [prefer-to-be](https://github.com/playwright-community/eslint-plugin-playwright/tree/main/docs/rules/prefer-to-be.md)                               | Suggest using `toBe()`                                             |     | 🔧  |     |
 | [prefer-to-contain](https://github.com/playwright-community/eslint-plugin-playwright/tree/main/docs/rules/prefer-to-contain.md)                     | Suggest using `toContain()`                                        |     | 🔧  |     |

docs/rules/prefer-native-locators.md

@@ -0,0 +1,34 @@
+# Suggest using native Playwright locators (`prefer-native-locators`)
+
+Playwright has built-in locators for common query selectors such as finding
+elements by placeholder text, ARIA role, accessible name, and more. This rule
+suggests using these native locators instead of using `page.locator()` with an
+equivalent selector.
+
+In some cases this can be more robust too, such as finding elements by ARIA role
+or accessible name, because some elements have implicit roles, and there are
+multiple ways to specify accessible names.
+
+## Rule details
+
+Examples of **incorrect** code for this rule:
+
+```javascript
+page.locator('[aria-label="View more"]')
+page.locator('[role="button"]')
+page.locator('[placeholder="Enter some text..."]')
+page.locator('[alt="Playwright logo"]')
+page.locator('[title="Additional context"]')
+page.locator('[data-testid="password-input"]')
+```
+
+Examples of **correct** code for this rule:
+
+```javascript
+page.getByLabel('View more')
+page.getByRole('Button')
+page.getByPlaceholder('Enter some text...')
+page.getByAltText('Playwright logo')
+page.getByTestId('password-input')
+page.getByTitle('Additional context')
+```

src/index.ts

@@ -31,6 +31,7 @@ import preferEqualityMatcher from './rules/prefer-equality-matcher'
 import preferHooksInOrder from './rules/prefer-hooks-in-order'
 import preferHooksOnTop from './rules/prefer-hooks-on-top'
 import preferLowercaseTitle from './rules/prefer-lowercase-title'
+import preferNativeLocators from './rules/prefer-native-locators'
 import preferStrictEqual from './rules/prefer-strict-equal'
 import preferToBe from './rules/prefer-to-be'
 import preferToContain from './rules/prefer-to-contain'
@@ -81,6 +82,7 @@ const index = {
     'prefer-hooks-in-order': preferHooksInOrder,
     'prefer-hooks-on-top': preferHooksOnTop,
     'prefer-lowercase-title': preferLowercaseTitle,
+    'prefer-native-locators': preferNativeLocators,
     'prefer-strict-equal': preferStrictEqual,
     'prefer-to-be': preferToBe,
     'prefer-to-contain': preferToContain,

src/rules/prefer-native-locators.test.ts

@@ -0,0 +1,98 @@
+import { runRuleTester } from '../utils/rule-tester'
+import rule from './prefer-native-locators'
+
+runRuleTester('prefer-native-locators', rule, {
+  invalid: [
+    {
+      code: `page.locator('[aria-label="View more"]')`,
+      errors: [{ column: 1, line: 1, messageId: 'unexpectedLabelQuery' }],
+      output: 'page.getByLabel("View more")',
+    },
+    {
+      code: `page.locator('[role="button"]')`,
+      errors: [{ column: 1, line: 1, messageId: 'unexpectedRoleQuery' }],
+      output: 'page.getByRole("button")',
+    },
+    {
+      code: `page.locator('[placeholder="Enter some text..."]')`,
+      errors: [{ column: 1, line: 1, messageId: 'unexpectedPlaceholderQuery' }],
+      output: 'page.getByPlaceholder("Enter some text...")',
+    },
+    {
+      code: `page.locator('[alt="Playwright logo"]')`,
+      errors: [{ column: 1, line: 1, messageId: 'unexpectedAltTextQuery' }],
+      output: 'page.getByAltText("Playwright logo")',
+    },
+    {
+      code: `page.locator('[title="Additional context"]')`,
+      errors: [{ column: 1, line: 1, messageId: 'unexpectedTitleQuery' }],
+      output: 'page.getByTitle("Additional context")',
+    },
+    {
+      code: `page.locator('[data-testid="password-input"]')`,
+      errors: [{ column: 1, line: 1, messageId: 'unexpectedTestIdQuery' }],
+      output: 'page.getByTestId("password-input")',
+    },
+    {
+      code: `page.locator('[data-custom-testid="password-input"]')`,
+      errors: [{ column: 1, line: 1, messageId: 'unexpectedTestIdQuery' }],
+      options: [{ testIdAttribute: 'data-custom-testid' }],
+      output: 'page.getByTestId("password-input")',
+    },
+    // Works when locators are chained
+    {
+      code: `this.page.locator('[role="heading"]').first()`,
+      errors: [{ column: 1, line: 1, messageId: 'unexpectedRoleQuery' }],
+      output: 'this.page.getByRole("heading").first()',
+    },
+    // Works when used inside an assertion
+    {
+      code: `await expect(page.locator('[role="alert"]')).toBeVisible()`,
+      errors: [{ column: 14, line: 1, messageId: 'unexpectedRoleQuery' }],
+      output: 'await expect(page.getByRole("alert")).toBeVisible()',
+    },
+    {
+      code: `await expect(page.locator('[data-testid="top"]')).toContainText(firstRule)`,
+      errors: [{ column: 14, line: 1, messageId: 'unexpectedTestIdQuery' }],
+      output: 'await expect(page.getByTestId("top")).toContainText(firstRule)',
+    },
+    // Works when used as part of an action
+    {
+      code: `await page.locator('[placeholder="New password"]').click()`,
+      errors: [{ column: 7, line: 1, messageId: 'unexpectedPlaceholderQuery' }],
+      output: 'await page.getByPlaceholder("New password").click()',
+    },
+    // Works when it is not page.locator
+    {
+      code: `this.locator('[aria-label="View more"]')`,
+      errors: [{ column: 1, line: 1, messageId: 'unexpectedLabelQuery' }],
+      output: 'this.getByLabel("View more")',
+    },
+  ],
+  valid: [
+    { code: 'page.getByLabel("View more")' },
+    { code: 'page.getByRole("button")' },
+    { code: 'page.getByPlaceholder("Enter some text...")' },
+    { code: 'page.getByAltText("Playwright logo")' },
+    { code: 'page.getByTestId("password-input")' },
+    { code: 'page.getByTitle("Additional context")' },
+    {
+      code: `page.locator('[complex-query] > [aria-label="View more"]')`,
+    },
+    {
+      code: `page.locator('[complex-query] > [role="button"]')`,
+    },
+    {
+      code: `page.locator('[complex-query] > [placeholder="Enter some text..."]')`,
+    },
+    {
+      code: `page.locator('[complex-query] > [alt="Playwright logo"]')`,
+    },
+    {
+      code: `page.locator('[complex-query] > [data-testid="password-input"]')`,
+    },
+    {
+      code: `page.locator('[complex-query] > [title="Additional context"]')`,
+    },
+  ],
+})

src/rules/prefer-native-locators.ts

@@ -0,0 +1,139 @@
+import { getStringValue, isPageMethod } from '../utils/ast'
+import { createRule } from '../utils/createRule'
+
+export default createRule({
+  create(context) {
+    return {
+      CallExpression(node) {
+        const { testIdAttribute } = {
+          testIdAttribute: 'data-testid',
+          ...((context.options?.[0] as Record<string, unknown>) ?? {}),
+        }
+
+        if (node.callee.type !== 'MemberExpression') return
+        const method = getStringValue(node.callee.property)
+        const query = getStringValue(node.arguments[0])
+        const isLocator = isPageMethod(node, 'locator') || method === 'locator'
+        if (!isLocator) return
+
+        // If it's something like `page.locator`, just replace the `.locator` part
+        const start =
+          node.callee.type === 'MemberExpression'
+            ? node.callee.property.range![0]
+            : node.range![0]
+        const end = node.range![1]
+        const rangeToReplace: [number, number] = [start, end]
+
+        const ariaLabelPattern = /^\[aria-label=['"](.+?)['"]\]$/
+        const labelMatch = query.match(ariaLabelPattern)
+        if (labelMatch) {
+          context.report({
+            fix(fixer) {
+              const newText = `getByLabel("${labelMatch[1]}")`
+              return fixer.replaceTextRange(rangeToReplace, newText)
+            },
+            messageId: 'unexpectedLabelQuery',
+            node,
+          })
+        }
+
+        const rolePattern = /^\[role=['"](.+?)['"]\]$/
+        const roleMatch = query.match(rolePattern)
+        if (roleMatch) {
+          context.report({
+            fix(fixer) {
+              const newText = `getByRole("${roleMatch[1]}")`
+              return fixer.replaceTextRange(rangeToReplace, newText)
+            },
+            messageId: 'unexpectedRoleQuery',
+            node,
+          })
+        }
+
+        const placeholderPattern = /^\[placeholder=['"](.+?)['"]\]$/
+        const placeholderMatch = query.match(placeholderPattern)
+        if (placeholderMatch) {
+          context.report({
+            fix(fixer) {
+              const newText = `getByPlaceholder("${placeholderMatch[1]}")`
+              return fixer.replaceTextRange(rangeToReplace, newText)
+            },
+            messageId: 'unexpectedPlaceholderQuery',
+            node,
+          })
+        }
+
+        const altTextPattern = /^\[alt=['"](.+?)['"]\]$/
+        const altTextMatch = query.match(altTextPattern)
+        if (altTextMatch) {
+          context.report({
+            fix(fixer) {
+              const newText = `getByAltText("${altTextMatch[1]}")`
+              return fixer.replaceTextRange(rangeToReplace, newText)
+            },
+            messageId: 'unexpectedAltTextQuery',
+            node,
+          })
+        }
+
+        const titlePattern = /^\[title=['"](.+?)['"]\]$/
+        const titleMatch = query.match(titlePattern)
+        if (titleMatch) {
+          context.report({
+            fix(fixer) {
+              const newText = `getByTitle("${titleMatch[1]}")`
+              return fixer.replaceTextRange(rangeToReplace, newText)
+            },
+            messageId: 'unexpectedTitleQuery',
+            node,
+          })
+        }
+
+        const testIdPattern = new RegExp(
+          `^\\[${testIdAttribute}=['"](.+?)['"]\\]`,
+        )
+        const testIdMatch = query.match(testIdPattern)
+        if (testIdMatch) {
+          context.report({
+            fix(fixer) {
+              const newText = `getByTestId("${testIdMatch[1]}")`
+              return fixer.replaceTextRange(rangeToReplace, newText)
+            },
+            messageId: 'unexpectedTestIdQuery',
+            node,
+          })
+        }
+      },
+    }
+  },
+  meta: {
+    docs: {
+      category: 'Best Practices',
+      description: 'Prefer native locator functions',
+      recommended: false,
+      url: 'https://github.com/playwright-community/eslint-plugin-playwright/tree/main/docs/rules/prefer-native-locators.md',
+    },
+    fixable: 'code',
+    messages: {
+      unexpectedAltTextQuery: 'Use .getByAltText() instead',
+      unexpectedLabelQuery: 'Use .getByLabel() instead',
+      unexpectedPlaceholderQuery: 'Use .getByPlaceholder() instead',
+      unexpectedRoleQuery: 'Use .getByRole() instead',
+      unexpectedTestIdQuery: 'Use .getByTestId() instead',
+      unexpectedTitleQuery: 'Use .getByTitle() instead',
+    },
+    schema: [
+      {
+        additionalProperties: false,
+        properties: {
+          testIdAttribute: {
+            default: 'data-testid',
+            type: 'string',
+          },
+        },
+        type: 'object',
+      },
+    ],
+    type: 'suggestion',
+  },
+})