Merge branch 'main' into no-slow-tests

Author: mskelton

.eslintignore

@@ -9,7 +9,7 @@ jobs:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        node-version: [16.x, 18.x, 20.x]
+        node-version: [18.x, 20.x, 22.x]
     steps:
       - name: Setup Node.js ${{ matrix.node-version }}
         uses: mskelton/setup-pnpm@v2

.eslintrc

@@ -28,14 +28,11 @@ pnpm add -D eslint-plugin-playwright
 
 ## Usage
 
-This plugin bundles two configurations to work with both `@playwright/test` or
-`jest-playwright`. The recommended setup is to use the `files` field to target
-only Playwright test files. In the examples below, this is done by targeting
-files in the `tests` directory and only applying the Playwright rules to those
-files. In your project, you may need to change the `files` field to match your
-Playwright test file patterns.
-
-### With [Playwright test runner](https://playwright.dev/docs/writing-tests)
+The recommended setup is to use the `files` field to target only Playwright test
+files. In the examples below, this is done by targeting files in the `tests`
+directory and only applying the Playwright rules to those files. In your
+project, you may need to change the `files` field to match your Playwright test
+file patterns.
 
 [Flat config](https://eslint.org/docs/latest/use/configure/configuration-files-new)
 (**eslint.config.js**)
@@ -47,10 +44,8 @@ export default [
   {
     ...playwright.configs['flat/recommended'],
     files: ['tests/**'],
-  },
-  {
-    files: ['tests/**'],
     rules: {
+      ...playwright.configs['flat/recommended'].rules,
       // Customize Playwright rules
       // ...
     },
@@ -72,45 +67,6 @@ export default [
 }
 ```
 
-### With [Jest Playwright](https://github.com/playwright-community/jest-playwright)
-
-[Flat config](https://eslint.org/docs/latest/use/configure/configuration-files-new)
-(**eslint.config.js**)
-
-```javascript
-import playwright from 'eslint-plugin-playwright'
-import jest from 'eslint-plugin-jest'
-
-export default [
-  {
-    ...playwright.configs['flat/jest-playwright'],
-    files: ['tests/**'],
-  },
-  {
-    files: ['tests/**'],
-    plugins: { jest },
-    rules: {
-      // Customize Playwright rules
-      // ...
-    },
-  },
-]
-```
-
-[Legacy config](https://eslint.org/docs/latest/use/configure/configuration-files)
-(**.eslintrc**)
-
-```json
-{
-  "overrides": [
-    {
-      "files": "tests/**",
-      "extends": "plugin:playwright/jest-playwright"
-    }
-  ]
-}
-```
-
 ## Settings
 
 ### Aliased Playwright Globals
@@ -163,7 +119,7 @@ CLI option\
 | Rule                                                                                                                                                | Description                                                        | ✅  | 🔧  | 💡  |
 | --------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------ | :-: | :-: | :-: |
 | [expect-expect](https://github.com/playwright-community/eslint-plugin-playwright/tree/main/docs/rules/expect-expect.md)                             | Enforce assertion to be made in a test body                        | ✅  |     |     |
-| [max-expects](https://github.com/playwright-community/eslint-plugin-playwright/tree/main/docs/rules/max-expects.md)                                 | Enforces a maximum number assertion calls in a test body           | ✅  |     |     |
+| [max-expects](https://github.com/playwright-community/eslint-plugin-playwright/tree/main/docs/rules/max-expects.md)                                 | Enforces a maximum number assertion calls in a test body           |     |     |     |
 | [max-nested-describe](https://github.com/playwright-community/eslint-plugin-playwright/tree/main/docs/rules/max-nested-describe.md)                 | Enforces a maximum depth to nested describe calls                  | ✅  |     |     |
 | [missing-playwright-await](https://github.com/playwright-community/eslint-plugin-playwright/tree/main/docs/rules/missing-playwright-await.md)       | Enforce Playwright APIs to be awaited                              | ✅  | 🔧  |     |
 | [no-commented-out-tests](https://github.com/playwright-community/eslint-plugin-playwright/tree/main/docs/rules/no-commented-out-tests.md)           | Disallow commented out tests                                       |     |     |     |
@@ -195,6 +151,8 @@ 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-locator](https://github.com/playwright-community/eslint-plugin-playwright/tree/main/docs/rules/prefer-locator.md)                           | Suggest locators over page methods                                 |     |     |     |
 | [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()`                                        |     | 🔧  |     |

.github/workflows/test.yml

@@ -10,6 +10,9 @@ Examples of **incorrect** code for this rule:
 ```javascript
 await page.locator('.my-element')
 await page.getByRole('.my-element')
+
+await expect(1).toBe(1)
+await expect(true).toBeTruthy()
 ```
 
 Examples of **correct** code for this rule:
@@ -20,4 +23,10 @@ page.getByRole('.my-element')
 
 await page.$('.my-element')
 await page.goto('.my-element')
+
+expect(1).toBe(1)
+expect(true).toBeTruthy()
+
+await expect(page.locator('.foo')).toBeVisible()
+await expect(page.locator('.foo')).toHaveText('bar')
 ```

README.md

@@ -0,0 +1,33 @@
+# Suggest using `page.locator()` (`prefer-locator`)
+
+Suggest using locators and their associated methods instead of page methods for
+performing actions.
+
+## Rule details
+
+This rule triggers a warning if page methods are used, instead of locators.
+
+The following patterns are considered warnings:
+
+```javascript
+page.click('css=button')
+await page.click('css=button')
+await page.dblclick('xpath=//button')
+await page.fill('input[type="password"]', 'password')
+
+await page.frame('frame-name').click('css=button')
+```
+
+The following pattern are **not** warnings:
+
+```javascript
+const locator = page.locator('css=button')
+await page.getByRole('password').fill('password')
+await page.getByLabel('User Name').fill('John')
+await page.getByRole('button', { name: 'Sign in' }).click()
+await page.locator('input[type="password"]').fill('password')
+await page.locator('css=button').click()
+await page.locator('xpath=//button').dblclick()
+
+await page.frameLocator('#my-iframe').getByText('Submit').click()
+```

docs/rules/no-useless-await.md

@@ -0,0 +1,70 @@
+# 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')
+```
+
+## Options
+
+```json
+{
+  "playwright/prefer-native-locators": [
+    "error",
+    {
+      "testIdAttribute": "data-testid"
+    }
+  ]
+}
+```
+
+### `testIdAttribute`
+
+Default: `data-testid`
+
+This string option specifies the test ID attribute to look for and replace with
+`page.getByTestId()` calls. If you are using
+[`page.setTestIdAttribute()`](https://playwright.dev/docs/api/class-selectors#selectors-set-test-id-attribute),
+this should be set to the same value as what you pass in to that method.
+
+Examples of **incorrect** code when using
+`{ "testIdAttribute": "data-custom-testid" }` option:
+
+```js
+page.locator('[data-custom-testid="password-input"]')
+```
+
+Examples of **correct** code when using
+`{ "testIdAttribute": "data-custom-testid" }` option:
+
+```js
+page.getByTestId('password-input')
+```

docs/rules/prefer-locator.md

@@ -46,13 +46,19 @@ test(123, () => {})
 test.describe(String(/.+/), () => {})
 test.describe(myFunction, () => {})
 test.describe(6, function () {})
+
+const title = 123
+test(title, () => {})
 ```
 
 Examples of **correct** code for this rule:
 
 ```javascript
 test('is a string', () => {})
 test.describe('is a string', () => {})
+
+const title = 'is a string'
+test(title, () => {})
 ```
 
 Examples of **correct** code when `ignoreTypeOfDescribeName` is `true`:
@@ -143,6 +149,7 @@ test.describe('foo', () => {
 ```ts
 interface Options {
   ignoreSpaces?: boolean
+  ignoreTypeOfStepName?: boolean
   ignoreTypeOfTestName?: boolean
   ignoreTypeOfDescribeName?: boolean
   disallowedWords?: string[]
@@ -157,6 +164,13 @@ Default: `false`
 
 When enabled, the leading and trailing spaces won't be checked.
 
+#### `ignoreTypeOfStepName`
+
+Default: `true`
+
+When enabled, the type of the first argument to `test.step` blocks won't be
+checked.
+
 #### `ignoreTypeOfDescribeName`
 
 Default: `false`

docs/rules/prefer-native-locators.md

@@ -0,0 +1,14 @@
+import mskelton from '@mskelton/eslint-config'
+
+export default [
+  ...mskelton.recommended,
+  {
+    ignores: ['dist', 'examples'],
+  },
+  {
+    files: ['**/*.test.ts'],
+    rules: {
+      'no-template-curly-in-string': 'off',
+    },
+  },
+]

docs/rules/valid-title.md

@@ -0,0 +1,26 @@
+import playwright from 'eslint-plugin-playwright'
+
+export default {
+  ...playwright.configs['flat/recommended'],
+  rules: {
+    ...playwright.configs['flat/recommended'].rules,
+    'playwright/no-commented-out-tests': 'error',
+    'playwright/no-duplicate-hooks': 'error',
+    'playwright/no-get-by-title': 'error',
+    'playwright/no-nth-methods': 'error',
+    'playwright/no-raw-locators': 'error',
+    'playwright/no-restricted-matchers': 'error',
+    'playwright/prefer-comparison-matcher': 'error',
+    'playwright/prefer-equality-matcher': 'error',
+    'playwright/prefer-hooks-in-order': 'error',
+    'playwright/prefer-hooks-on-top': 'error',
+    'playwright/prefer-lowercase-title': 'error',
+    'playwright/prefer-strict-equal': 'error',
+    'playwright/prefer-to-be': 'error',
+    'playwright/prefer-to-contain': 'error',
+    'playwright/prefer-to-have-count': 'error',
+    'playwright/prefer-to-have-length': 'error',
+    'playwright/require-to-throw-message': 'error',
+    'playwright/require-top-level-describe': 'error',
+  },
+}

eslint.config.js

@@ -6,7 +6,7 @@
   },
   "dependencies": {
     "@playwright/test": "^1.42.0",
-    "eslint": "^8.51.0",
+    "eslint": "^9.13.0",
     "eslint-plugin-playwright": "file:../"
   },
   "devDependencies": {

examples/.eslintrc

@@ -0,0 +1,2 @@
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+module.exports = require('./dist/index.cjs')

examples/eslint.config.js

@@ -0,0 +1,12 @@
+import { Linter, Rule } from 'eslint'
+
+declare const config: {
+  configs: {
+    'flat/recommended': Linter.Config
+    'playwright-test': Linter.Config
+    recommended: Linter.Config
+  }
+  rules: Record<string, Rule.RuleModule>
+}
+
+export default config

examples/package.json

@@ -0,0 +1,3 @@
+import plugin from './dist/index.cjs'
+
+export default plugin