Playwright JavaScript Test Runner: Step-by-Step Guide (2026)

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.

PlaywrightPlaywright Test
Browser automation libraryEnd-to-end test runner
Provides browser APIsOrganizes and executes test cases
Supports browser interactionsProvides test() and expect()
Can be used for custom automation scriptsProvides fixtures and hooks
Controls browser pages and contextsSupports 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.

4. Parallel execution

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.

https://nodejs.org

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:

npx playwright install

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

PropertyPurpose
testDirDefines the test folder
timeoutSets the maximum test duration
expect.timeoutSets the default assertion timeout
fullyParallelAllows tests to run independently in parallel
retriesDefines retry attempts
workersControls parallel worker processes
reporterDefines test report formats
baseURLSets the default application URL
screenshotControls screenshot capture
videoControls video recording
traceControls 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

  1. Import test and expect from @playwright/test.
  2. Use test() to define a test case.
  3. Receive the page fixture.
  4. Navigate to the homepage.
  5. 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:

FixturePurpose
pageProvides a browser page
contextProvides an isolated browser context
browserProvides a browser instance
requestProvides 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:

https://the-internet.herokuapp.com/login

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 ProblemPossible CauseSolution
Playwright command not foundPackage not installedRun npm install -D @playwright/test
Executable doesn’t existBrowser binaries missingRun npx playwright install
Test timeoutSlow application or incorrect locatorInspect trace and increase timeout only when justified
Element not foundIncorrect locatorUse reliable role, label, or test ID locators
Test passes locally but fails in CIEnvironment differencesCheck browser dependencies, environment variables, and traces
Flaky testsShared state or unstable synchronizationIsolate data and use web-first assertions
HTML report not openingReport not generated or wrong directoryRun 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.

Leave a Comment

Your email address will not be published. Required fields are marked *