1. Introduction to Playwright Test Runner
Automated testing is an important part of modern software development. QA Engineers and developers use automation frameworks to verify that web applications work correctly across different browsers and environments.
One popular tool for end-to-end testing is Playwright. It supports Chromium, Firefox, and WebKit and provides reliable browser automation capabilities.
However, browser automation and test execution are two different things. Playwright provides browser automation APIs, while Playwright Test provides the test runner used to organize, execute, and report automated tests.
The playwright javascript test runner helps QA Engineers write structured test cases, execute them in parallel, manage test data, capture screenshots, and generate reports.
In this tutorial, you will learn how to install Playwright Test, configure a JavaScript project, write test cases, use fixtures and hooks, execute tests, generate reports, and integrate the test runner into CI/CD pipelines.
We will also build a practical project that can help beginners and SDETs understand how a real automation framework works.
2. What Is Playwright Test and Its Key Features?
Playwright Test is an end-to-end testing framework built specifically for Playwright. It provides a test runner, assertions, fixtures, hooks, parallel execution, retries, and reporting.
It helps teams manage automated tests without building these capabilities separately.
Playwright vs. Playwright Test
It is important to understand the difference between Playwright and Playwright Test.
| Playwright | Playwright Test |
| Browser automation library | End-to-end test runner |
| Provides browser APIs | Organizes and executes test cases |
| Supports browser interactions | Provides test() and expect() |
| Can be used for custom automation scripts | Provides fixtures and hooks |
| Controls browser pages and contexts | Supports retries and parallel execution |
For example, Playwright provides methods such as page.goto() and locator.click() to interact with web applications.
Playwright Test provides test() to define a test case and expect() to verify the expected result.
Key Features of Playwright Test Runner
1. Built-in assertions
Playwright Test includes the expect() API to verify page titles, text, visibility, URLs, and other application behavior.
2. Auto-waiting
Playwright actions and web-first assertions automatically wait for relevant conditions. This reduces failures caused by elements not being ready.
3. Fixtures
Fixtures provide reusable resources such as browser pages, browser contexts, and API request objects.
Tests can run across multiple workers to reduce overall execution time.
5. Test isolation
Each test receives an isolated browser context by default when using the standard page fixture.
6. Retry mechanism
You can configure failed tests to run again, which can help identify intermittent failures.
7. Reporting
The HTML reporter provides a detailed view of passed, failed, and skipped tests.
8. Debugging support
Screenshots, videos, traces, and the Playwright Inspector help investigate test failures.
3. Prerequisites and JavaScript Installation
Before starting the playwright javascript test runner tutorial, install the required software.
Prerequisites
- Basic JavaScript knowledge.
- Node.js and npm.
- Visual Studio Code or another code editor.
- Basic understanding of HTML and CSS.
- Basic knowledge of browser testing.
Step 1: Install Node.js
Download and install the current supported Node.js LTS version from the official website.
Verify the installation:
node -v
npm -v
Both commands should display installed version numbers.
Step 2: Create a project
Create a folder for the automation project:
mkdir playwright-test-runner
cd playwright-test-runner
Initialize the Node.js project:
npm init -y
This creates a package.json file that manages project dependencies and scripts.
Step 3: Install Playwright Test
Install the test runner as a development dependency:
npm install -D @playwright/test
Install the browser binaries:
On Linux CI environments, you can install browsers and their system dependencies with:
npx playwright install –with-deps
Step 4: Verify the installation
Run:
npx playwright –version
You can also check the available commands:
npx playwright –help
Your JavaScript automation project is now ready.
4. Project Structure and playwright.config.js
A good folder structure makes an automation project easier to maintain as the number of test cases increases.
Create the following structure:
playwright-test-runner/
│
├── tests/
│ ├── homepage.spec.js
│ ├── login.spec.js
│ └── search.spec.js
│
├── pages/
│ └── LoginPage.js
│
├── test-data/
│ └── users.json
│
├── playwright.config.js
├── package.json
└── .gitignore
Understanding the folders
- tests/: Contains automated test cases.
- pages/: Contains reusable page objects.
- test-data/: Stores test data.
- playwright.config.js: Stores test runner configuration.
- package.json: Manages dependencies and npm scripts.
Configure playwright.config.js
Create a file named playwright.config.js in the root folder.
const { defineConfig } = require(‘@playwright/test’);
module.exports = defineConfig({
testDir: ‘./tests’,
timeout: 30000,
expect: {
timeout: 5000
},
fullyParallel: true,
forbidOnly: !!process.env.CI,
retries: process.env.CI ? 2 : 0,
workers: process.env.CI ? 2 : undefined,
reporter: [
[‘list’],
[‘html’, { open: ‘never’ }]
],
use: {
baseURL: ‘https://example.com’,
headless: true,
screenshot: ‘only-on-failure’,
video: ‘retain-on-failure’,
trace: ‘retain-on-failure’
},
projects: [
{
name: ‘chromium’,
use: {
browserName: ‘chromium’
}
}
]
});
Important configuration properties
| Property | Purpose |
| testDir | Defines the test folder |
| timeout | Sets the maximum test duration |
| expect.timeout | Sets the default assertion timeout |
| fullyParallel | Allows tests to run independently in parallel |
| retries | Defines retry attempts |
| workers | Controls parallel worker processes |
| reporter | Defines test report formats |
| baseURL | Sets the default application URL |
| screenshot | Controls screenshot capture |
| video | Controls video recording |
| trace | Controls trace collection |
The baseURL option allows tests to use relative paths such as /login instead of repeating the complete application URL.
For a multi-browser project, you can add Firefox and WebKit projects to the configuration.
5. Writing and Executing Tests Using test() and expect()
The test() and expect() functions are the foundation of Playwright Test.
- test() defines an automated test.
- expect() verifies the expected result.
Create tests/homepage.spec.js.
const { test, expect } = require(‘@playwright/test’);
test(‘verify homepage title’, async ({ page }) => {
await page.goto(‘/’);
await expect(page).toHaveTitle(/Example Domain/);
});
Understanding the test
- Import test and expect from @playwright/test.
- Use test() to define a test case.
- Receive the page fixture.
- Navigate to the homepage.
- Use expect() to verify the page title.
Notice that page.goto() and expect() use await because they return promises.
Create multiple test cases
You can write multiple tests in one specification file.
const { test, expect } = require(‘@playwright/test’);
test(‘verify homepage URL’, async ({ page }) => {
await page.goto(‘/’);
await expect(page).toHaveURL(/example\.com/);
});
test(‘verify heading is visible’, async ({ page }) => {
await page.goto(‘/’);
await expect(
page.getByRole(‘heading’, { name: ‘Example Domain’ })
).toBeVisible();
});
Execute test cases
Run all tests:
npx playwright test
Run one test file:
npx playwright test tests/homepage.spec.js
Run tests with a specific title:
npx playwright test -g “verify homepage title
Run tests in headed mode:
npx playwright test –headed
Run tests using a specific project:
npx playwright test –project=chromium
The test runner displays the execution results in the terminal.
6. Fixtures and Hooks in Playwright Test
Fixtures and hooks are important features of the playwright javascript test runner. They help create reusable test environments and avoid repeating setup code.
What are fixtures?
Fixtures provide the resources required by a test.
Some commonly used built-in fixtures include:
| Fixture | Purpose |
| page | Provides a browser page |
| context | Provides an isolated browser context |
| browser | Provides a browser instance |
| request | Provides an API request context |
Example using the page fixture:
const { test, expect } = require(‘@playwright/test’);
test(‘verify website heading’, async ({ page }) => {
await page.goto(‘/’);
await expect(
page.getByRole(‘heading’, { name: ‘Example Domain’ })
).toBeVisible();
});
You do not need to manually launch a browser or create a page when using the standard Playwright Test fixtures.
The runner manages their lifecycle.
What are hooks?
Hooks execute setup or cleanup operations at specific points in the test lifecycle.
Common hooks include:
- beforeEach()
- afterEach()
- beforeAll()
- afterAll()
beforeEach(): Executes before each test in the relevant scope.
const { test, expect } = require(‘@playwright/test’);
test.beforeEach(async ({ page }) => {
await page.goto(‘/’);
});
test(‘verify page title’, async ({ page }) => {
await expect(page).toHaveTitle(/Example Domain/);
});
test(‘verify page heading’, async ({ page }) => {
await expect(
page.getByRole(‘heading’, { name: ‘Example Domain’ })
).toBeVisible();
});
Both tests navigate to the homepage through the beforeEach() hook.
afterEach(): Executes after each test.
test.afterEach(async ({ page }, testInfo) => {
console.log(‘Completed test:’, testInfo.title);
});
beforeAll(): Executes once before tests in its relevant scope.
test.beforeAll(async () => {
console.log(‘Starting test group’);
});
afterAll(): Executes once after tests in its relevant scope.
test.afterAll(async () => {
console.log(‘Finished test group’);
});
A useful distinction: beforeAll() and afterAll() are appropriate for shared setup and cleanup, but they do not provide a fresh page fixture for each test. Use beforeEach() when each test needs its own page navigation or setup.
7. Assertions, Parallel Execution, Retries, and Test Isolation
These features help make automated tests more reliable and efficient.
Playwright assertions
Assertions verify whether the actual application behavior matches the expected behavior.
Common assertions include:
await expect(page).toHaveTitle(‘Dashboard’);
await expect(page).toHaveURL(/dashboard/);
await expect(page.getByText(‘Welcome’)).toBeVisible();
await expect(page.getByRole(‘button’, {
name: ‘Submit’
})).toBeEnabled();
await expect(page.locator(‘.error-message’)).toHaveText(
‘Invalid username’
);
Playwright provides web-first assertions. They automatically retry until the expected condition is met or the assertion timeout is reached.
For example:
await expect(
page.getByRole(‘heading’, { name: ‘Dashboard’ })
).toBeVisible();
This is generally more reliable than checking visibility immediately with a one-time evaluation.
Parallel execution
Parallel execution allows independent tests to run at the same time.
In playwright.config.js:
module.exports = {
fullyParallel: true,
workers: 4
};
Alternatively, execute tests with a specific number of workers:
npx playwright test –workers=4
Parallel execution can reduce execution time, but tests must not depend on shared mutable data or execution order.
Retries
Retries allow failed tests to execute again.
Configure retries:
retries: 2
Or use a command:
npx playwright test –retries=2
Retries are useful for identifying intermittent failures. However, they should not replace fixing the actual cause of flaky tests.
Test isolation
Playwright Test creates a new browser context for each test using the standard page fixture.
This means cookies, local storage, and session data are isolated between tests by default.
For example, one test can log in while another starts with a clean browser context.
Avoid sharing mutable application state between parallel tests. Use unique test data and clean up records when necessary.
8. HTML Reporting, Screenshots, Videos, and Traces
Reporting helps QA Engineers understand test execution results and investigate failures.
HTML reporter
Configure the HTML reporter:
reporter: [
[‘list’],
[‘html’, { open: ‘never’ }]
]
After execution, open the report:
npx playwright show-report
The HTML report provides test results, failure details, and links to available attachments.
Screenshots
Capture screenshots when a test fails:
use: {
screenshot: ‘only-on-failure’
}
You can also capture a screenshot manually:
await page.screenshot({
path: ‘homepage.png’,
fullPage: true
});
Videos
Record videos for failed tests:
use: {
video: ‘retain-on-failure’
}
Traces
Trace files help investigate browser actions, network activity, and errors.
Configure:
use: {
trace: ‘retain-on-failure’
}
Open a trace:
npx playwright show-trace test-results/example-trace.zip
You can also debug a test using:
npx playwright test –debug
Or open the Playwright Inspector:
PWDEBUG=1 npx playwright test
On Windows PowerShell, use:
$env:PWDEBUG=”1″
npx playwright test
Traces are especially useful when a test passes locally but fails in a CI environment.
9. Complete Real-World JavaScript Test Runner Example
Let’s build a small login automation project using Playwright Test.
We will use the public practice website:
The example verifies successful login and invalid login behavior.
Step 1: Configure the application URL
Update playwright.config.js:
const { defineConfig } = require(‘@playwright/test’);
module.exports = defineConfig({
testDir: ‘./tests’,
timeout: 30000,
expect: {
timeout: 5000
},
reporter: [
[‘list’],
[‘html’, { open: ‘never’ }]
],
use: {
baseURL: ‘https://the-internet.herokuapp.com’,
browserName: ‘chromium’,
headless: true,
screenshot: ‘only-on-failure’,
video: ‘retain-on-failure’,
trace: ‘retain-on-failure’
}
});
Step 2: Create a Login Page Object
Create pages/LoginPage.js.
class LoginPage {
constructor(page) {
this.page = page;
this.username = page.locator(‘#username’);
this.password = page.locator(‘#password’);
this.loginButton = page.locator(‘button[type=”submit”]’);
this.flashMessage = page.locator(‘#flash’);
}
async open() {
await this.page.goto(‘/login’);
}
async login(username, password) {
await this.username.fill(username);
await this.password.fill(password);
await this.loginButton.click();
}
}
module.exports = { LoginPage };
This page object stores the locators and reusable login actions in one place.
Step 3: Create login test cases
Create tests/login.spec.js.
const { test, expect } = require(‘@playwright/test’);
const { LoginPage } = require(‘../pages/LoginPage’);
test.describe(‘Login functionality’, () => {
let loginPage;
test.beforeEach(async ({ page }) => {
loginPage = new LoginPage(page);
await loginPage.open();
});
test(‘successful login’, async ({ page }) => {
await loginPage.login(
‘tomsmith’,
‘SuperSecretPassword!’
);
await expect(page).toHaveURL(/secure/);
await expect(
page.getByRole(‘heading’, { name: ‘Secure Area’ })
).toBeVisible();
});
test(‘invalid login’, async () => {
await loginPage.login(‘wronguser’, ‘wrongpassword’);
await expect(loginPage.flashMessage).toContainText(
‘Your username is invalid!’
);
});
});
The example uses the practice site’s commonly published test credentials. If the external site changes, update the credentials or selectors accordingly.
Step 4: Add npm scripts
Update the scripts section of package.json:
{
“scripts”: {
“test”: “playwright test”,
“test:headed”: “playwright test –headed”,
“test:debug”: “playwright test –debug”,
“test:report”: “playwright show-report”
}
}
You can now run:
npm test
Run in headed mode:
npm run test:headed
View the report:
npm run test:report
This practical example demonstrates how a test runner, page objects, fixtures, hooks, and assertions work together.
10. GitHub Actions and Jenkins CI/CD Integration
Modern QA engineering teams execute automated tests as part of CI/CD pipelines.
This helps identify application defects before changes reach production.
GitHub Actions integration
Create the following file:
.github/workflows/playwright.yml
name: Playwright Tests
on:
push:
branches: [main]
pull_request:
branches: [main]
jobs:
test:
runs-on: ubuntu-latest
steps:
– name: Checkout repository
uses: actions/checkout@v4
– name: Setup Node.js
uses: actions/setup-node@v4
with:
node-version: lts/*
cache: npm
– name: Install dependencies
run: npm ci
– name: Install Playwright browsers
run: npx playwright install –with-deps chromium
– name: Run Playwright tests
run: npx playwright test
– name: Upload HTML report
if: always()
uses: actions/upload-artifact@v4
with:
name: playwright-report
path: playwright-report/
retention-days: 30
– name: Upload test results
if: always()
uses: actions/upload-artifact@v4
with:
name: playwright-test-results
path: test-results/
retention-days: 30
The workflow installs dependencies, downloads Chromium, executes tests, and uploads reports even if the test step fails.
Ensure that package-lock.json is committed so that npm ci can install the locked dependencies.
Jenkins integration
You can also execute Playwright tests using Jenkins.
Create a Jenkinsfile:
pipeline {
agent any
stages {
stage(‘Checkout’) {
steps {
checkout scm
}
}
stage(‘Install Dependencies’) {
steps {
sh ‘npm ci’
}
}
stage(‘Install Browsers’) {
steps {
sh ‘npx playwright install –with-deps chromium’
}
}
stage(‘Run Tests’) {
steps {
sh ‘npx playwright test’
}
}
}
post {
always {
archiveArtifacts(
artifacts: ‘playwright-report/**,test-results/**’,
allowEmptyArchive: true
)
}
}
}
The Jenkins agent must have a compatible Node.js environment and the system dependencies required by the selected browser.
For larger projects, teams can divide test suites across multiple CI jobs and publish reports centrally.
11. Common Errors, Troubleshooting, and Best Practices
Beginners may face errors while configuring and executing the playwright javascript test runner.
Here are common issues and practical solutions.
| Error or Problem | Possible Cause | Solution |
| Playwright command not found | Package not installed | Run npm install -D @playwright/test |
| Executable doesn’t exist | Browser binaries missing | Run npx playwright install |
| Test timeout | Slow application or incorrect locator | Inspect trace and increase timeout only when justified |
| Element not found | Incorrect locator | Use reliable role, label, or test ID locators |
| Test passes locally but fails in CI | Environment differences | Check browser dependencies, environment variables, and traces |
| Flaky tests | Shared state or unstable synchronization | Isolate data and use web-first assertions |
| HTML report not opening | Report not generated or wrong directory | Run tests and then npx playwright show-report |
Best practices
1. Use meaningful test names
Write test names that clearly describe the expected behavior.
2. Prefer user-facing locators
Use getByRole(), getByLabel(), and getByTestId() where appropriate.
3. Avoid fixed waits
Avoid unnecessary commands such as:
await page.waitForTimeout(5000);
Prefer a condition-based assertion:
await expect(
page.getByText(‘Login successful’)
).toBeVisible();
4. Keep tests independent
Do not make one test depend on another test’s execution order.
5. Use Page Object Model when appropriate
Move repeated page interactions into reusable page classes.
6. Use retries carefully
Retries help identify intermittent failures, but investigate why tests fail instead of relying on retries to hide defects.
7. Protect credentials
Store sensitive credentials in environment variables or a secure CI secret store. Do not commit passwords or authentication state to Git.
8. Review test reports
Use HTML reports and traces to identify the actual failure instead of changing timeouts without investigation.
Interview and placement tips for Indian QA Engineers and SDETs
For QA Automation Engineer and SDET interviews, prepare to explain the difference between Playwright and Playwright Test.
You should also be comfortable answering questions such as:
- What is a test runner?
- What is the difference between test() and expect()?
- What are fixtures in Playwright?
- What is the difference between beforeEach() and beforeAll()?
- How does Playwright achieve test isolation?
- How do you configure parallel execution?
- How do retries work?
- How do you debug a failed test using traces?
- How do you execute Playwright tests in Jenkins or GitHub Actions?
For practical interview rounds, be ready to create a small test project, write login tests, use assertions, configure a reporter, and explain how you would investigate a flaky test.
A strong SDET candidate should explain not only the syntax but also why a particular test design is reliable and maintainable.
12. FAQs About Playwright JavaScript Test Runner
1. What is playwright javascript test runner?
Playwright JavaScript Test Runner refers to Playwright Test, the test execution framework used to create, organize, execute, and report browser automation tests written in JavaScript. It provides fixtures, hooks, assertions, retries, parallel execution, and reporting.
2. How do I get started with playwright javascript test runner?
Install Node.js, create a project using npm init -y, install @playwright/test, and download browsers using npx playwright install. Create a playwright.config.js file and write your first test using test() and expect().
3. What are the benefits of playwright javascript test runner?
Its main benefits include automatic waiting, isolated browser contexts, reusable fixtures, parallel execution, retry support, built-in assertions, and detailed HTML reports. These features help teams build maintainable end-to-end testing suites.
4. Is Playwright Test different from Selenium?
Yes. Playwright Test is a test runner designed for Playwright browser automation. Selenium is a browser automation ecosystem that is commonly combined with external test frameworks such as JUnit, TestNG, or pytest.
5. Can beginners use Playwright Test with JavaScript?
Yes. Beginners who understand basic JavaScript, asynchronous functions, and promises can start with Playwright Test. Its fixtures and built-in assertions make it easier to organize tests.
6. How can I run Playwright tests in parallel?
Set the workers option in playwright.config.js or use the –workers command-line option. Make sure tests are independent and do not conflict over shared application data.
7. How do I generate an HTML report?
Configure the HTML reporter in playwright.config.js, execute the tests, and run npx playwright show-report to open the generated report.
