How to Run Playwright Tests – Complete Guide with Commands & Examples

Playwright Commands for Running Tests (Complete Guide with Examples)

Running your Playwright test suite efficiently is one of the most important skills every automation engineer should master. Whether you're executing a single test during development, running smoke tests before deployment, debugging failures, or executing thousands of tests in parallel inside a CI/CD pipeline, Playwright provides a rich collection of command-line options that make test execution simple and powerful.

In this tutorial, you'll learn all the essential Playwright commands used to run tests in real-world automation projects. Every command includes examples and explanations so you can immediately apply them in your own framework.

Why Learn Playwright Test Commands?

Writing automated tests is only half of the job. Professional SDETs spend a significant amount of time executing tests in different ways depending on the situation. For example:

• Running only smoke tests before deployment
• Debugging a single failing test
• Executing regression tests in parallel
• Running tests on Chrome, Firefox, and WebKit
• Rerunning failed tests only
• Generating HTML or JUnit reports
• Running tests across multiple CI/CD machines

Understanding these commands can dramatically improve your productivity and reduce execution time.

Run All Tests

The most basic Playwright command executes every test inside your project.

npx playwright test

By default:

• All test files are discovered automatically.
• Tests run headlessly, meaning no browser window is displayed.
• All configured projects (Chromium, Firefox, WebKit, etc.) execute unless configured otherwise.

This command is commonly used inside CI/CD pipelines.

Run a Specific Test File

Instead of executing the entire suite, you can run a single test file.

npx playwright test tests/login.spec.ts

This is useful when you're working on one feature and want faster feedback. In a project like:

tests/
    login.spec.ts
    products.spec.ts
    checkout.spec.ts

Only login.spec.ts will execute.

Run Multiple Test Files

You can specify multiple files in a single command.

npx playwright test tests/login.spec.ts tests/products.spec.ts

This is useful when related features (Login, Product Search, Shopping Cart) need to be validated together without running the complete regression suite.

Run Tests from a Directory

Playwright can execute every test inside a folder.

npx playwright test tests/api

tests
│
├── api
│   ├── createUser.spec.ts
│   ├── updateUser.spec.ts
│   └── deleteUser.spec.ts

Only API tests will execute. This approach is extremely useful when separating UI Tests, API Tests, Mobile Tests, and Performance Tests.

Run a Test by Title

Sometimes you only want one specific test inside a file.

test('user can log in successfully', async ({ page }) => {
    await page.goto('/login');
});

Run it using:

npx playwright test -g "user can log in"

or

npx playwright test --grep "user can log in"

The --grep option filters tests whose titles match the given text or regular expression. This is incredibly useful during debugging because it avoids executing unrelated tests.

Exclude Tests by Title or Tag

Sometimes you need to skip slow or unstable tests. Playwright provides the --grep-invert option.

npx playwright test --grep-invert "@slow"

All tests tagged with @slow will be excluded. This is particularly useful in CI pipelines where you only want fast feedback.

Run Smoke Tests

Tags make organizing tests much easier.

test('user login', { tag: '@smoke' }, async ({ page }) => {
    await page.goto('/login');
});

Run all smoke tests:

npx playwright test --grep "@smoke"

Common enterprise tags include @smoke, @regression, @sanity, @api, @ui, @critical, and @mobile. Instead of maintaining separate folders, many enterprise automation frameworks organize execution using tags.

Run Tests in Headed Mode

Normally Playwright executes tests without opening a browser window. If you want to see browser activity:

npx playwright test --headed

• Observe browser actions
• Verify animations
• Understand failures visually
• Demonstrate automation during presentations

Headed mode is commonly used while developing new test cases.

Run Tests in Debug Mode

One of Playwright's best features is its built-in debugger.

npx playwright test --debug

Debug mode automatically opens the browser, launches Playwright Inspector, executes slowly, allows stepping through commands, lets you inspect locators, and enables pause and resume. This is the preferred approach for troubleshooting complex automation failures.

Run Tests in UI Mode

Playwright also includes a powerful graphical interface.

npx playwright test --ui

• Interactive test explorer
• Watch mode
• Timeline view
• DOM snapshots
• Network requests
• Locator inspection
• Retry failed tests
• Live debugging

For beginners, UI Mode is one of the easiest ways to learn Playwright because everything is visual.

Run Tests on a Specific Browser

Playwright supports multiple browser engines.

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

