| | |

Playwright 02 ๐ŸŽญ Installation โ€” npm init playwright@latest & project scaffolding

โฑ๏ธ Estimated read: 8 min | |

Playwright installs with a single interactive command that scaffolds a project, installs the test runner, and downloads the browser binaries. The command is npm init playwright@latest, and it is the recommended path for both new projects and existing ones because it creates the configuration file, the example tests, and the CI workflow in one step . The alternativeโ€”installing @playwright/test manually and running npx playwright installโ€”is available for projects that need finer control, but the init command is what most teams use.

This chapter covers the init command and its prompts, the files it creates, the system requirements, and the manual installation path for projects that cannot use the interactive scaffolder. The sections that follow walk through the prompts, the generated structure, and the browser installation step.

Key point: npm init playwright@latest scaffolds the config, example tests, and CI workflow, and optionally downloads the three browser binaries; it requires Node.js 22.x, 24.x, or 26.x, and it does not overwrite existing tests if re-run.


a. The init command and its prompts

The command is run in the project root. It is interactive: it asks four questions, and the answers determine the language, the test folder, the CI workflow, and whether the browsers are downloaded .

npm init playwright@latest

The prompts are:

PromptDefaultEffect
TypeScript or JavaScriptTypeScriptLanguage of the config and tests
Tests folder nametests (or e2e if tests exists)Where the example test is placed
Add a GitHub Actions workflowRecommendedCreates .github/workflows/playwright.yml
Install Playwright browsersYesDownloads Chromium, Firefox, WebKit

The command can be re-run later, and it does not overwrite existing tests . This makes it safe to use as a way to add the GitHub Actions workflow to an existing Playwright project, or to regenerate the config after a version upgrade. The prompts are skippable with flags in CI environments, but the interactive path is the documented default.


b. The scaffolded files

The init command creates a specific set of files. The exact list depends on the answers, but the core is consistent across projects .

playwright.config.ts          # test configuration
package.json                  # scripts and devDependencies
package-lock.json             # lockfile
tests/
  example.spec.ts             # basic example test
tests-examples/
  demo-todo-app.spec.ts       # more detailed example
.github/workflows/
  playwright.yml              # CI workflow (if selected)

The playwright.config.ts is where the projects (Chromium, Firefox, WebKit) are defined, where the baseURL is set, and where the retries, workers, and reporters are configured . The tests/example.spec.ts is a minimal test that demonstrates the page fixture and a basic assertion. The tests-examples/demo-todo-app.spec.ts is a larger example that tests a todo application, useful for seeing the locator patterns and the assertion style .

The package.json receives the @playwright/test dependency and the scripts. The default scripts are test (runs the suite) and test:headed (runs with a visible browser), but the config supports more via the CLI.


c. System requirements and the manual path

The current Playwright documentation lists Node.js 22.x, 24.x, or 26.x as the supported versions . Older documentation and third-party guides list Node 18 or 20, which reflects the version at the time of writing; the installed Playwright version determines the floor, and a project on an older Node version should check the release notes before upgrading . The operating system requirements are Windows 11+, macOS 14+, or the supported Linux distributions (Debian 12/13, Ubuntu 22.04/24.04/26.04) .

The manual installation is two commands. The first installs the test runner as a dev dependency; the second downloads the browser binaries .

npm i -D @playwright/test
npx playwright install

The manual path does not create the config file or the example tests. A project that uses it must write playwright.config.ts by hand, which is why the init command is the recommended starting point. The browser download can be scoped to a single engine with npx playwright install chromium, which is useful in CI where only one browser is tested .

The browser binaries are not the system browsers. Playwright downloads its own builds of Chromium, Firefox, and WebKit, which are versioned with the Playwright release and stored outside the project directory. The total download is roughly 400MB for all three engines, and the WebKit build is larger on Windows than on macOS or Linux.


Complete Example Session

# ============================================
# PART 1: THE INIT COMMAND
# ============================================
# Create a directory and run the scaffolder
mkdir my-e2e-tests && cd my-e2e-tests
npm init playwright@latest

