ESLint Plugin Playwright

2.10.2 verified Sat Apr 25 auth: no javascript

ESLint plugin for Playwright testing framework, providing lint rules to catch common mistakes and enforce best practices. Current stable version is v2.10.2, with frequent releases (weekly to bi-weekly). Supports both flat config (eslint.config.js) and legacy .eslintrc. Ships TypeScript types. Key differentiators: it is the official Playwright ESLint plugin, actively maintained, with 30+ rules including 'missing-playwright-await' to detect missing await on Playwright assertions, and 'no-wait-for-selector' replacement for deprecated APIs.

Common errors

error Error: Cannot find module 'eslint-plugin-playwright' ↓

cause Package not installed or not in node_modules

fix

Run npm install -D eslint-plugin-playwright (or yarn/pnpm)

error Error: Failed to load plugin 'playwright' declared in 'extends': The plugin is missing. ↓

cause Legacy config referencing 'plugin:playwright/recommended' but package not installed

fix

Ensure eslint-plugin-playwright is installed and in your package.json devDependencies

error Error: [playwright/expect-expect] Expected assertion to be made in a test body. ↓

cause A test block has no assertion (expect) call

fix

Add an assertion inside the test, e.g., await expect(page).toHaveTitle(...)

error Error: [playwright/missing-playwright-await] Expected 'await' before Playwright async method. ↓

cause Calling async Playwright method like page.goto() or locator.click() without await

fix

Add await before the method call: await page.goto(url)

Warnings

breaking Flat config breaking change: configs are under 'flat/recommended' not 'recommended' ↓

fix Use `playwright.configs['flat/recommended']` instead of `playwright.configs.recommended`

breaking Requires ESLint >= 8.40.0 ↓

fix Update ESLint to >= 8.40.0 or stay on v1 if using older ESLint

deprecated Rule 'no-wait-for-selector' is deprecated in favor of Playwright's built-in auto-waiting ↓

fix Remove usage of page.waitForSelector and let Playwright handle waiting automatically

gotcha CommonJS require returns the whole plugin object, not a default export ↓

fix Use `const playwright = require('eslint-plugin-playwright')` then `playwright.configs['flat/recommended']`

gotcha Using legacy config (eslintrc) with flat config will cause errors ↓

fix Choose one config format: flat config (eslint.config.js) or legacy (eslintrc)

Install

npm install eslint-plugin-playwright

yarn add eslint-plugin-playwright

pnpm add eslint-plugin-playwright

Imports

default export (entire plugin object)
wrong
```
const { configs, rules } = require('eslint-plugin-playwright')
```
correct
```
import playwright from 'eslint-plugin-playwright'
```
CommonJS users must use `const playwright = require('eslint-plugin-playwright')`. The default import provides the plugin object with configs and rules.
flat config (recommended)
wrong
```
playwright.configs.recommended
```
correct
```
playwright.configs['flat/recommended']
```
Since v2, flat config is accessed via `flat/recommended` key. Legacy `recommended` is for .eslintrc only.

individual rules

wrong

import { missingPlaywrightAwait } from 'eslint-plugin-playwright'

correct

import { rules } from 'eslint-plugin-playwright' // then reference rules['missing-playwright-await']

Rules are not exported as named exports; you must access via the `rules` object.

Quickstart

Shows flat config usage: targeting tests/ folder, extending recommended flat config, and customizing a rule.

// eslint.config.js (flat config)
import { defineConfig } from '@eslint/config'
import playwright from 'eslint-plugin-playwright'

export default defineConfig([
  {
    files: ['tests/**'],
    extends: [playwright.configs['flat/recommended']],
    rules: {
      'playwright/max-expects': ['error', { max: 3 }],
    },
  },
])