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. 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

Flat config (eslint.config.js)

import playwright from 'eslint-plugin-playwright'

export default [
  {
    ...playwright.configs['flat/playwright'],
    files: ['tests/**'],
  },
  {
    files: ['tests/**'],
    rules: {
      // Customize Playwright rules
      // ...
    },
  },
]

Legacy config (.eslintrc)

{
  "overrides": [
    {
      "files": "tests/**",
      "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'],
    files: ['tests/**'],
  },
  {
    files: ['tests/**'],
    plugins: { jest },
    rules: {
      // Customize Playwright rules
      // ...
    },
  },
]

Legacy config (.eslintrc)

{
  "overrides": [
    {
      "files": "tests/**",
      "extends": "plugin:playwright/jest-playwright"
    }
  ]
}

Settings

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"]
      }
    }
  }
}

Custom Messages

You can customize the error messages for rules using the settings.playwright.messages property. This is useful if you would like to increase the verbosity of error messages or provide additional context.

Only the message ids you define in this setting will be overridden, so any other messages will use the default message defined by the plugin.

{
  "settings": {
    "playwright": {
      "messages": {
        "conditionalExpect": "Avoid conditional expects as they can lead to false positives"
      }
    }
  }
}

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 awaits 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() | | | |