Introduction: What Does Playwright Installation Involve?

A successful Playwright installation involves more than installing one npm package.

For a beginner, the setup has three important parts:

1. Install a supported Node.js environment.
2. Install the Playwright Test package in your project.
3. Download the browser binaries Playwright needs to execute tests.

This distinction is important. Installing @playwright/test gives your project the Playwright Test framework and CLI, while npx playwright install downloads the browser binaries required by Playwright. Each Playwright release is associated with specific browser versions, so browser installation should be kept aligned with the Playwright version in your project.

This Playwright installation guide for beginners walks through the complete setup for Windows, macOS, and Linux. It also covers TypeScript, playwright.config.ts, browser installation, verification, common errors, CI/CD, and interview questions.

By the end, you should be able to create a project and run your first Playwright test successfully.

---

Playwright Prerequisites: Node.js, npm, VS Code, and System Requirements

Before starting the Playwright setup, make sure your machine has the required software.

Basic prerequisites

Requirement	Purpose
Node.js	Runs Playwright and its JavaScript/TypeScript tooling
npm	Installs Playwright packages
VS Code	Recommended editor, but not mandatory
Terminal	Runs Playwright commands
Git	Recommended for automation projects
Internet access	Required to download packages and browser binaries

Playwright’s current documentation lists supported Node.js and operating-system requirements, including recent Node.js versions and supported Windows, macOS, and Linux distributions. Always check the current official requirements when setting up a new environment because support changes over time.

For a QA Automation Engineer, a good beginner setup is:

Windows/macOS/Linux

        ↓

Node.js

        ↓

npm

        ↓

Playwright Test

        ↓

Chromium / Firefox / WebKit

        ↓

TypeScript tests

---

Installing Node.js and Verifying npm

Step 1: Install Node.js

Download and install a current supported Node.js release from the official Node.js website.

After installation, restart your terminal or VS Code terminal.

Step 2: Check Node.js

Run:

node –version

Example:

v22.x.x

Step 3: Check npm

Run:

npm –version

Example:

10.x.x

Expected Result

Both commands should return version numbers.

If you get:

‘node’ is not recognized

on Windows, Node.js may not be installed correctly or its installation directory may not be available in your PATH.

Troubleshooting Tip

Close and reopen your terminal after installing Node.js. If the problem continues, verify that Node.js is included in your system PATH.

---

Installing Playwright With npm

There are two common approaches.

Option 1: Create a new Playwright project

For beginners, this is the recommended approach:

npm init playwright@latest

The Playwright setup wizard guides you through project creation and can install the required browsers and optionally create a GitHub Actions workflow.

Option 2: Install Playwright in an existing project

If you already have a Node.js project:

npm install -D @playwright/test

Then install browsers:

npx playwright install

Playwright’s recommended Node.js test runner is included through @playwright/test, which provides the test runner, assertions, fixtures, reporting, and other test features.

---

Creating a New Playwright Project

The simplest Playwright installation guide example begins with:

npm init playwright@latest

You will be asked questions similar to:

✔ Do you want to use TypeScript or JavaScript?

Choose:

TypeScript

You may then be asked for the test directory.

A common choice is:

tests

You may also be asked whether you want a GitHub Actions workflow.

For a learning project, selecting it can be useful because it introduces CI/CD early.

Concept

The setup wizard creates a ready-to-run Playwright project.

Command

npm init playwright@latest

Explanation

The command initializes the project, adds the required Playwright testing dependency, creates configuration, and can install browsers.

Expected Result

You should see a project containing files such as:

playwright.config.ts

tests/

package.json

Troubleshooting Tip

If npm reports a network or registry error, verify your internet connection and npm registry configuration.

---

Understanding the Playwright Project Structure

After Playwright install, your project may look like this:

playwright-project/

│

├── tests/

│   └── example.spec.ts

│

├── playwright.config.ts

├── package.json

├── package-lock.json

└── node_modules/

tests/

Contains your automated tests.

Example:

tests/login.spec.ts

tests/search.spec.ts

tests/checkout.spec.ts

playwright.config.ts

Contains test configuration.

package.json

Contains project metadata, dependencies, and scripts.

package-lock.json

Locks dependency versions for reproducible npm installations.

node_modules/

Contains installed npm packages.

Do not manually edit files inside node_modules.

---

Playwright Browser Installation: An Important Difference

One of the most common beginner misunderstandings is assuming that:

npm install -D @playwright/test

automatically means every required browser binary is available.

It is better to think about installation as two layers:

Layer 1

@playwright/test

       ↓

Test runner + Playwright APIs

Layer 2

npx playwright install

       ↓

Browser binaries

Chromium / Firefox / WebKit

Playwright documents that each version requires specific browser binaries and that these browsers are installed through the Playwright CLI.

