1. Introduction
Playwright has become one of the popular automation tools for modern web application testing. It supports Chromium, Firefox, and WebKit browsers and provides powerful features such as auto-waiting, web-first assertions, parallel execution, API testing, and built-in reporting.
However, simply writing Playwright test scripts does not guarantee a reliable automation solution. As the application grows, poorly organized test scripts can become difficult to maintain, debug, and execute.
This is why following Playwright framework best practices is important.
A well-designed Playwright automation framework helps QA engineers and SDETs create reusable, scalable, and maintainable automation solutions. It also reduces flaky tests and makes regression testing more reliable.
In this tutorial, we will explore practical Playwright automation best practices using TypeScript. We will cover framework architecture, Page Object Model, fixtures, test data management, reporting, parallel execution, and CI/CD integration.
Whether you are a fresher or an experienced Selenium automation tester transitioning to Playwright, these practices will help you build professional automation frameworks.
2. What Are Playwright Framework Best Practices?
Playwright framework best practices are recommended coding standards, design principles, and execution strategies used to develop reliable and maintainable browser automation frameworks.
These practices help organize automation scripts, improve test stability, reduce code duplication, and simplify debugging.
Some important principles include:
- Use meaningful and reusable test scripts.
- Follow the Page Object Model where it improves maintainability.
- Prefer user-facing locators over fragile CSS and XPath selectors.
- Use web-first assertions instead of fixed waits.
- Keep tests independent and isolated.
- Manage test data separately from test logic.
- Use fixtures for reusable setup and teardown.
- Configure parallel execution carefully.
- Generate detailed test reports.
- Integrate automation suites into CI/CD pipelines.
What Are the Benefits of Playwright Framework Best Practices?
| Benefit | Explanation |
| Maintainability | Makes test scripts easier to update. |
| Reusability | Reduces duplicated code through shared components. |
| Reliability | Reduces flaky tests and synchronization problems. |
| Scalability | Supports growing test suites and multiple teams. |
| Faster execution | Uses parallel execution and optimized configurations. |
| Better debugging | Provides screenshots, traces, and HTML reports. |
| CI/CD integration | Enables automated regression testing during deployments. |
For QA engineering teams, these benefits improve automation coverage and reduce the effort required for repeated regression testing.
3. Recommended Playwright Project Structure
A proper folder structure is the foundation of good Playwright framework design.
Avoid placing all test cases, locators, test data, and utility methods inside a single file.
A recommended scalable project structure is:
playwright-framework/
│
├── tests/
│ ├── login.spec.ts
│ ├── registration.spec.ts
│ └── dashboard.spec.ts
│
├── pages/
│ ├── LoginPage.ts
│ ├── DashboardPage.ts
│ └── RegistrationPage.ts
│
├── fixtures/
│ └── testFixtures.ts
│
├── utils/
│ ├── testData.ts
│ └── helpers.ts
│
├── test-data/
│ └── users.json
│
├── config/
│ └── environments.ts
│
├── .github/
│ └── workflows/
│ └── playwright.yml
│
├── playwright.config.ts
├── package.json
├── tsconfig.json
└── .env
Folder Responsibilities
| Folder | Responsibility |
| tests | Contains test scenarios and assertions. |
| pages | Contains reusable page classes and locators. |
| fixtures | Manages reusable test setup and teardown. |
| utils | Contains common helper functions. |
| test-data | Stores external test data. |
| config | Manages environment-specific settings. |
| .github | Contains GitHub Actions workflows. |
Best practice: Keep test logic separate from page interactions. This separation makes framework maintenance easier when the application UI changes.
4. Use Reliable Locators
Locators identify elements on web pages. Selecting the right locator is one of the most important Playwright automation best practices.
Playwright recommends user-facing locators and explicit testing contracts.
Recommended Locator Types
1. Role-based locator
Use getByRole() to locate elements based on their accessible roles.
await page.getByRole(‘button’, {
name: ‘Login’
}).click();
2. Label locator
Use getByLabel() to locate form fields through their associated labels.
await page.getByLabel(‘Email Address’)
.fill(‘test@example.com’);
3. Text locator
Use getByText() to identify elements using visible text.
await page.getByText(‘Welcome Back’)
.isVisible();
For an assertion, prefer:
await expect(
page.getByText(‘Welcome Back’)
).toBeVisible();
4. Test ID locator
Use getByTestId() when the application provides stable test identifiers.
await page.getByTestId(‘login-button’)
.click();
Incorrect Locator Approach
await page.locator(
‘#container > div:nth-child(2) > button’
).click();
This selector depends on the DOM structure. If the frontend developer changes the layout, the test may fail.
Recommended Approach
await page.getByRole(‘button’, {
name: ‘Submit’
}).click();
Real-world recommendation: Work with developers to add meaningful data-testid attributes for complex components that cannot be reliably identified through accessible roles or labels.
5. Follow Page Object Model (POM)
Page Object Model is a design pattern that separates page-specific interactions from test scenarios.
Instead of writing locators repeatedly in different test files, create reusable page classes.
Example: LoginPage.ts
import { Page, Locator } from ‘@playwright/test’;
export class LoginPage {
readonly page: Page;
readonly email: Locator;
readonly password: Locator;
readonly loginButton: Locator;
constructor(page: Page) {
this.page = page;
this.email = page.getByLabel(‘Email’);
this.password = page.getByLabel(‘Password’);
this.loginButton = page.getByRole(
‘button’,
{ name: ‘Login’ }
);
}
async navigate() {
await this.page.goto(‘/login’);
}
async login(email: string, password: string) {
await this.email.fill(email);
await this.password.fill(password);
await this.loginButton.click();
}
}
Example: login.spec.ts
import { test, expect } from ‘@playwright/test’;
import { LoginPage } from ‘../pages/LoginPage’;
test(‘Verify successful login’, async ({ page }) => {
const loginPage = new LoginPage(page);
await loginPage.navigate();
await loginPage.login(
‘test@example.com’,
‘Password123’
);
await expect(page).toHaveURL(/dashboard/);
await expect(
page.getByRole(‘heading’, {
name: ‘Dashboard’
})
).toBeVisible();
});
Why Use POM?
- Avoids repeated locator definitions.
- Improves code readability.
- Makes maintenance easier.
- Encourages reusable page interactions.
- Separates test scenarios from application implementation.
Important: Do not put every assertion inside page classes. Keep scenario-specific business validations in test files. Use POM to organize interactions, not to create unnecessary layers.
For a deeper explanation, internally link this section to the TechSarvam pillar article: Playwright Framework Design.
6. Use Web-First Assertions
One major advantage of Playwright is its built-in auto-retrying assertions.
When a web application loads dynamically, elements may not become visible immediately. Traditional assertions can fail if they execute before the application finishes updating.
Playwright web-first assertions automatically retry until the expected condition is satisfied or the assertion timeout is reached.
Incorrect Approach
expect(
await page.getByText(‘Login Successful’).isVisible()
).toBe(true);
This checks visibility immediately rather than waiting for the expected condition.
Recommended Approach
await expect(
page.getByText(‘Login Successful’)
).toBeVisible();
Other useful assertions include:
await expect(page).toHaveTitle(‘Dashboard’);
await expect(page).toHaveURL(/dashboard/);
await expect(
page.getByRole(‘button’, { name: ‘Logout’ })
).toBeEnabled();
await expect(
page.getByLabel(‘Email’)
).toHaveValue(‘test@example.com’);
Avoid Fixed Waits
Incorrect:
await page.waitForTimeout(5000);
Recommended:
await expect(
page.getByText(‘Order Completed’)
).toBeVisible();
Fixed waits unnecessarily increase execution time and may still fail when an application takes longer than expected.
Use explicit waits only when you have a genuine synchronization requirement that cannot be expressed through normal locator actions or assertions.
7. Manage Test Data and Environments
A professional automation framework should not contain hard-coded URLs, usernames, passwords, and environment-specific values throughout test scripts.
Instead, separate configuration from test logic.
Environment Variables
Create a .env file:
BASE_URL=https://staging.example.com
TEST_USERNAME=test@example.com
TEST_PASSWORD=Password123
Install dotenv:
npm install dotenv
Load the variables in playwright.config.ts:
import dotenv from ‘dotenv’;
dotenv.config();
import { defineConfig } from ‘@playwright/test’;
export default defineConfig({
use: {
baseURL: process.env.BASE_URL
},
testDir: ‘./tests’
});
Access the variables in test scripts:
const username = process.env.TEST_USERNAME!;
const password = process.env.TEST_PASSWORD!;
await loginPage.login(username, password);
Use a validation step for required environment variables in production frameworks rather than relying only on TypeScript’s non-null assertion.
Test Data Separation
Create test-data/users.json:
{
“validUser”: {
“email”: “test@example.com”,
“password”: “Password123”
},
“invalidUser”: {
“email”: “invalid@example.com”,
“password”: “WrongPassword”
}
}
Import the test data:
import users from ‘../test-data/users.json’;
await loginPage.login(
users.validUser.email,
users.validUser.password
);
Keep credentials and sensitive information out of source control. Use CI/CD secrets or a secure secret manager for real environments.
8. Use Fixtures and Test Hooks
Fixtures help manage reusable test setup and teardown operations.
Playwright provides built-in fixtures such as:
- page
- browser
- context
- request
You can also create custom fixtures.
Example: Custom Test Fixture
Create fixtures/testFixtures.ts:
import { test as base } from ‘@playwright/test’;
import { LoginPage } from ‘../pages/LoginPage’;
type MyFixtures = {
loginPage: LoginPage;
};
export const test = base.extend<MyFixtures>({
loginPage: async ({ page }, use) => {
const loginPage = new LoginPage(page);
await loginPage.navigate();
await use(loginPage);
}
});
export { expect } from ‘@playwright/test’;
Use the custom fixture:
import { test, expect } from ‘../fixtures/testFixtures’;
test(‘Verify login page’, async ({ loginPage, page }) => {
await loginPage.login(
‘test@example.com’,
‘Password123’
);
await expect(page).toHaveURL(/dashboard/);
});
Before and After Hooks
import { test } from ‘@playwright/test’;
test.beforeEach(async ({ page }) => {
await page.goto(‘/login’);
});
test.afterEach(async ({ page }) => {
console.log(‘Test execution completed’);
});
Best practice: Use fixtures for reusable setup with lifecycle management. Use beforeEach and afterEach for simple test-level preparation and cleanup.
Avoid sharing mutable browser state between independent tests.
9. Improve Test Execution
Execution performance becomes important when an automation framework contains hundreds or thousands of regression test cases.
Playwright provides parallel execution, retries, configurable timeouts, and browser projects.
Parallel Execution
Playwright runs test files in parallel by default.
Configure the worker count:
export default defineConfig({
workers: process.env.CI ? 2 : undefined,
});
For independent tests inside a file, you can also enable parallel execution:
test.describe.configure({
mode: ‘parallel’
});
Ensure that parallel tests do not modify the same shared records or depend on execution order.
Configure Retries
export default defineConfig({
retries: process.env.CI ? 2 : 0,
});
Retries are useful for capturing intermittent failures, but they should not be used to hide flaky tests.
Investigate failures even when a retry passes.
Cross-Browser Testing
Use browser projects to test applications across Chromium, Firefox, and WebKit.
import { defineConfig, devices } from ‘@playwright/test’;
export default defineConfig({
projects: [
{
name: ‘chromium’,
use: { …devices[‘Desktop Chrome’] }
},
{
name: ‘firefox’,
use: { …devices[‘Desktop Firefox’] }
},
{
name: ‘webkit’,
use: { …devices[‘Desktop Safari’] }
}
]
});
npx playwright test –project=chromium
This approach helps identify browser compatibility problems before application release.
10. Reporting and Debugging
Reporting is essential for understanding test execution results and identifying application defects.
Playwright provides a built-in HTML reporter.
Configure HTML Reporting
export default defineConfig({
reporter: [
[‘list’],
[‘html’, {
open: ‘never’
}]
]
});
Execute tests:
npx playwright test
Open the report:
npx playwright show-report
The HTML report provides information about passed tests, failed tests, execution duration, and failure details.
Capture Screenshots
await page.screenshot({
path: ‘screenshots/login-page.png’,
fullPage: true
});
For automatic failure screenshots, configure:
use: {
screenshot: ‘only-on-failure’
}
Enable Trace Viewer
Trace Viewer is especially useful for debugging failures in CI environments.
Configure:
use: {
trace: ‘on-first-retry’
}
npx playwright test –trace on
Open the report:
npx playwright show-report
The trace helps engineers inspect browser actions, DOM snapshots, network activity, and execution timing.
Real-world scenario: Suppose a checkout test fails because the payment confirmation message does not appear. The trace can help determine whether the click failed, the API returned an error, or the confirmation message never appeared.
11. Follow CI/CD Best Practices
A professional Playwright framework should execute automatically whenever developers submit code changes.
GitHub Actions and Jenkins are popular CI/CD options for Playwright automation.
GitHub Actions Integration
Create:
.github/workflows/playwright.yml
name: Playwright Automation
on:
push:
branches: [main]
pull_request:
branches: [main]
jobs:
test:
timeout-minutes: 60
runs-on: ubuntu-latest
steps:
– name: Checkout Repository
uses: actions/checkout@v4
– name: Setup Node.js
uses: actions/setup-node@v4
with:
node-version: 22
– name: Install Dependencies
run: npm ci
– name: Install Playwright Browsers
run: npx playwright install –with-deps chromium
– name: Run Automation Tests
run: npx playwright test
– name: Upload Test Report
if: always()
uses: actions/upload-artifact@v4
with:
name: playwright-report
path: playwright-report/
retention-days: 30
The workflow executes automation tests whenever a pull request is created or code is pushed to the main branch.
For Jenkins, create a pipeline with similar stages:
- Checkout the repository.
- Install Node.js dependencies.
- Install the required Playwright browser.
- Execute regression tests.
- Publish the HTML report.
- Archive screenshots and trace files.
Best practice: Start with a smoke test suite for pull requests and run the complete regression suite on a scheduled or release pipeline. Add browser projects and CI sharding when execution time requires it.
12. Common Playwright Framework Mistakes to Avoid
Even experienced automation engineers make mistakes when designing automation frameworks.
| Common Mistake | Recommended Solution |
| Using fixed waits everywhere | Use auto-waiting and web-first assertions. |
| Hard-coding URLs | Use environment configuration. |
| Duplicating locators | Create reusable page classes. |
| Using unstable XPath | Prefer role, label, and test ID locators. |
| Sharing test data | Generate or isolate test data. |
| Ignoring failed tests | Analyze traces and failure reports. |
| Excessive retries | Identify and fix flaky tests. |
| Overcomplicated POM | Keep page classes focused. |
| Running all tests sequentially | Use safe parallel execution. |
| Ignoring CI failures | Make test results part of release decisions. |
Following these recommendations improves framework stability and reduces unnecessary maintenance work.
13. Real-World Playwright Framework Example
Let’s combine the important practices using a simple e-commerce login and product dashboard scenario.
Scenario: A user logs into an e-commerce application and verifies that the product dashboard is displayed.
Step 1: Configure Playwright
playwright.config.ts
import dotenv from ‘dotenv’;
dotenv.config();
import { defineConfig } from ‘@playwright/test’;
export default defineConfig({
testDir: ‘./tests’,
fullyParallel: true,
retries: process.env.CI ? 2 : 0,
workers: process.env.CI ? 2 : undefined,
reporter: [
[‘list’],
[‘html’, { open: ‘never’ }]
],
use: {
baseURL: process.env.BASE_URL,
trace: ‘on-first-retry’,
screenshot: ‘only-on-failure’,
video: ‘retain-on-failure’
}
});
Step 2: Create the Login Page
pages/LoginPage.ts
import { Page } from ‘@playwright/test’;
export class LoginPage {
constructor(private page: Page) {}
async login(email: string, password: string) {
await this.page.goto(‘/login’);
await this.page.getByLabel(‘Email’)
.fill(email);
await this.page.getByLabel(‘Password’)
.fill(password);
await this.page.getByRole(‘button’, {
name: ‘Login’
}).click();
}
}
Step 3: Write the Test Case
tests/login.spec.ts
import { test, expect } from ‘@playwright/test’;
import { LoginPage } from ‘../pages/LoginPage’;
test(‘Verify successful e-commerce login’, async ({ page }) => {
const loginPage = new LoginPage(page);
await loginPage.login(
process.env.TEST_USERNAME!,
process.env.TEST_PASSWORD!
);
await expect(page).toHaveURL(/dashboard/);
await expect(
page.getByRole(‘heading’, {
name: ‘Products’
})
).toBeVisible();
});
Step 4: Execute the Framework
Install dependencies:
npm install -D @playwright/test dotenv
Install Chromium:
npx playwright install chromium
Execute the test:
npx playwright test
Generate the HTML report:
npx playwright show-report
Expected Test Result
| Test Scenario | Expected Result |
| Navigate to login page | Login page opens successfully. |
| Enter valid credentials | Credentials are accepted. |
| Click Login | User is redirected to dashboard. |
| Verify dashboard heading | Products heading is visible. |
| Generate report | Execution results are available. |
This example demonstrates how Playwright framework best practices work together in a practical automation project.
For a real enterprise framework, extend this implementation with API-based test data setup, isolated test accounts, reusable fixtures, negative login scenarios, and environment validation.
14. Playwright Framework Best Practices: Interview Questions and FAQs
The following questions are useful for freshers, experienced automation testers, and SDETs preparing for technical interviews.
Q1. What is Playwright framework best practices?
Playwright framework best practices are recommended techniques for developing stable, reusable, scalable, and maintainable automation frameworks. They include proper locator strategies, POM, fixtures, test isolation, reporting, and CI/CD integration.
Q2. Why is Page Object Model used in Playwright?
POM separates page interactions from test scenarios. It reduces code duplication and makes maintenance easier when application locators or UI elements change.
Q3. How do you reduce flaky tests in Playwright?
Use reliable locators, auto-waiting, web-first assertions, independent test data, and proper synchronization. Avoid unnecessary fixed waits and shared mutable state.
Q4. What is the difference between fixtures and hooks?
Fixtures provide reusable setup and teardown with dependency management. Hooks such as beforeEach and afterEach execute setup and cleanup logic around tests.
Q5. How do you execute Playwright tests in parallel?
Playwright supports parallel test execution by default. Configure the number of workers using the workers option or enable parallel execution within a test group.
Q6. How do you handle multiple environments?
Use environment variables and configuration files to manage different base URLs, credentials, and environment-specific settings.
Q7. How do you debug failed Playwright tests?
Use HTML reports, screenshots, Playwright Inspector, and Trace Viewer to investigate failed actions, locator problems, and network issues.
Q8. How do you integrate Playwright with Jenkins?
Configure a Jenkins pipeline to install dependencies, install browsers, execute tests, publish reports, and archive failure artifacts.
Q9. What is the recommended locator strategy in Playwright?
Prefer getByRole(), getByLabel(), and getByText() for user-facing elements. Use getByTestId() when an explicit testing contract is more appropriate.
Q10. How do you design a scalable Playwright framework?
Separate tests, page objects, fixtures, utilities, configuration, and test data. Introduce reusable components where needed and integrate reporting, parallel execution, and CI/CD.
Placement-Oriented Interview Preparation Tips for Indian QA/SDET Candidates
For Indian IT service companies and product-based organizations, prepare beyond basic Playwright commands.
Focus on these practical areas:
- Explain your framework architecture with a folder structure.
- Demonstrate POM implementation using TypeScript.
- Explain auto-waiting versus explicit waits.
- Write reusable fixtures and custom test utilities.
- Explain parallel execution and test isolation.
- Demonstrate API testing and browser automation together.
- Explain how you debug intermittent CI failures.
- Describe how you integrate regression suites with Jenkins or GitHub Actions.
Interview tip: Prepare one end-to-end project that you can explain from framework setup to CI/CD execution. Interviewers often evaluate your ability to solve real automation problems rather than your ability to memorize Playwright methods.
Frequently Asked Questions
Q1. How do I get started with Playwright framework best practices?
Install Playwright using npm init playwright@latest, select TypeScript, understand the project structure, create reusable page classes, and gradually introduce fixtures, reporting, and CI/CD.
Q2. Is TypeScript recommended for Playwright automation?
Yes. TypeScript provides type checking, improved IDE support, and better maintainability for large automation projects.
Q3. Should every Playwright project use Page Object Model?
POM is useful for medium and large projects with reusable page interactions. Small projects may use simpler test organization without unnecessary abstraction.
Q4. How many retries should be configured?
A common approach is zero retries locally and one or two retries in CI. Investigate failures rather than treating retries as a permanent solution.
Q5. Can Playwright support regression testing?
Yes. Playwright supports automated regression testing across multiple browsers, devices, and environments.
Q6. Is Playwright suitable for beginners?
Yes. Its TypeScript support, built-in assertions, auto-waiting, and debugging tools make it approachable for beginners and experienced Selenium testers.
