Setup & First Test

Getting started with Playwright takes less than a minute. In this lesson, you will install Playwright, explore the project structure it generates, and write your first end-to-end test.

Installing Playwright

Create a new project or navigate to an existing one, then run the Playwright initializer:

npm init playwright@latest

The installer asks a few questions — accept the defaults for now. It will:

1. Install @playwright/test as a dev dependency.
2. Create a playwright.config.ts configuration file.
3. Generate an e2e/ folder (or tests/) with an example test.
4. Download browser binaries for Chromium, Firefox, and WebKit.

You can also install browsers separately at any time:

npx playwright install

Project Structure

After initialization, your project looks like this:

project/
├── playwright.config.ts   # Test configuration
├── tests/
│   └── example.spec.ts    # Example test file
├── tests-examples/
│   └── demo-todo-app.spec.ts
└── package.json

The playwright.config.ts file controls everything — which browsers to test, base URL, timeouts, retries, and reporter settings. Here is a minimal configuration:

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

export default defineConfig({
  testDir: './tests',
  timeout: 30_000,
  retries: 0,
  use: {
    baseURL: 'http://localhost:3000',
    trace: 'on-first-retry',
  },
  projects: [
    { name: 'chromium', use: { browserName: 'chromium' } },
  ],
});

Writing Your First Test

Create a file called tests/home.spec.ts:

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

test('homepage has correct title', async ({ page }) => {
  await page.goto('/');

  await expect(page).toHaveTitle(/My App/);
});

test('navigation links work', async ({ page }) => {
  await page.goto('/');

  await page.click('text=About');

  await expect(page).toHaveURL('/about');
  await expect(page.locator('h1')).toHaveText('About Us');
});

Each test() receives a page object — a browser tab you can interact with. The page.goto() method navigates to a URL. The expect() function makes assertions about the page state.

Running Tests

Run your tests from the terminal:

npx playwright test

This runs all tests in headless mode (no visible browser window) across the configured browsers. You will see a summary of passed and failed tests.

Headed Mode

To watch the browser while tests run, use the --headed flag:

npx playwright test --headed

This opens a real browser window so you can see every click and navigation as it happens. It is invaluable for debugging.

UI Mode

Playwright also offers an interactive UI mode for development:

npx playwright test --ui

UI mode shows each test step with a timeline, DOM snapshots, and the ability to re-run individual tests instantly. It is the best way to write and debug tests during development.

Running a Single Test File

You do not need to run the entire suite every time. Target a specific file:

npx playwright test tests/home.spec.ts

Or run a single test by title:

npx playwright test -g "homepage has correct title"

Key Takeaways

• npm init playwright@latest sets up everything you need.
• Tests live in .spec.ts files inside the test directory.
• Each test receives a page object for browser interaction.
• Use --headed to see the browser, --ui for an interactive development experience.
• Always start with a simple test that verifies your app loads before writing complex scenarios.

In the next lesson, you will learn how to find and interact with elements on the page using Playwright's powerful selector engine.