Playwright Installation Complete Guide

Setting up a robust automation framework begins with configuration. Playwright simplifies this by packaging browser binaries and configuration setups into a unified CLI runner. This guide walks you through setting up Playwright from scratch.

Introduction

Modern web apps require testing across multiple browser engines. Playwright automates this by downloading customized builds of Chromium, Firefox, and WebKit. This ensures execution consistency without relying on pre-installed local applications.

The installation CLI initializes configurations, sets up typescript helper environments, and populates mock test scripts automatically.

System Requirements

Before running the installation commands, verify that your development environment satisfies these prerequisites:

graph TD
    SystemRequirements["Node.js 18+ & 1GB Disk Space"] --> InstallCLI["Execute: npm init playwright"]
    InstallCLI --> DownloadBinaries["Download: WebKit, Chromium, Firefox"]
    DownloadBinaries --> ConfigCreated["Created: playwright.config.ts"]
    ConfigCreated --> RunFirstTest["Execute: npx playwright test"]

Installation Architecture Flow

The download and initialization sequence follows a clear lifecycle:

sequenceDiagram
    participant User as Developer CLI
    participant NPM as NPM Registry
    participant PW as Playwright Setup Package
    participant CDN as Microsoft Azure CDN

    User->>NPM: npm init playwright@latest
    NPM-->>User: Load setup package
    User->>PW: Choose TS/JS and directory options
    PW->>PW: Write config, packages, & templates
    PW->>CDN: Request browser binaries (Chromium, Firefox, WebKit)
    CDN-->>PW: Download zip packages
    PW->>PW: Unpack and install under local appdata folder
    PW-->>User: Setup complete message

Step-by-Step Installation Guide

Follow these steps to configure Playwright in your project.

1. Initialize the Installer

Navigate to your workspace directory and execute the initializer:

# Run the official setup script using npm
npm init playwright@latest

The CLI will prompt you with the following configuration options:

2. Verify Generated Files

The installer creates a clean folder layout containing configuration files and templates:

my-project/
  ├── node_modules/
  ├── tests/
  │    └── example.spec.ts         # Sample test file
  ├── tests-examples/
  │    └── demo-todo-app.spec.ts   # Complex examples
  ├── package.json
  ├── playwright.config.ts         # Main configuration file
  └── .github/
       └── workflows/
            └── playwright.yml     # CI Actions flow

Configuration File Overview

The setup script creates a default playwright.config.ts configuration. Here is an optimized setup:

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

// Configuration details for multi-browser tests
export default defineConfig({
  testDir: './tests',
  fullyParallel: true,
  forbidOnly: !!process.env.CI,
  retries: process.env.CI ? 2 : 0,
  workers: process.env.CI ? 1 : undefined,
  reporter: 'html',
  use: {
    baseURL: 'http://localhost:3000',
    trace: 'on-first-retry',
  },
  projects: [
    {
      name: 'chromium',
      use: { ...devices['Desktop Chrome'] },
    },
    {
      name: 'firefox',
      use: { ...devices['Desktop Firefox'] },
    },
    {
      name: 'webkit',
      use: { ...devices['Desktop Safari'] },
    },
  ],
});

Verification and Execution

Validate that your setup runs correctly by triggering the example tests:

# Execute tests across all configured browsers
npx playwright test

Review the Test Report

After execution completes, launch the HTML report to inspect test speeds and screenshots:

# Launch the local HTML reporter server
npx playwright show-report

Installation Troubleshooting

If you encounter issues during installation, review the solutions in the table below.

Frequently Asked Questions

Can I install Playwright in an existing project?

Yes. Run the initialization script in the root directory. It will add dependencies to package.json without modifying other files.

Where does Playwright download browser binaries?

On Windows, they are saved in %USERPROFILE%\AppData\Local\ms-playwright. On macOS, they are stored in ~/Library/Caches/ms-playwright.

Do I need to install Google Chrome separately?

No. Playwright downloads optimized open-source browser builds (Chromium, Firefox, WebKit) that do not interfere with system apps.

How do I install specific browsers only?

Run npx playwright install chromium to fetch a single binary and reduce disk space utilization.

How do I update Playwright dependencies?

Update the packages in package.json and then execute npx playwright install to fetch compatible browser versions.

Does Playwright support Microsoft Edge?

Yes. You can configure Chrome or Edge in the project devices section by specifying the channel value (e.g. channel: 'msedge').

What does the --with-deps flag do?

It installs the required system dependencies and libraries on Linux operating systems (e.g. npx playwright install-deps).

Can I run tests on real mobile devices?

Playwright simulates mobile browsers locally via responsive viewport settings. Testing on physical mobile hardware requires external server wrappers.

How do I disable browser downloads during installations?

Specify the environment variable PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD=1 before initializing project packages.

Why does installation fail inside Docker containers?

Ensure the Dockerfile includes execution dependencies. Use the official Playwright Docker base image to simplify container builds.

Summary

Completing the installation step initializes configuration rules and mounts browser packages. Running example tests verifies runtime stability.

Related Articles