The project name must match the configuration inside playwright.config.ts.

projects: [
    { name: 'chromium' },
    { name: 'firefox' },
    { name: 'webkit' }
]

Cross-browser testing is one of Playwright's strongest features and helps ensure your application behaves consistently across modern browsers.

Run Multiple Browser Projects

You can execute more than one browser in a single command.

npx playwright test --project=chromium --project=firefox

This is common in CI pipelines where teams validate compatibility across multiple browsers simultaneously.

Run Tests with One Worker

Workers determine how many tests execute in parallel. Run sequentially:

npx playwright test --workers=1

• Debugging
• Tests share database data
• Tests modify common resources
• Execution order matters

Although slower, sequential execution eliminates issues caused by parallel processing.

Run Tests with Multiple Workers

To speed up execution:

npx playwright test --workers=4

Or use a percentage of available CPU cores:

npx playwright test --workers=50%

Parallel execution significantly reduces regression testing time and is widely used in enterprise automation frameworks.

Stop After a Number of Failures

Sometimes it's unnecessary to continue after several failures.

npx playwright test --max-failures=3

Playwright stops execution after three failed tests. This saves valuable CI/CD time when a deployment is already known to be unstable.

Run Only Previously Failed Tests

Instead of rerunning everything:

npx playwright test --last-failed

Only tests that failed during the previous execution are rerun. This command is especially useful during bug fixing because it shortens the feedback cycle.

Repeat Every Test

Flaky tests often pass sometimes and fail at other times. To identify unstable behavior:

npx playwright test --repeat-each=5

Each test executes five times. If failures occur intermittently, the test is likely flaky and needs investigation.

Retry Failed Tests

Playwright can automatically retry failed tests.

npx playwright test --retries=2

Each failed test gets two additional attempts. Retries are useful when occasional environmental issues (network latency, temporary API outages, or browser startup delays) cause non-deterministic failures. However, excessive retries should not be used to hide genuine defects.

Shard Tests Across Multiple Machines

Large organizations often distribute execution across several CI agents.

# Machine 1
npx playwright test --shard=1/3

# Machine 2
npx playwright test --shard=2/3

# Machine 3
npx playwright test --shard=3/3

Each machine runs one-third of the suite. Sharding dramatically reduces execution time for large regression suites and is commonly used with GitHub Actions, Azure DevOps, Jenkins, GitLab CI, and CircleCI.

List Tests Without Running Them

To view discovered tests:

npx playwright test --list

• Verifying test discovery
• Checking grep filters
• Validating project configuration
• Reviewing execution scope before running a large suite

Run Tests with Different Reporters

Playwright supports multiple built-in reporters.

npx playwright test --reporter=list
npx playwright test --reporter=line
npx playwright test --reporter=dot
npx playwright test --reporter=html
npx playwright test --reporter=json
npx playwright test --reporter=junit

When Should You Use Each Reporter?

• list — Local development with detailed output
• line — Compact console output
• dot — Large regression suites with minimal logs
• html — Interactive execution reports for developers and testers
• json — Integration with dashboards or custom reporting tools
• junit — CI/CD systems such as Jenkins, Azure DevOps, Bamboo, or GitHub Actions

The HTML reporter is one of the most popular because it provides screenshots, traces, execution details, and a clean interface for investigating failures.

Best Practices for Running Playwright Tests

• Use tags (@smoke, @regression, @api) to organize test execution.
• Run smoke tests before every deployment.
• Execute full regression suites in parallel using multiple workers.
• Use --debug or --ui when investigating failures.
• Run headed mode only during development or demonstrations.
• Configure retries carefully and fix flaky tests instead of relying on retries.
• Use HTML reports for local debugging and JUnit reports for CI/CD integrations.
• Leverage sharding for very large test suites to reduce execution time across multiple build agents.

Final Thoughts

Playwright offers one of the most powerful and flexible test runners available for modern web automation. From executing a single test during development to running thousands of tests across multiple browsers and distributed CI/CD environments, its command-line interface provides everything needed for fast, reliable, and scalable test execution.

Mastering these commands will help you debug failures more efficiently, organize your automation framework with tags and projects, optimize execution using workers and sharding, and generate professional reports for your development and QA teams. Whether you're a beginner learning Playwright or an experienced SDET building enterprise automation frameworks, understanding these execution commands is an essential skill that will improve both your productivity and the reliability of your test automation strategy.