Setup and First Test

Getting started with Playwright takes minutes, not hours. The framework ships with a CLI that scaffolds a project, installs browsers, and generates configuration — removing the setup friction that plagued earlier tools.

Installation

Playwright supports multiple languages. TypeScript/JavaScript is the primary ecosystem with the richest tooling; Python is the most common alternative in QA teams.

TypeScript (recommended)

# Create a new project and install Playwright
npm init playwright@latest

# This scaffolds:
#   playwright.config.ts   — configuration
#   tests/                 — test directory
#   tests/example.spec.ts  — sample test
#   package.json           — dependencies

Python

pip install playwright
playwright install  # downloads browser binaries

What playwright install Does

Playwright bundles its own browser binaries — specific versions of Chromium, Firefox, and WebKit that are tested against each Playwright release. This eliminates the "which ChromeDriver version matches my Chrome?" problem that Selenium teams struggle with.

Project Structure

A typical Playwright project:

project/
├── playwright.config.ts     # Test runner configuration
├── tests/
│   ├── login.spec.ts        # Test files (*.spec.ts)
│   ├── checkout.spec.ts
│   └── fixtures/            # Custom fixtures
│       └── auth.ts
├── pages/                   # Page objects
│   ├── login.page.ts
│   └── dashboard.page.ts
├── test-data/               # Test data files
└── test-results/            # Generated: traces, screenshots, videos

Your First Test

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

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

test('get started link navigates to intro', async ({ page }) => {
  await page.goto('https://playwright.dev/');
  await page.getByRole('link', { name: 'Get started' }).click();
  await expect(page).toHaveURL(/.*intro/);
});

Running Tests

# Run all tests
npx playwright test

# Run a specific file
npx playwright test tests/login.spec.ts

# Run in headed mode (see the browser)
npx playwright test --headed

# Run in UI mode (interactive debugger)
npx playwright test --ui

The Test Runner: @playwright/test

Playwright ships with its own test runner that provides features other frameworks require plugins for:

Basic Configuration

// playwright.config.ts
import { defineConfig } from '@playwright/test';

export default defineConfig({
  testDir: './tests',
  timeout: 30_000,
  retries: process.env.CI ? 2 : 0,
  workers: process.env.CI ? 4 : undefined,
  use: {
    baseURL: 'http://localhost:3000',
    screenshot: 'only-on-failure',
    trace: 'on-first-retry',
  },
  projects: [
    { name: 'chromium', use: { browserName: 'chromium' } },
    { name: 'firefox', use: { browserName: 'firefox' } },
    { name: 'webkit', use: { browserName: 'webkit' } },
  ],
});

Debugging Tools

Playwright provides multiple debugging approaches — no more guessing why a test failed.

UI Mode (--ui): Interactive timeline showing every action, network request, and DOM snapshot. The single most useful debugging tool.

Trace Viewer: Records a trace during test execution that you can replay step-by-step after the fact. Essential for CI failures.

Codegen (npx playwright codegen): Opens a browser and records your actions as test code. Useful for bootstrapping tests quickly, though the generated code usually needs cleanup.

VS Code Extension: Run, debug, and step through tests directly in the editor with breakpoints.

Python Equivalent

from playwright.sync_api import sync_playwright

with sync_playwright() as p:
    browser = p.chromium.launch()
    page = browser.new_page()
    page.goto("https://playwright.dev/")
    assert "Playwright" in page.title()
    browser.close()

# With pytest-playwright (recommended)
def test_homepage(page):
    page.goto("https://playwright.dev/")
    assert "Playwright" in page.title()

Key Takeaways

• npm init playwright@latest scaffolds a complete project in seconds
• Playwright bundles browser binaries — no driver version mismatch issues
• The built-in test runner includes parallel execution, retries, screenshots, video, and traces
• UI Mode and Trace Viewer are the primary debugging tools — use them before adding console.log
• Codegen bootstraps tests quickly; the VS Code extension integrates everything into the editor