How to Run Playwright Tests: Every Command You Need

This guide covers how to run Playwright tests every way you will need: the whole suite, one file, one test by line number or title, headed, in UI Mode, in debug mode, on one browser, from VS Code and in CI. Each npx playwright test command below was checked against npx playwright test --help on Playwright 1.62, so there are no made-up flags.

If Playwright isn't set up yet, start with how to install Playwright. You need a project created with npm init playwright@latest and at least one test file.

The Example Project

All commands below use these two files and this config. Copy them into a fresh project to follow along.

const { test, expect } = require('@playwright/test');

test('has title', async ({ page }) => {
  await page.goto('https://playwright.dev/');
  await expect(page).toHaveTitle(/Playwright/);
});

test('get started link', async ({ page }) => {
  await page.goto('https://playwright.dev/');
  await page.getByRole('link', { name: 'Get started' }).click();
  await expect(page.getByRole('heading', { name: 'Installation' })).toBeVisible();
});

const { test, expect } = require('@playwright/test');

test('valid user can log in', async ({ page }) => {
  await page.goto('https://the-internet.herokuapp.com/login');
  await page.getByLabel('Username').fill('tomsmith');
  await page.getByLabel('Password').fill('SuperSecretPassword!');
  await page.getByRole('button', { name: 'Login' }).click();
  await expect(page.getByText('You logged into a secure area!')).toBeVisible();
});

test('logout returns to the login page', async ({ page }) => {
  await page.goto('https://the-internet.herokuapp.com/login');
  await page.getByLabel('Username').fill('tomsmith');
  await page.getByLabel('Password').fill('SuperSecretPassword!');
  await page.getByRole('button', { name: 'Login' }).click();
  await page.getByRole('link', { name: 'Logout' }).click();
  await expect(page).toHaveURL(/\/login/);
});

const { defineConfig, devices } = require('@playwright/test');

module.exports = defineConfig({
  testDir: './tests',
  retries: process.env.CI ? 2 : 0,
  workers: process.env.CI ? 1 : undefined,
  reporter: 'html',
  use: { trace: 'on-first-retry' },
  projects: [
    { name: 'chromium', use: { ...devices['Desktop Chrome'] } },
    { name: 'firefox', use: { ...devices['Desktop Firefox'] } },
    { name: 'webkit', use: { ...devices['Desktop Safari'] } },
  ],
});

Four tests times three browser projects means a full run is 12 tests.

How to Run Playwright Tests: All, One File, One Test

To run Playwright tests, open a terminal in your project folder and use the npx playwright test command:

1. Run every test: npx playwright test
2. Run one file: npx playwright test tests/login.spec.js
3. Run a single test by line: npx playwright test tests/login.spec.js:11
4. Run a single test by title: npx playwright test -g "valid user can log in"
5. Watch the browser: add --headed, or use --ui for UI Mode

Run all tests

npx playwright test

Playwright finds every *.spec.js / *.test.js file under testDir, runs them headless in parallel across all projects, and prints results. With the html reporter, it opens the report automatically when a test fails.

Run one file

npx playwright test tests/login.spec.js
npx playwright test login            # any file whose path matches "login"
npx playwright test login example    # several filters

File arguments are regular expressions matched against the file path, so login is enough. It also means login would match login-admin.spec.js; use the full path when names overlap.

Run a single Playwright test by line number

npx playwright test tests/login.spec.js:11

This runs only the test declared on line 11: logout returns to the login page. It's what the VS Code extension does when you click the green arrow next to a test.

Run a single test by title with -g

npx playwright test -g "valid user can log in"
npx playwright test --grep "log in"          # regex, partial match
npx playwright test --grep-invert "logout"   # everything except matching tests

-g also matches tags, which is how you run groups like @smoke. The full pattern guide is in Playwright tags.

Run one test from the code with test.only

const { test, expect } = require('@playwright/test');

test.only('only this test runs', async ({ page }) => {
  await page.goto('https://demo.playwright.dev/todomvc');
  await expect(page.getByPlaceholder('What needs to be done?')).toBeVisible();
});

test('this one is skipped while test.only exists', async ({ page }) => {
  await page.goto('https://demo.playwright.dev/todomvc');
});

Handy while writing a test, risky if it gets committed: the whole CI run would execute just one test. Add --forbid-only to your CI command so the run fails if a test.only slips through.

Headed, UI Mode and Debug Mode

npx playwright test --headed      # show the browser window
npx playwright test --ui          # interactive UI Mode
npx playwright test --debug       # step through with the Playwright Inspector
npx playwright test login.spec.js:3 --debug   # debug one test

