ESLint Plugin Playwright

ESLint plugin for Playwright.

Installation

npm

npm install -D eslint-plugin-playwright

Yarn

yarn add -D eslint-plugin-playwright

pnpm

pnpm add -D eslint-plugin-playwright

Usage

This plugin bundles two configurations to work with both @playwright/test or jest-playwright.

With Playwright test runner

Flat config (eslint.config.js)

import playwright from 'eslint-plugin-playwright';

export default [
  playwright.configs['flat/recommended'],
  {
    rules: {
      // Customize Playwright rules
      // ...
    },
  },
];

Legacy config (.eslintrc)

{
  "extends": ["plugin:playwright/recommended"]
}

With Jest Playwright

Flat config (eslint.config.js)

import playwright from 'eslint-plugin-playwright';
import jest from 'eslint-plugin-jest';

export default [
  playwright.configs['flat/jest-playwright'],
  {
    plugins: {
      jest,
    },
    rules: {
      // Customize Playwright rules
      // ...
    },
  },
];

Legacy config (.eslintrc)

{
  "extends": ["plugin:playwright/jest-playwright"]
}

Aliased Playwright Globals

If you import Playwright globals (e.g. test, expect) with a custom name, you can configure this plugin to be aware of these additional names.

{
  "settings": {
    "playwright": {
      "globalAliases": {
        "test": ["myTest"],
        "expect": ["myExpect"]
      }
    }
  }
}

Rules

✅ Set in the recommended configuration
🔧 Automatically fixable by the --fix CLI option
💡 Manually fixable by editor suggestions

Rule	Description	✅	🔧	💡
expect-expect	Enforce assertion to be made in a test body	✅
max-expects	Enforces a maximum number assertion calls in a test body	✅
max-nested-describe	Enforces a maximum depth to nested describe calls	✅
missing-playwright-await	Enforce Playwright APIs to be awaited	✅	🔧
no-commented-out-tests	Disallow commented out tests
no-conditional-expect	Disallow calling `expect` conditionally	✅
no-conditional-in-test	Disallow conditional logic in tests	✅
no-duplicate-hooks	Disallow duplicate setup and teardown hooks
no-element-handle	Disallow usage of element handles	✅		💡
no-eval	Disallow usage of `page.$eval()` and `page.$$eval()`	✅
no-focused-test	Disallow usage of `.only` annotation	✅		💡
no-force-option	Disallow usage of the `{ force: true }` option	✅
no-hooks	Disallow setup and teardown hooks
no-nested-step	Disallow nested `test.step()` methods	✅
no-networkidle	Disallow usage of the `networkidle` option	✅
no-nth-methods	Disallow usage of `first()`, `last()`, and `nth()` methods
no-page-pause	Disallow using `page.pause()`	✅
no-unsafe-references	Prevent unsafe variable references in `page.evaluate()`	✅	🔧
no-get-by-title	Disallow using `getByTitle()`		🔧
no-raw-locators	Disallow using raw locators
no-useless-await	Disallow unnecessary `await`s for Playwright methods	✅	🔧
no-restricted-matchers	Disallow specific matchers & modifiers
no-skipped-test	Disallow usage of the `.skip` annotation	✅		💡
no-standalone-expect	Disallow using expect outside of `test` blocks	✅
no-useless-not	Disallow usage of `not` matchers when a specific matcher exists	✅	🔧
no-wait-for-selector	Disallow usage of `page.waitForSelector()`	✅		💡
no-wait-for-timeout	Disallow usage of `page.waitForTimeout()`	✅		💡
prefer-comparison-matcher	Suggest using the built-in comparison matchers		🔧
prefer-equality-matcher	Suggest using the built-in equality matchers			💡
prefer-hooks-in-order	Prefer having hooks in a consistent order
prefer-hooks-on-top	Suggest having hooks before any test cases
prefer-strict-equal	Suggest using `toStrictEqual()`			💡
prefer-lowercase-title	Enforce lowercase test names		🔧
prefer-to-be	Suggest using `toBe()`		🔧
prefer-to-contain	Suggest using `toContain()`		🔧
prefer-to-have-count	Suggest using `toHaveCount()`		🔧
prefer-to-have-length	Suggest using `toHaveLength()`		🔧
prefer-web-first-assertions	Suggest using web first assertions	✅	🔧
require-hook	Require setup and teardown code to be within a hook
require-top-level-describe	Require test cases and hooks to be inside a `test.describe` block
require-soft-assertions	Require assertions to use `expect.soft()`		🔧
valid-describe-callback	Enforce valid `describe()` callback	✅
valid-expect	Enforce valid `expect()` usage	✅
valid-expect-in-promise	Require promises that have expectations in their chain to be valid	✅
valid-title	Enforce valid titles	✅	🔧
require-to-throw-message	Require a message for `toThrow()`