Install all supported browsers

npx playwright install

Install only Chromium

npx playwright install chromium

Install Firefox

npx playwright install firefox

Install WebKit

npx playwright install webkit

List installed browsers

npx playwright install –list

Uninstall Playwright browsers

npx playwright uninstall

These commands are provided by the Playwright CLI.

Best Practice

For local development, install the browsers your project actually tests.

For a cross-browser framework, installing Chromium, Firefox, and WebKit is appropriate.

---

Configuring playwright.config.ts

The playwright.config.ts file controls how tests execute.

A beginner-friendly configuration is:

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

export default defineConfig({

  testDir: ‘./tests’,

  timeout: 30_000,

  expect: {

    timeout: 5_000,

  },

  reporter: ‘html’,

  use: {

    baseURL: ‘https://example.com’,

    headless: true,

    screenshot: ‘only-on-failure’,

    trace: ‘on-first-retry’,

  },

  projects: [

    {

      name: ‘chromium’,

      use: { …devices[‘Desktop Chrome’] },

    },

  ],

});

Important settings

testDir

testDir: ‘./tests’

Tells Playwright where tests are stored.

baseURL

baseURL: ‘https://example.com’

Allows:

await page.goto(‘/login’);

instead of writing the complete URL every time.

headless

headless: true

Runs browsers without displaying the browser window.

screenshot

screenshot: ‘only-on-failure’

Captures screenshots when tests fail.

trace

trace: ‘on-first-retry’

Captures a trace when a failed test is retried.

Playwright’s configuration supports options such as test directories, retries, workers, reporters, and browser projects.

---

Writing and Running the First Playwright Test

Create:

tests/first-test.spec.ts

Add:

import { test, expect } from ‘@playwright/test’;