• --headed runs exactly the same tests with visible browser windows. Good for a quick look; tests still run at full speed.
• --ui opens UI Mode: a test tree, watch mode, time-travel through every step, and a locator picker. It's the best way to work on tests day to day. See the Playwright UI Mode tutorial.
• --debug opens the Playwright Inspector and pauses on the first action. Per the help text it's a shortcut for PWDEBUG=1 plus --timeout=0 --max-failures=1 --headed --workers=1. More techniques in how to debug Playwright tests.

Playwright Test Command Options You Will Use

Pick browsers with --project

npx playwright test --project=chromium
npx playwright test --project=chromium --project=webkit

--project uses the name values from your config, so it works for any project, not only browsers: mobile, api, staging. It also accepts a * wildcard.

Speed and stability: --workers, --retries, --repeat-each

npx playwright test --workers=4          # 4 parallel workers
npx playwright test --workers=1          # one at a time
npx playwright test --retries=2          # retry failed tests up to 2 times
npx playwright test --repeat-each=10     # run each test 10 times
npx playwright test -x                   # stop after the first failure
npx playwright test --max-failures=3     # stop after 3 failures

--workers also takes a percentage such as 50% of CPU cores (the default). --repeat-each is the quickest way to prove a test is flaky: if --repeat-each=20 passes 20 times, it's probably stable. The parallel testing guide explains how workers split the work.

Re-run only what failed: --last-failed

npx playwright test --last-failed

Playwright remembers failures from the previous run and runs only those. If the previous run was all green, there is nothing to re-run and you get No tests found.

Run only changed files: --only-changed

npx playwright test --only-changed          # uncommitted changes
npx playwright test --only-changed=main     # changes since the main branch

Git only. Useful on a pull request to run the tests you touched first, before the full suite.

See what would run: --list

npx playwright test --project=chromium --list

Listing tests:
  [chromium] › example.spec.js:3:1 › has title
  [chromium] › example.spec.js:8:1 › get started link
  [chromium] › login.spec.js:3:1 › valid user can log in
  [chromium] › login.spec.js:11:1 › logout returns to the login page
Total: 4 tests in 2 files

Always check a new filter with --list before you put it in CI.

Change the output: --reporter

npx playwright test --reporter=list
npx playwright test --reporter=dot
npx playwright test --reporter=line,html     # comma-separated for several
npx playwright show-report                   # open the last HTML report

Built-in reporters: list, line, dot, json, junit, null, github, html, blob.

Other flags worth knowing

Run Playwright Tests in VS Code

Install the Playwright Test for VSCode extension from Microsoft. Once it's installed:

• A green play button appears next to every test(). Click it to run that one test; right-click for Debug Test.
• The Testing sidebar lists every file and test. Run all, one file, or one test from there.
• The Playwright panel lets you choose projects (browsers), turn on Show browser, and record new tests.
• Set a breakpoint in the editor and use Debug Test to stop on it, with live locator highlighting in the browser.

The extension runs the same npx playwright test under the hood, so results match the terminal.

Run Playwright Tests in CI (GitHub Actions)

npm init playwright@latest can generate this workflow for you. The important parts: install browsers with system dependencies, run the tests, and always upload the report.

name: Playwright Tests
on:
  push:
    branches: [ main ]
  pull_request:
    branches: [ main ]

jobs:
  test:
    timeout-minutes: 60
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: lts/*
      - run: npm ci
      - run: npx playwright install --with-deps
      - run: npx playwright test --forbid-only
      - uses: actions/upload-artifact@v4
        if: ${{ !cancelled() }}
        with:
          name: playwright-report
          path: playwright-report/
          retention-days: 30

GitHub Actions sets CI=true, so the config above switches to 2 retries and 1 worker automatically. For caching, sharding and secrets, see the Playwright GitHub Actions CI/CD guide.

npx playwright Commands: Quick Reference

npx playwright test is one of several commands. These are the ones you will use most:

New to writing the tests themselves? 20 Playwright script examples gives you copy-paste tests to run with every command on this page.

Already run tests daily and want to check the gaps? The Playwright Automation Practice Tests are exam-style questions with explanations on the CLI, configuration, tags and fixtures.

Frequently Asked Questions

Meet Your Instructor

Asim Noaman

Senior QA Automation Engineer & AI Testing Specialist

With years of hands-on experience building test automation frameworks for production applications, Asim specializes in combining traditional QA methodologies with cutting-edge AI tools. He has helped teams adopt Playwright and AI-driven testing workflows to ship faster with fewer bugs.

Udemy Instructor Published course author

Playwright + AI Expert Specialized in AI-powered QA

Production Experience Enterprise-grade frameworks

Connect on LinkedIn