Getting Started with Playwright: Installation, Setup, and Your First Test

Introduction

Playwright has become the default choice for teams building reliable end-to-end tests for modern web applications. Developed by Microsoft and maintained by many of the same engineers who originally built Puppeteer, Playwright delivers cross-browser automation across Chromium, Firefox, and WebKit with a single API — and does so with dramatically less flakiness than legacy frameworks like Selenium or Cypress.

This tutorial is a complete, hands-on setup guide. By the end of it you will have Playwright installed on your machine, a working test project structured the way real production teams organise theirs, your first test executing across three browsers, an HTML report open in your browser, and a clear understanding of what to learn next.

Every command in this guide has been verified on macOS, Windows 11, and Ubuntu 22.04 with Node.js 20. If you follow along top to bottom you should be running your first passing test in under ten minutes.

Why Playwright Matters in 2026

Modern web applications are dynamic, network-heavy, and rendered by frameworks like React, Next.js, Angular, and Svelte. Older automation tools were designed for server-rendered HTML and struggle with hydration delays, streaming responses, and shadow DOM. Playwright was built from the ground up to handle these realities.

• True cross-browser support — one API driving Chromium, Firefox, and WebKit engines.
• Auto-waiting on every action — no more sleep() or manual polling.
• First-class TypeScript support out of the box.
• Built-in HTTP client (request context) for API testing without extra libraries.
• Network interception and mocking without a proxy.
• Trace Viewer — a time-travel debugger that shows every DOM snapshot, network call, and console log for a failing test.
• Parallel and sharded execution scales linearly on CI.
• Codegen tool records interactions and generates test code.

Companies from small startups to Fortune 500 enterprises — including Microsoft, Adobe, VS Code, Disney, and many others — rely on Playwright for critical release pipelines. Learning it today is one of the highest ROI investments an automation engineer can make.

Prerequisites

Before installing Playwright, confirm you have the following:

• Node.js 18 or later (Node.js 20 LTS recommended).
• npm 9+ or an equivalent package manager (pnpm, yarn, bun).
• A code editor — Visual Studio Code with the Playwright extension is strongly recommended.
• Basic familiarity with JavaScript or TypeScript.
• Approximately 1 GB of free disk space for the three browser engines.

Verify your Node.js and npm versions:

node -v
# v20.11.0 (or newer)

npm -v
# 10.2.4 (or newer)

Step 1: Install Playwright

Create a new empty project folder and initialise it:

mkdir playwright-demo
cd playwright-demo
npm init -y

Now run Playwright's initializer. This one command scaffolds the config, downloads the three browser engines, and creates an example test file:

npm init playwright@latest

You will be prompted with four questions. The recommended answers for a modern project are:

• Do you want to use TypeScript or JavaScript? → TypeScript
• Where to put your end-to-end tests? → tests
• Add a GitHub Actions workflow? → true (creates a ready-to-run CI file)
• Install Playwright browsers? → true

The install typically takes 60–120 seconds depending on your internet connection because it downloads Chromium, Firefox, and WebKit.

Step 2: Project Structure

After the installer finishes, your project should look like this:

playwright-demo/
├── .github/
│   └── workflows/
│       └── playwright.yml
├── tests/
│   └── example.spec.ts
├── tests-examples/
│   └── demo-todo-app.spec.ts
├── playwright.config.ts
├── package.json
└── node_modules/

Two folders are created: tests holds the tests you will write, and tests-examples ships with a longer reference test you can study or delete.

Step 3: Understanding playwright.config.ts

Open playwright.config.ts. This file controls how your tests run — reporters, timeouts, retries, browsers, base URL, screenshots, and traces. The key section defines projects, which are named browser configurations:

import { defineConfig, devices } from '@playwright/test';

export default defineConfig({
  testDir: './tests',
  fullyParallel: true,
  retries: process.env.CI ? 2 : 0,
  reporter: 'html',
  use: {
    baseURL: 'https://playwright.dev',
    trace: 'on-first-retry',
    screenshot: 'only-on-failure',
  },
  projects: [
    { name: 'chromium', use: { ...devices['Desktop Chrome'] } },
    { name: 'firefox',  use: { ...devices['Desktop Firefox'] } },
    { name: 'webkit',   use: { ...devices['Desktop Safari'] } },
  ],
});

The two most useful defaults for beginners are trace: 'on-first-retry' (captures a full trace when a test flakes) and screenshot: 'only-on-failure'.

Step 4: Your First Test

Delete the placeholder example.spec.ts and create your own. We'll test the Playwright docs site because it is stable and public:

import { test, expect } from '@playwright/test';

test('Playwright docs page loads and title is correct', async ({ page }) => {
  await page.goto('https://playwright.dev/');

  await expect(page).toHaveTitle(/Playwright/);

  const getStarted = page.getByRole('link', { name: 'Get started' });
  await expect(getStarted).toBeVisible();

  await getStarted.click();
  await expect(page).toHaveURL(/.*intro/);
});

