Playwright 02 ๐ญ Installation โ npm init playwright@latest & project scaffolding
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:
| Prompt | Default | Effect |
|---|---|---|
| TypeScript or JavaScript | TypeScript | Language of the config and tests |
| Tests folder name | tests (or e2e if tests exists) | Where the example test is placed |
| Add a GitHub Actions workflow | Recommended | Creates .github/workflows/playwright.yml |
| Install Playwright browsers | Yes | Downloads 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
| Item | Value |
|---|---|
| Command | npm init playwright@latest |
| Language default | TypeScript |
| Test folder default | tests |
| CI workflow | Optional, recommended |
| Browser install | Optional, default yes |
| Re-run behavior | Does not overwrite tests |
Generated Files
| File | Purpose |
|---|---|
playwright.config.ts | Projects, baseURL, retries, reporters |
tests/example.spec.ts | Minimal example test |
tests-examples/demo-todo-app.spec.ts | Larger example |
.github/workflows/playwright.yml | CI workflow |
Manual Path
| Step | Command |
|---|---|
| Install runner | npm i -D @playwright/test |
| Install browsers | npx playwright install |
| Single engine | npx playwright install chromium |
| Verify version | npx playwright --version |
System Requirements
| Requirement | Version |
|---|---|
| Node.js | 22.x, 24.x, or 26.x |
| Windows | 11+ |
| macOS | 14+ |
| Linux | Debian 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
| Pitfall | Why It Happens | Fix |
|---|---|---|
| Tests not discovered | No playwright.config.ts | Use init or write the config |
| Browser not found | npx playwright install not run | Run it, or select browsers during init |
| Node version error | Older than supported | Upgrade Node |
| CI fails on missing deps | --with-deps not used | npx 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
| Item | Value |
|---|---|
| Init command | npm init playwright@latest |
| Language default | TypeScript |
| Test folder default | tests |
| CI workflow | Optional, recommended |
| Browser install | Optional, default yes |
| Node.js requirement | 22.x, 24.x, or 26.x |
| Manual install | npm i -D @playwright/test + npx playwright install |
| Re-run behavior | Does 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.tsis the control surface. It defines the projects (Chromium, Firefox, WebKit), thebaseURL, and the test settings. The example tests demonstrate the locator and assertion style, and thetests-examplesfile shows a more complete pattern . - The manual path is for projects that cannot use the interactive command.
npm i -D @playwright/testandnpx playwright installinstall 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.
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!