Installing Playwright: a basic guide

Goal

By the end you'll have Playwright installed in your project, a test running against your local app, and the tools to see why a test failed (a screenshot and a trace).

Playwright is an end-to-end (E2E) testing framework. It drives a real browser (Chromium, Firefox, or WebKit) the way a user would, and checks what the page shows.

Prerequisites

• Node.js (a current LTS) and npm.
• A web project you can run locally.
• A terminal open at the root of that project.

This guide covers Playwright as of October 2026.

Steps

1. Add Playwright to your project

From the root of the project:

npm init playwright@latest

It asks a few questions. Confirm or choose:

• TypeScript or JavaScript (default: TypeScript).
• The tests folder (default: tests, or e2e if tests already exists).
• Whether to add a GitHub Actions workflow (optional, you can skip it).
• Whether to install the Playwright browsers (default: yes).

In an existing project it adds the dependencies to your package.json, creates a playwright.config.ts file, and adds an example test (example.spec.ts). You can re-run it later: it does not overwrite your existing tests.

2. Run the tests

npx playwright test

By default the browser runs without a window (headless).

3. Open the report

npx playwright show-report

It serves the HTML report locally. Open it through this command, not by double-clicking the file.

4. Watch the browser work

npx playwright test --headed   # opens a browser window
npx playwright test --ui       # UI mode: live steps and time-travel debugging

5. Point Playwright at your app

Add these options to the playwright.config.ts that was generated. Adjust the command and the port to your project:

import { defineConfig } from '@playwright/test';
 
export default defineConfig({
  retries: 1,
  webServer: {
    command: 'npm run dev',
    url: 'http://localhost:3000',
    reuseExistingServer: !process.env.CI,
  },
  use: {
    baseURL: 'http://localhost:3000',
    trace: 'on-first-retry',
    screenshot: 'only-on-failure',
  },
});

• webServer starts your dev server before the tests run, and reuses one that is already running.
• baseURL lets your tests use relative paths: page.goto('/login') opens http://localhost:3000/login.

6. Keep the evidence when a test fails

The options above already do it:

• screenshot: 'only-on-failure' saves a screenshot when a test fails.
• trace: 'on-first-retry' records a trace (a step-by-step timeline of the test) when a test is retried. That is why retries: 1 is set.

Open a trace with:

npx playwright show-trace trace.zip

This evidence is what lets you, or an agent, diagnose a failure without guessing.

7. Write a minimal check of your own app

import { test, expect } from '@playwright/test';
 
test('home page loads', async ({ page }) => {
  await page.goto('/');
  await expect(page).toHaveTitle(/.+/);
});

Run it with npx playwright test. Once it passes, you can delete the generated example test.

Expected result

• npx playwright test finishes with passing tests.
• npx playwright show-report opens the report.
• Your config has baseURL, webServer, trace, and screenshot.

Troubleshooting

Next step

Write your first end-to-end flow with an agent: pick one critical flow of your project, have the agent plan it, generate the test, and report the result.