Notice three things: the test is fully async, we use await on every action and assertion, and every locator uses a role-based query (getByRole) — the recommended approach.

Step 5: Execute the Test

npx playwright test

Playwright runs the test in parallel against all three configured browsers. Typical output:

Running 3 tests using 3 workers

  ✓  [chromium] › first.spec.ts (2.1s)
  ✓  [firefox]  › first.spec.ts (2.8s)
  ✓  [webkit]   › first.spec.ts (2.4s)

  3 passed (3.4s)

Step 6: Headed Mode & UI Mode

By default Playwright runs headless (no visible browser). To watch the browser drive itself in real time:

npx playwright test --headed

For interactive debugging, UI mode is the killer feature — a browser-like control panel that lets you pick tests, watch them run, time-travel through the DOM, and re-run on file change:

npx playwright test --ui

Step 7: HTML Report & Trace Viewer

npx playwright show-report

The HTML report opens in your browser and shows every test, its steps, timings, screenshots, videos (if enabled), console logs, and network requests. For any failed test, click the trace icon to open the Trace Viewer — a step-by-step time-travel debugger with DOM snapshots at every action.

Step 8: Run on a Specific Browser

# Run only Chromium
npx playwright test --project=chromium

# Run a single test file
npx playwright test tests/first.spec.ts

# Run a single test by name (grep on title)
npx playwright test -g 'title is correct'

# Debug a single test with the Playwright Inspector
npx playwright test --debug tests/first.spec.ts

Common Pitfalls

• Forgetting to await an action or assertion — every page.* and expect() call must be awaited.
• Using page.waitForTimeout(5000) — this defeats auto-waiting and creates flaky tests. Use web-first assertions instead.
• Running tests against a URL that is not yet ready (dev server still starting). Configure webServer in playwright.config.ts to start and wait for it.
• Adding retries: 3 locally to hide flakiness. Retries mask bugs — fix the root cause in local dev, use retries only in CI.
• Mixing raw ElementHandle (page.$) with Locators. Modern Playwright is Locator-first; ElementHandles are legacy.
• Committing test-results/ and playwright-report/ to git. Add them to .gitignore.

Debugging Tips

• Run with --debug to launch the Playwright Inspector — step through actions and see the live selector.
• Use page.pause() inside a test to open the inspector at that exact line.
• Enable trace: 'on' temporarily to capture a full trace even for passing tests.
• Use npx playwright codegen https://your-site.com to record interactions and get generated code.
• Check the Locator with await expect(locator).toBeVisible() before clicking — it produces clearer failure messages than a raw click timeout.
• In CI, always upload the playwright-report folder as an artifact so you can inspect failures locally.

When to Use Playwright (and When Not To)

Great fit

• End-to-end tests for modern web apps (React, Vue, Angular, Svelte, Next.js).
• Cross-browser regression suites.
• API + UI hybrid tests using the same runner.
• Visual regression testing via toHaveScreenshot().
• Component testing for React, Vue, and Svelte components in a real browser.

Not the right tool

• Native mobile app testing — use Appium or Detox instead.
• Load or performance testing — use k6, JMeter, or Gatling.
• Unit tests for pure JS/TS logic — use Vitest or Jest.
• Testing Internet Explorer (Playwright does not support IE).

FAQ

Is Playwright free?

Yes. Playwright is fully open source under the Apache 2.0 license — free for personal and commercial use, with no paid tier or usage limits.

Which language should I use — TypeScript or JavaScript?

TypeScript. The tooling (autocomplete, refactoring, catching typos before runtime) pays for itself within a day, and the Playwright API is designed TypeScript-first.

How is Playwright different from Cypress?

Playwright supports multiple tabs, multiple origins, native browser events, WebKit, and true parallel execution across processes. Cypress runs inside the browser, which limits it to single-tab, single-origin flows. For most modern apps, Playwright is more capable.

How is Playwright different from Selenium?

Playwright is dramatically faster and less flaky because it uses the browsers' DevTools protocol directly rather than the WebDriver JSON wire protocol. It also ships batteries-included (test runner, assertions, reporter, network interception) whereas Selenium is only the automation library.

Do I need to install browsers manually?

No. npm init playwright downloads pinned versions of Chromium, Firefox, and WebKit into ~/.cache/ms-playwright, isolated from your system browsers.

Can I run Playwright in Docker?

Yes. Microsoft publishes an official image at mcr.microsoft.com/playwright with browsers and system dependencies pre-installed — ideal for CI.

Summary

You now have Playwright installed, a working project scaffold, a first test running in three browsers, and access to the HTML report and Trace Viewer. From here the natural progression is to master locators (how you identify elements), then assertions (how you verify behaviour), then the Page Object Model (how you keep tests maintainable at scale).

Playwright is not just a browser automation library — it is a complete testing platform capable of handling UI, API, visual, and component testing behind one consistent API. Every hour you invest learning it pays back many times over in reduced flakiness and faster releases.