Setting Up ESLint for Playwright Projects in 2026

Have you ever returned to a Playwright project after a few weeks and felt the tests were suddenly unstable or difficult to trust?

In most cases the problem isn’t Playwright. It comes from small issues that slip in unnoticed.

Missing awaits. Inconsistent patterns. Promise errors that never surface. Test files that grow without any structure.

I’ve faced the same situation, and the instability only made sense when I stepped back and saw how these small mistakes stacked up, which is exactly where a strict ESLint setup becomes the guardrail that keeps Playwright tests stable.

// eslint.config.js or .eslintrc.jsmodule.exports = {

root: true,

env: {

browser: true,

node: true,

es2024: true

},

parser: ‘@typescript-eslint/parser’,

parserOptions: {

project: ‘./tsconfig.json’,

sourceType: ‘module’

},

extends: [

‘eslint:recommended’,

‘plugin:@typescript-eslint/recommended’,

‘plugin:playwright/recommended’,

‘prettier’

],

plugins: [

‘@typescript-eslint’,

‘playwright’

],

rules: {

// Strengthen async safety in Playwright tests

‘@typescript-eslint/no-misused-promises’: ‘error’,

‘@typescript-eslint/await-thenable’: ‘error’

}

};

How ESLint Supports Test Quality and Stability in Playwright Projects

Playwright tests depend on clean async handling, stable locators and a predictable project layout. When these elements drift, test reliability drops and failures become harder to trace.

ESLint acts as a checkpoint that identifies issues early and guides the codebase toward patterns that reduce flakiness. It reviews the code before the tests ever run and highlights behaviours that commonly cause instability.

Here is how ESLint contributes to a steady and maintainable Playwright setup.

• Preventing hidden async mistakes: Playwright runs on async operations, and missing a single await can lead to race conditions that only appear under slower or remote environments. ESLint flags these issues early.
• Highlighting unsafe locator usage: Practices like nested locators or overly complex chains often break during cloud runs. ESLint warns about these patterns before they cause failures.
• Guiding consistent test structure: Large suites are easier to navigate when file names, imports and patterns remain uniform. ESLint enforces this structure across the project.
• Reducing flakiness caused by timing issues: Many timing problems come from improper async handling rather than Playwright itself. ESLint rules help avoid these traps.

• Helping teams review code faster: ESLint catches smaller mistakes so reviewers can focus on test logic instead of syntax or missing awaits.

Even with ESLint catching async mistakes and enforcing structure, tests can still behave unpredictably across different browsers and devices. Ensuring that your Playwright suite runs reliably in real-world conditions is a challenge.

Tools like BrowserStack help by running these stable, ESLint-checked tests on real browsers and devices, so flakiness is minimized and failures are easier to debug.

Run Playwright Tests on Real Devices

What ESLint Packages Are Required for Playwright Test Environments

A Playwright project needs ESLint packages that can understand async test behaviour, TypeScript syntax and Playwright-specific patterns. Without the right set of packages, the linter either misses important issues or produces noise that does not help anyone.

The goal is to give ESLint enough context to read your test files correctly and apply rules that actually strengthen test stability. Below are the core packages that form a complete Playwright linting setup.

• ESLint: This is the main linter that evaluates your code, identifies problems and enforces consistent patterns across the project.
• @typescript-eslint/parser and @typescript-eslint/eslint-plugin: These packages help ESLint understand TypeScript so the linter can detect type safety issues, async misuse and patterns that often cause flaky tests.
• eslint-plugin-playwright: This plugin includes rules designed for Playwright. It flags issues like unsafe locators, missing awaits on Playwright actions and incorrect usage of test functions.
• Configuration files: .eslintrc.js defines the linting rules, the parser and the configurations you extend. tsconfig.json tells ESLint how the TypeScript project is structured so it interprets the files correctly.

These packages work together to give ESLint full visibility into how your Playwright tests behave, which allows the linter to catch real issues instead of shallow syntax errors.

How To Configure ESLint for Playwright Projects

A clean ESLint setup gives Playwright tests a consistent structure. It prevents silent failures, flags missing awaits, and keeps async patterns predictable. Setting it up is straightforward when the configuration follows a clear sequence.

Here are the steps that establish a stable baseline for any Playwright project.

Step 1: Install the core ESLint packages that every JavaScript or TypeScript project needs. This includes eslint itself and the parser that understands modern syntax.

Step 2: Add the Playwright specific plugin so ESLint knows how to interpret test, expect and the async flow inside UI automation.

Step 3: Create or update the eslint config file and set the environment to node and browser. This ensures global variables like page and browser types are handled correctly.

Step 4: Extend the recommended configurations from ESLint and the Playwright plugin. This activates rules that catch async mistakes inside test blocks.