test(‘verify Playwright installation’, async ({ page }) => {

  await page.goto(‘https://playwright.dev/’);

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

});

Concept

This test verifies that the Playwright environment can:

• Start a browser
• Open a page
• Navigate to a URL
• Execute an assertion

Expected Result

Run:

npx playwright test

You should see a successful test result.

Troubleshooting Tip

If the browser executable is missing, run:

npx playwright install

---

Verifying the Playwright Installation

A successful installation should pass several checks.

Check 1: Node.js

node –version

Check 2: npm

npm –version

Check 3: Playwright version

npx playwright –version

Playwright recommends using the CLI to check the installed version.

Check 4: Browser installation

npx playwright install –list

Check 5: Run tests

npx playwright test

Check 6: Run headed

npx playwright test –headed

If all six checks work, your basic Playwright installation is ready.

---

Installing Playwright on Windows

The Playwright installation on Windows process is straightforward.

Prerequisite

Install a supported Node.js version.

Command

Open PowerShell or Command Prompt:

node –version

npm –version

Create the project:

npm init playwright@latest

Install browsers if needed:

npx playwright install

Run tests:

npx playwright test

Run visibly:

npx playwright test –headed

Windows troubleshooting

If npx is not recognized:

1. Restart the terminal.
2. Verify Node.js installation.
3. Check PATH configuration.
4. Reinstall Node.js if necessary.

---

Playwright Installation on macOS

For Playwright installation on Mac, first verify Node.js:

node –version

npm –version

Create the project:

npm init playwright@latest

Install browsers:

npx playwright install

Run:

npx playwright test

macOS troubleshooting

If permissions or shell configuration cause issues, avoid randomly using sudo npm install for project dependencies.

Instead, fix the Node.js installation or use a Node version manager appropriate for your environment.

---

Playwright Installation on Linux

For Playwright installation on Linux, the basic setup is:

node –version

npm –version

Then:

npm init playwright@latest

Install browsers:

npx playwright install

Linux CI machines can additionally require operating-system dependencies.

Use:

npx playwright install –with-deps

Playwright provides –with-deps to install browser binaries together with required system dependencies, which is especially useful in CI environments.

Linux troubleshooting

If the browser launches locally but fails on a Linux CI agent, missing OS dependencies are a common thing to investigate.

---

Running Playwright in Headed and Headless Modes

Headless mode

This is commonly used in CI:

npx playwright test

The browser runs without a visible window.

Headed mode

Useful during development:

npx playwright test –headed

You can watch the browser perform actions.

Debug mode

npx playwright test –debug

This is useful for investigating locators and test steps.

Playwright also supports UI Mode:

npx playwright test –ui

UI Mode provides a visual way to explore and debug tests.

---

Installing Playwright in an Existing Project

Suppose you already have:

my-automation-project/

├── package.json

└── src/

You can add Playwright without creating a new project:

npm install -D @playwright/test

Then:

npx playwright install

Create:

tests/

and add:

tests/login.spec.ts

Example:

import { test, expect } from ‘@playwright/test’;

test(‘homepage loads’, async ({ page }) => {

  await page.goto(‘https://example.com’);

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

});

Run:

npx playwright test

This approach is useful when adding Playwright automation testing to an existing JavaScript or TypeScript application.

---

Basic Playwright CI/CD and GitHub Actions Setup

After local Playwright setup, the next step for professional QA automation is CI/CD.

A basic GitHub Actions workflow is:

name: Playwright Tests

on:

  push:

    branches: [main]

  pull_request:

    branches: [main]

jobs:

  test:

    runs-on: ubuntu-latest

    steps:

      – uses: actions/checkout@v6

      – uses: actions/setup-node@v6

        with:

          node-version: lts/*

      – name: Install dependencies

        run: npm ci

      – name: Install Playwright browsers

        run: npx playwright install –with-deps

      – name: Run Playwright tests

        run: npx playwright test

      – name: Upload Playwright report

        uses: actions/upload-artifact@v5

        if: ${{ !cancelled() }}

        with:

          name: playwright-report

          path: playwright-report/

The important CI sequence is:

Checkout

   ↓

Install Node

   ↓

npm ci

   ↓

Install Playwright browsers

   ↓

Run tests

   ↓

Upload report

Playwright’s official CI guidance uses this same general pattern for GitHub Actions and recommends installing browser dependencies before running tests.

Career Tip

For an SDET interview, be prepared to explain why browser installation is a separate CI step.

---

Common Playwright Installation Errors and Solutions

Error 1: node is not recognized

Cause

Node.js is missing or not available in PATH.

Solution

Verify:

node –version

Reinstall or correct the Node.js PATH configuration if necessary.

---

Error 2: npm is not recognized

Cause

Usually a Node.js installation or PATH issue.

Solution

Restart the terminal first.

Then:

npm –version

---

Error 3: Browser executable doesn’t exist

Cause

The Playwright package is installed but the required browser binary is missing.

Solution

npx playwright install

---

Error 4: Linux dependency error

Cause

Required system libraries are missing.

Solution

npx playwright install –with-deps

This is particularly useful on CI Linux machines.

---

Error 5: npm network error

Possible causes

• Corporate proxy
• Firewall
• DNS issue
• Registry configuration
• Unstable internet
• SSL inspection

Check:

npm config get registry

You can also investigate proxy configuration in corporate environments.

For browser downloads, Playwright provides environment variables for proxy and download configuration. For example, the browser download connection timeout can be increased when connections to the browser archive are slow.

Example:

PLAYWRIGHT_DOWNLOAD_CONNECTION_TIMEOUT=120000 npx playwright install

On Windows PowerShell:

$Env:PLAYWRIGHT_DOWNLOAD_CONNECTION_TIMEOUT=”120000″

npx playwright install

---

Playwright Browser Installation and Dependency Issues

Browser installation deserves special attention because browsers are version-specific.

Playwright updates supported browser versions as the framework evolves. After updating Playwright, you may need to run the browser installation command again.

Update:

npm install -D @playwright/test@latest

Then:

npx playwright install

Check:

npx playwright –version

List browsers:

npx playwright install –list

Practical rule

Whenever your team upgrades Playwright, treat browser installation as part of the upgrade process.

---

Playwright Version and Node.js Compatibility

Avoid blindly mixing old Playwright packages with unrelated Node.js versions.

Check your Node version:

node –version

Check Playwright:

npx playwright –version

Check the official Playwright system requirements before beginning a new project or upgrading an existing framework because supported Node.js and OS versions can change between releases.

For team projects, commit:

package.json

package-lock.json

This helps CI reproduce the intended dependency installation.

Use:

npm ci

in CI rather than casually installing dependencies without honoring the lockfile.

---

Playwright Installation Best Practices

Follow these practices from the beginning.

1. Install Playwright locally

Prefer:

npm install -D @playwright/test

instead of relying on a global test framework installation.

2. Commit the lockfile

Keep:

package-lock.json

in your project.

3. Keep Playwright and browsers aligned

After upgrades:

npm install -D @playwright/test@latest

npx playwright install

4. Use CI-specific browser dependencies

On Linux CI:

npx playwright install –with-deps

5. Verify installations

Use:

npx playwright –version

npx playwright install –list

npx playwright test

6. Do not install browsers manually unless required

Let Playwright manage its compatible browser binaries.

7. Avoid unnecessary global packages

Your project should declare its automation dependencies.

8. Use Git

Track:

• Configuration
• Tests
• Package files
• CI workflows

Do not commit node_modules.

9. Keep configuration in source control

Your playwright.config.ts should be version controlled.

10. Run a smoke test after installation

A simple homepage test immediately tells you whether your environment is working.

---

Playwright Interview Questions With Answers

1. How do I install Playwright?

For a new project:

npm init playwright@latest

For an existing Node.js project:

npm install -D @playwright/test

Then install browsers:

npx playwright install

2. What is the difference between Playwright package installation and browser installation?

@playwright/test installs the testing framework and CLI. npx playwright install downloads the browser binaries Playwright needs for test execution.

3. How do you check the installed Playwright version?

npx playwright –version

4. How do you install only Chromium?

npx playwright install chromium

5. How do you install Playwright browsers with Linux dependencies?

npx playwright install –with-deps

6. How do you run Playwright tests?

npx playwright test

7. How do you run a Playwright test with a visible browser?

npx playwright test –headed

8. Why can Playwright work locally but fail in CI?

The CI environment may not have the required browser binaries, Linux dependencies, environment variables, or compatible runtime.

9. What is playwright.config.ts?

It is the central configuration file for Playwright Test. It can define test directories, browser projects, reporters, retries, base URLs, screenshots, traces, and other execution settings.

10. How would you troubleshoot a Playwright installation failure?

Check Node.js, npm, Playwright version, network/proxy configuration, browser installation, OS dependencies, and permissions. Then run a minimal test to isolate the problem.

---

Playwright Learning Roadmap for Beginners

Installing Playwright is only the first step.

A practical learning path is:

Stage 1: Playwright Installation

Learn:

• Node.js
• npm
• Project creation
• Browser installation
• Configuration
• Test execution

Stage 2: Playwright Basics

Learn:

• Browser
• Browser context
• Page
• Locators
• Actions
• Assertions
• Auto-waiting

Stage 3: Playwright Automation

Practice:

• Login
• Forms
• Dropdowns
• Checkboxes
• Tables
• Alerts
• Frames
• Popups
• Multiple pages

Stage 4: Framework Design

Learn:

• Page Object Model
• Fixtures
• Hooks
• Test data
• Utilities
• Environment configuration

Stage 5: Advanced Automation

Learn:

• API testing
• Authentication
• Network interception
• Parallel execution
• Visual testing
• Advanced reporting

Stage 6: DevOps

Learn:

• Git
• GitHub Actions
• CI/CD
• Docker
• Test artifacts
• Pipeline troubleshooting

For QA Automation and SDET careers, combine Playwright TypeScript with API testing, SQL, Git, CI/CD, and software testing fundamentals.

---

Related Playwright Tutorials to Learn Next

After completing this Playwright installation guide, continue with:

• Playwright Basics
• Playwright for Beginners
• Playwright First Test Script
• Playwright Tutorial
• Playwright Tutorial Step by Step
• Playwright TypeScript Tutorial
• Playwright Python Tutorial
• Playwright Java Tutorial
• Playwright Locators
• Playwright Auto Waiting
• Playwright Page Object Model
• Playwright Fixtures Tutorial
• Playwright API Testing
• Playwright Authentication Tutorial
• Playwright Reporting Tutorial
• Playwright Parallel Execution Tutorial
• Playwright CI/CD Tutorial
• Playwright GitHub Actions Tutorial
• Playwright Docker Tutorial
• Playwright Troubleshooting
• Playwright Interview Questions

This progression takes you from basic Playwright setup to a production-ready Playwright testing framework.

---

FAQs About Playwright Installation

How do I install Playwright?

For a new TypeScript project, run:

npm init playwright@latest

For an existing Node.js project:

npm install -D @playwright/test

Then install browsers:

npx playwright install

How do I get started with Playwright?

Install Node.js, create a Playwright project, install browser binaries, create a test, and run it with:

npx playwright test

Do I need Node.js to use Playwright TypeScript?

For Playwright’s Node.js TypeScript test runner, yes. The official Node.js Playwright implementation uses Node.js and includes its own test runner.

Do I need to install Chrome separately?

No. Playwright can download and manage its supported browser binaries through:

npx playwright install

It can also test branded browsers such as Google Chrome and Microsoft Edge when configured appropriately.

How do I install Playwright browsers?

Run:

npx playwright install

For Linux CI environments:

npx playwright install –with-deps

Can I install only Chromium?

Yes:

npx playwright install chromium

Can I install Playwright on Windows?

Yes. Install a supported Node.js version, create the project with npm init playwright@latest, install browsers, and run your tests.

Can I install Playwright on macOS?

Yes. The same npm-based setup works on supported macOS versions.

Can I install Playwright on Linux?

Yes. On Linux, you may also need operating-system browser dependencies. The –with-deps option can install the required dependencies where supported.

Why does Playwright say a browser executable is missing?

Usually the required browser binary has not been installed or the Playwright version was changed. Run:

npx playwright install

How do I verify Playwright installation?

Run:

node –version

npm –version

npx playwright –version

npx playwright install –list

npx playwright test

How do I open the Playwright HTML report?

After running tests:

npx playwright show-report