# Prompts:
# โœ” TypeScript or JavaScript ยท TypeScript
# โœ” Tests folder ยท tests
# โœ” Add GitHub Actions workflow ยท true
# โœ” Install Playwright browsers ยท true

# ============================================
# PART 2: THE GENERATED FILES
# ============================================
# playwright.config.ts
# package.json
# tests/example.spec.ts
# tests-examples/demo-todo-app.spec.ts
# .github/workflows/playwright.yml

# ============================================
# PART 3: THE FIRST RUN
# ============================================
# npx playwright test
# Runs the example spec on the configured projects

# ============================================
# PART 4: THE MANUAL PATH
# ============================================
# For a project that cannot use the interactive scaffolder:
npm i -D @playwright/test
npx playwright install
# Then write playwright.config.ts and the tests by hand

The parts covered the init command and its prompts, the generated files, the first test run, and the manual installation path.


Quick Reference

Init Command

ItemValue
Commandnpm init playwright@latest
Language defaultTypeScript
Test folder defaulttests
CI workflowOptional, recommended
Browser installOptional, default yes
Re-run behaviorDoes not overwrite tests

Generated Files

FilePurpose
playwright.config.tsProjects, baseURL, retries, reporters
tests/example.spec.tsMinimal example test
tests-examples/demo-todo-app.spec.tsLarger example
.github/workflows/playwright.ymlCI workflow

Manual Path

StepCommand
Install runnernpm i -D @playwright/test
Install browsersnpx playwright install
Single enginenpx playwright install chromium
Verify versionnpx playwright --version

System Requirements

RequirementVersion
Node.js22.x, 24.x, or 26.x
Windows11+
macOS14+
LinuxDebian 12/13, Ubuntu 22.04/24.04/26.04

Best Practices

โœ… Do This:

# Use the init command for new projects
npm init playwright@latest                                    # โœ…

# Select the GitHub Actions workflow
# (the scaffolded workflow is the easiest CI setup)           # โœ…

# Scope browser install in CI
npx playwright install chromium                               # โœ…

โŒ Don’t Do This:

# Skip the config file and expect tests to run
npm i -D @playwright/test && npx playwright test # no config     # โŒ

# Assume the init command overwrites existing tests
# (it does not, but re-running still changes config)            # โŒ

# Use an unsupported Node version
# (check the release notes before upgrading)                    # โŒ

Common Pitfalls

PitfallWhy It HappensFix
Tests not discoveredNo playwright.config.tsUse init or write the config
Browser not foundnpx playwright install not runRun it, or select browsers during init
Node version errorOlder than supportedUpgrade Node
CI fails on missing deps--with-deps not usednpx playwright install --with-deps

Real-World Examples

1. Init command

npm init playwright@latest

2. Generated config

// playwright.config.ts
import { defineConfig, devices } from "@playwright/test";
export default defineConfig({
  projects: [{ name: "chromium", use: { ...devices["Desktop Chrome"] } }],
});

3. Generated example test

// tests/example.spec.ts
import { test, expect } from "@playwright/test";
test("has title", async ({ page }) => {
  await page.goto("https://playwright.dev/");
  await expect(page).toHaveTitle(/Playwright/);
});

4. Manual install

npm i -D @playwright/test
npx playwright install

5. Single browser

npx playwright install chromium

6. Verify version

npx playwright --version

7. Run tests

npx playwright test

8. Headed run

npx playwright test --headed

9. CI install

npx playwright install --with-deps

10. Check Node

node --version

Visual

The Init Flow

โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”
โ”‚  npm init playwright@latest                             โ”‚
โ”‚         โ”‚                                               โ”‚
โ”‚         โ–ผ                                               โ”‚
โ”‚  Prompt: TypeScript/JavaScript                          โ”‚
โ”‚         โ”‚                                               โ”‚
โ”‚         โ–ผ                                               โ”‚
โ”‚  Prompt: Tests folder                                   โ”‚
โ”‚         โ”‚                                               โ”‚
โ”‚         โ–ผ                                               โ”‚
โ”‚  Prompt: GitHub Actions workflow                        โ”‚
โ”‚         โ”‚                                               โ”‚
โ”‚         โ–ผ                                               โ”‚
โ”‚  Prompt: Install browsers                               โ”‚
โ”‚         โ”‚                                               โ”‚
โ”‚         โ–ผ                                               โ”‚
โ”‚  Scaffold files + download binaries                     โ”‚
โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜

Generated Structure

โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”
โ”‚  project/                                               โ”‚
โ”‚  โ”œโ”€โ”€ playwright.config.ts                               โ”‚
โ”‚  โ”œโ”€โ”€ package.json                                       โ”‚
โ”‚  โ”œโ”€โ”€ tests/                                             โ”‚
โ”‚  โ”‚   โ””โ”€โ”€ example.spec.ts                                โ”‚
โ”‚  โ”œโ”€โ”€ tests-examples/                                    โ”‚
โ”‚  โ”‚   โ””โ”€โ”€ demo-todo-app.spec.ts                          โ”‚
โ”‚  โ””โ”€โ”€ .github/workflows/                                 โ”‚
โ”‚      โ””โ”€โ”€ playwright.yml                                 โ”‚
โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜

Manual vs Init

โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”
โ”‚  INIT                           MANUAL                  โ”‚
โ”‚                                                         โ”‚
โ”‚  One command                    Two commands            โ”‚
โ”‚  Config created                 Config written by hand  โ”‚
โ”‚  Example tests                  Tests written by hand   โ”‚
โ”‚  CI workflow optional           CI workflow manual      โ”‚
โ”‚                                                         โ”‚
โ”‚  Recommended for new projects   For existing projects   โ”‚
โ”‚                                 with custom setup       โ”‚
โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜

Summary

ItemValue
Init commandnpm init playwright@latest
Language defaultTypeScript
Test folder defaulttests
CI workflowOptional, recommended
Browser installOptional, default yes
Node.js requirement22.x, 24.x, or 26.x
Manual installnpm i -D @playwright/test + npx playwright install
Re-run behaviorDoes not overwrite tests

Key takeaways:

  • The init command is the recommended starting point. It scaffolds the config, the example tests, and the optional CI workflow in one step, and it downloads the browser binaries if the prompt is accepted .
  • The prompts are decisions, not defaults to accept blindly. The language, the test folder, and the CI workflow should match the project’s conventions. The browser download is the one prompt where “yes” is almost always correct for a new project.
  • The generated playwright.config.ts is the control surface. It defines the projects (Chromium, Firefox, WebKit), the baseURL, and the test settings. The example tests demonstrate the locator and assertion style, and the tests-examples file shows a more complete pattern .
  • The manual path is for projects that cannot use the interactive command. npm i -D @playwright/test and npx playwright install install the runner and the browsers, but the config and tests must be written by hand .
  • The system requirements are current. Node.js 22.x, 24.x, or 26.x, and a supported operating system. A project on an older Node version should check the release notes before upgrading .

Remember: The installation is the first step, and the init command is the shortest path. It creates the config, the example tests, and the CI workflow, and it downloads the browsers. Accept the defaults for a new project, but confirm the language and the test folder match the project’s conventions. If the project cannot use the interactive command, the manual path is two commands plus a config file written by hand. The browsers are not the system browsers; they are downloaded builds that Playwright manages, and the CI job must install them with the same command.

Was this helpful?


Stop using slow, ad-bloated tool sites! ๐Ÿคฎ

๐Ÿ”Ž Search “KandZ Tools” on Google to use many professional utilities for free.

KandZ.me is the ultimate minimalist hub for:
โœ… Finance (Mortgage, Interest, Inflation)
โœ… Tech (Base64, JSON, Dev Suite, IP)
โœ… Health (BMI, BMR, TDEE)
โœ… Productivity (Timer, Workspace, QR)

โšก๏ธ Fast & Private
๐Ÿ”’ No data leaves your device
๐Ÿ’Ž 100% Free

๐Ÿ”— Use it now: https://tools.kandz.me
๐Ÿ”– Bookmark itโ€”youโ€™ll need it later!