Installing Playwright and Project Setup
Playwright is installed via npm (or yarn/pnpm) into a Node.js project using the npm init playwright@latest command, which scaffolds a complete test project: a playwright.config.ts, an example tests/ directory, a GitHub Actions workflow file, and installs the @playwright/test package. This is different from a bare npm install playwright, which only adds the automation library without the test runner, config, or example scaffolding that most teams actually want on day one.
Cricket analogy: It's like a cricket academy handing a new recruit a full kit bag — bat, pads, helmet, gloves — on day one via npm init playwright, versus a bare npm install playwright which is like being handed just a bat and told to source the rest yourself.
What the Scaffolded Project Looks Like
After running the init command, the CLI asks whether you want TypeScript or JavaScript, where tests should live (default tests/), whether to add a GitHub Actions workflow, and whether to install browser binaries immediately. The resulting playwright.config.ts centralizes settings like testDir, timeout, retries, use.baseURL, and a projects array that defines which browsers (chromium, firefox, webkit) and device emulations the suite runs against, so individual test files stay free of environment-specific configuration.
Cricket analogy: It's like a tour manager setting the match schedule, venues, and playing conditions in one central fixtures document, so individual players don't each need to know the ground dimensions themselves.
Installing Browser Binaries
Playwright does not reuse browsers already installed on your machine by default; it downloads its own patched builds via npx playwright install, which pulls specific tested versions of Chromium, Firefox, and WebKit into a local cache (~/.cache/ms-playwright on Linux/macOS). This matters because it guarantees every developer and CI runner uses the exact same browser build, removing an entire class of 'works on my machine' bugs caused by version drift between a tester's local Chrome and whatever Chrome version a CI runner happens to have.
Cricket analogy: It's like the ICC shipping identical, pre-approved Kookaburra balls to every venue for a World Cup, rather than trusting each host ground's local ball supply and risking inconsistent behavior.
# Scaffold a new Playwright project
npm init playwright@latest
# Install (or update) the browser binaries Playwright manages
npx playwright install
# Install only Chromium, and its OS-level dependencies (useful in CI)
npx playwright install --with-deps chromium
# Run the example test suite
npx playwright testOn Linux CI images, npx playwright install alone often isn't enough — missing system libraries (like libnss3 or libatk) will cause browsers to fail to launch. Use npx playwright install --with-deps to also install the required OS packages, or use Microsoft's official mcr.microsoft.com/playwright Docker image, which ships with everything preinstalled.
Running npm init playwright@latest inside an existing project (one that already has package.json) will add Playwright to that project rather than creating a brand-new folder, which is the recommended way to add E2E tests to an existing app.
npm init playwright@latestscaffolds a full project: config, example tests, and an optional CI workflow.- A bare
npm install playwrightonly adds the library, without the test runner or scaffolding. playwright.config.tscentralizes settings like testDir, timeout, retries, baseURL, and the projects array of browsers/devices.- Playwright downloads its own patched browser binaries via
npx playwright install, cached outside your project folder. - Using Playwright's own managed browsers avoids version-drift bugs between developer machines and CI.
--with-depsinstalls missing OS-level libraries needed to launch browsers on Linux CI images.- Microsoft's official Docker image ships with browsers and dependencies preinstalled for CI use.
Practice what you learned
1. Which command scaffolds a complete Playwright project including config and example tests?
2. What does `playwright.config.ts` typically centralize?
3. Why does Playwright download its own browser binaries instead of using the system-installed Chrome?
4. What is the purpose of the `--with-deps` flag on `playwright install`?
5. Where are Playwright's downloaded browser binaries typically cached on Linux/macOS?
Was this page helpful?
You May Also Like
What Is Playwright?
An introduction to Playwright, Microsoft's cross-browser automation and end-to-end testing framework, and why teams choose it over older tools.
Your First Playwright Test
Writing, running, and understanding a first real Playwright test, from locators and actions to assertions and the HTML report.
Browsers, Contexts, and Pages
Understanding Playwright's core object model — Browser, BrowserContext, and Page — and how it enables fast, isolated test execution.