Step 5: Configure ignore patterns for folders that should not be linted. Examples include the Playwright test output folder and node modules.

Step 6: Run eslint for the first time and review the errors. This confirms the config is wired correctly before adding custom rules or project level adjustments.

How To Configure ESLint Rules for Playwright Test Syntax

Playwright relies on async actions, strict locator patterns and predictable test blocks. To enforce these behaviours, ESLint rules must be configured in a way that actively guides the test author while writing code.

This requires enabling the right rule sets, applying overrides for test files and adjusting rule severity based on how strict the team wants the test suite to be.

Here is how to configure the rules:

• Extend plugin:playwright/recommended: This preset enables rules for async actions, locators and test structure. It acts as the baseline so you do not configure each rule manually.
• Create overrides for test files: Add a files section targeting patterns like **/*.spec.ts so Playwright-specific rules apply only to test directories and not app code.
• Adjust rule severity for async safety: Set rules like no-floating-promises or await-thenable to error inside test overrides so missing awaits are caught immediately.

• Enable locator warnings: Turn on rules that warn against chained locators or unsafe selectors to prevent hidden flakiness.
• Configure structure rules for test blocks: Enforce consistent patterns for test, describe and hooks so the suite remains readable and avoids unexpected dependencies.

Configuring rules this way ensures ESLint evaluates Playwright tests with the level of strictness needed for stable UI automation.

How To Enable TypeScript Aware Linting for Playwright

To get accurate linting inside Playwright tests, ESLint must read TypeScript type information and understand async return types. This requires setting up TypeScript-aware parsing and linking ESLint with your tsconfig file. When done correctly, the linter can detect type-driven issues that are common in automation work.

Here is how to enable TypeScript aware linting:

• Set parser to @typescript-eslint/parser: Update .eslintrc so ESLint uses a parser capable of reading TypeScript syntax.
• Add parserOptions.project: Point the project field to tsconfig.json so ESLint uses your TypeScript configuration while analysing test files.
• Include @typescript-eslint/eslint-plugin: This plugin adds rules that catch unsafe promise usage, incorrect return types and other type-linked issues common in UI tests.
• Extend recommended TypeScript configs: Use @typescript-eslint/recommended and the type-checked variant if required, depending on how strict the suite needs to be.
• Enable TypeScript rules inside Playwright test overrides: Apply stricter async and promise rules only to test files to avoid unnecessary noise in utility folders.

Even with strict TypeScript linting, large Playwright test suites can cause slow or flaky CI pipelines if run locally. Platforms like BrowserStack enable parallel testing on real devices and browsers to ensure type-safe tests scale efficiently while maintaining stability and reliability.

How To Lint Playwright Project Structure and Test Directories

Large Playwright suites become hard to manage when files are scattered, helpers mix with tests or naming patterns drift. ESLint can enforce structure through directory-specific rules and naming conventions.

To apply these constraints, you need to configure targeted overrides and plugins that understand file paths. Below is the process for setting this up.

Here is how to lint project structure and test directories:

• Create path-based overrides: Target folders like tests, e2e or specs to ensure only those files follow Playwright-specific rules.
• Enforce naming patterns: Use filename rules so test files follow formats like *.spec.ts or *.test.ts and utility files follow consistent naming.
• Restrict imports from app code: Apply no-restricted-imports to prevent test files from pulling internal modules that create tight coupling.
• Define allowed folder layouts: Use rules that limit placement of Playwright fixtures, helpers or global setup files so the project stays predictable.
• Enable linting for unused helpers: Detect unused fixtures or helper functions so the test directory stays clean as it grows.

Common ESLint Errors Seen in Playwright Projects and How To Resolve Them

Playwright projects trigger a predictable set of ESLint errors. These issues point to patterns that cause flaky behaviour, missed awaits, or invalid test flow. Below are the most frequent errors and how to fix them in a practical way.

• Missing await on Playwright actions: This error appears when a Playwright method like click or fill executes without await. Playwright depends on awaited async steps for stability. Fix it by marking the function async and adding await to every action or navigation.

• Unhandled promise from a Playwright operation: The no-floating-promises rule catches cases where a promise completes silently. These unhandled operations hide failures inside navigation or API calls. Fix it by awaiting the call or wrapping the promise inside a controlled try pattern.
• Incorrect test or hook placement: This occurs when test, beforeEach, or afterEach functions sit outside valid test.describe scopes. Playwright structures tests in isolated blocks, so moving the hook or test into the correct scope resolves the error.
• Unused locator variables: This is common when refactoring tests. A locator is declared but never used, which often signals incomplete test logic. Remove the unused locator or attach it to an actual interaction.
• Broad or unstable Playwright selectors: Some rules warn when selectors use patterns that Playwright treats as fragile. These selectors lead to flaky tests. Replace them with exact role-based or text-based locators that stay stable over UI changes.
• Mixed sync and async test code: Playwright APIs are async. Mixing synchronous checks inside async tests triggers rule warnings because the sequence breaks test timing. Convert the surrounding logic into async or move sync checks to a controlled utility function.

How To Run ESLint in CI for Playwright Automation

Linting inside CI keeps flaky test patterns out of the codebase before Playwright runs. The setup works best when the CI pipeline follows a clear set of steps that validate lint output and block unstable changes.

Step 1: Add a dedicated lint script in package.json so the CI workflow has a reliable command entry point.

Step 2: Install all ESLint and Playwright-related plugins inside the CI image so the environment matches local development.

Step 3: Create a separate lint job that runs before Playwright tests to prevent unstable async patterns from reaching execution.

Step 4: Configure the CI job to fail when ESLint reports errors so branches cannot merge with missing awaits or invalid test structure.

Step 5: Enable caching for node modules or .eslintcache to prevent delays in large Playwright repositories with many test files.

Step 6: Add lint output to CI logs so test authors can quickly locate missing awaits, invalid hooks, or broken selectors without re-running jobs locally.

How To Maintain and Update ESLint Rules for Playwright in 2026

Playwright projects evolve as new test patterns, new APIs, and new browser behaviours appear. ESLint must grow with the project or it starts missing issues that cause subtle flakiness. The simplest way to keep ESLint effective is to follow a clear sequence of steps that keep the config updated and aligned with the test suite.

Additionally, follow these steps to update ESLint Rules for Playwright in 2026.

Step 1: Review Playwright plugin releases every few months because new rules often target problems found in recent Playwright versions. Update eslint-plugin-playwright and apply new recommended rules when they address gaps in your test patterns.

Step 2: Update @typescript-eslint packages so ESLint understands newer TypeScript syntax used inside Playwright tests. This prevents parsing gaps and keeps the linter aligned with evolving TypeScript configurations.

Step 3: Revisit custom overrides that were added months ago. Some overrides disable rules that protect test stability. Remove overrides that no longer serve a real purpose.

Step 4: Add new rules when you notice recurring mistakes in the codebase. Many teams observe patterns such as inconsistent waits or unstable selectors. Convert these into lint rules or rule tweaks so the issue stops repeating.

Step 5: Test lint changes on a branch with a large subset of the Playwright tests. This helps confirm that new rules do not block valid patterns or slow down developer workflows.

Step 6: Keep the .eslintrc file small and readable. Consolidate outdated settings and keep only rules that add clear value to Playwright test stability.

Running Playwright Tests on Scalable Infrastructure

When a test suite grows, local or in’#145;house infrastructure stops being enough. Running tests on a single machine or limited device set introduces several problems. Old browser versions pile up and aren’t maintained.

Emulators and headless browsers often fail to reveal issues that only emerge on real devices, like rendering quirks or OS’#145;specific behaviours. Scaling test volume becomes cumbersome and slow. Network limitations, device diversity, and environment drift lead to unpredictable failures.

That’s where tools like BrowserStack come in. BrowserStack Automate offers a cloud-based infrastructure that addresses the scaling challenges in a practical, resource-efficient manner. Here is how it helps when paired with Playwright tests:

• Real Device Cloud: BrowserStack gives access to thousands of browser-OS combinations, including recent and legacy versions, on real devices and real browsers.
• Parallel Testing: Instead of sequential runs that take hours or days, tests can execute in parallel across browsers and platforms.
• Test Reporting & Analytics: When a test fails, BrowserStack provides video recordings, logs, screenshots, and network captures.
• Local Environment Testing: Run Playwright tests against local or internal apps via BrowserStack before pushing to production.

Talk to an Expert

Conclusion

ESLint is a critical tool for maintaining stable and reliable Playwright tests. By enforcing consistent async handling, proper locators, and structured test patterns, it prevents common pitfalls that lead to flaky or unpredictable automation.

Running Playwright tests on BrowserStack takes this reliability further. You can validate your ESLint’#145;enforced tests across real browsers, devices, and operating systems, including local and internal environments via secure tunnels.

Try BrowserStack for Free

Useful Resources for Playwright

• Playwright Automation Framework
• Playwright Java Tutorial
• Playwright Python tutorial
• Playwright Debugging
• End to End Testing using Playwright
• Visual Regression Testing Using Playwright
• Mastering End-to-End Testing with Playwright and Docker
• Page Object Model in Playwright
• Scroll to Element in Playwright
• Understanding Playwright Assertions
• Cross Browser Testing using Playwright
• Playwright Selectors
• Playwright and Cucumber Automation

Tool Comparisons:

• Playwright vs Puppeteer
• Playwright vs Cypress
• Playwright vs Selenium
• Cypress vs Selenium vs Playwright vs Puppeteer