Installing Playwright and the shape of a project

On this site you write Playwright tests without installing anything. On a real job the install is your first task, and it does more than the usual npm package. Here is what it does and why.

npm init playwright@latest

This asks a few questions and then sets the project up. The part that surprises people is the download: it fetches Chromium, Firefox and WebKit, which is a few hundred megabytes.

That is deliberate. Playwright does not use the Chrome you already have. It downloads specific browser builds so that everyone on your team, and the build server, runs exactly the same versions. A test that passes for you passes for your colleague, because it is not the same browser only by name.

Here is what appears:

tests/
  example.spec.ts
playwright.config.ts
package.json

Smaller than a Cypress project, because Playwright keeps almost everything in one config file.

tests/ holds your test files, named something.spec.ts.

playwright.config.ts is the whole project's settings. This is the file you will edit most, so learn its main parts now:

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

export default defineConfig({
  testDir: './tests',
  use: {
    baseURL: 'http://localhost:3000',
    trace: 'on-first-retry',
  },
  projects: [
    { name: 'chromium', use: { ...devices['Desktop Chrome'] } },
    { name: 'firefox', use: { ...devices['Desktop Firefox'] } },
  ],
});

Three things to notice.

baseURL means page.goto('/login') goes to http://localhost:3000/login. Set it once and your tests stop containing addresses.

trace: 'on-first-retry' records a detailed trace when a test fails and is retried. This is the single most useful setting in the file, and there is a lecture on it later.

projects is how Playwright runs the same tests on several browsers. Each entry is one browser. Running the suite runs it once per project, which is why cross-browser testing in Playwright is nearly free.

To run:

npx playwright test              # everything, headless
npx playwright test --headed     # watch it in a visible browser
npx playwright test --ui         # the interactive UI mode

--ui is worth knowing on day one. It gives you a window where you pick tests, watch them run, and step back through what happened.

Two mistakes I have seen cost people an afternoon.

Your app has to be running. Playwright does not start it. If nothing serves baseURL, every test fails with a connection error. You can have Playwright start it for you with the webServer option in config, which is what most real projects do.

Tests run in parallel by default. This catches Cypress users out. Playwright runs multiple test files at the same time, so two tests that share data will collide immediately rather than eventually. That is a good default, and it means the independence rules matter from day one.

Remember this: one config file, browsers downloaded on purpose, and tests run in parallel from the start.

Reference: Installation.