Learn Playwright - Installation & Basic Configuration

#Introduction

Episode 2 gave you the architectural model. Now it's time to practice: installing Playwright properly, putting together the configuration you'll use throughout the series, and running your first test via the CLI. This episode 3 is the gateway to actually writing tests.

A correct installation greatly determines your experience going forward. Many problems that appear in real projects — browser not found, tests running in the wrong browser, or timeouts set too aggressively — actually stem from a rushed installation and configuration. Let's do this carefully, starting from zero.

#Installing Playwright and Browser Dependencies

#Installing the Package in a New Project

The fastest way to start a new project and build the default structure at the same time:

npm init playwright@latest

This command creates a configuration file, an example test folder, and installs @playwright/test. If the project already exists and you just want to add Playwright, install the package manually:

npm install -D @playwright/test

#Installing Browser Binaries

Once the package is installed, download the browser binaries:

npx playwright install

The command npx playwright install downloads Chromium, Firefox, and WebKit at once. On Linux, you may need additional system dependencies, which can be installed with:

npx playwright install --with-deps

#The .gitignore File

The browser binaries are stored in the system cache directory, not in the project — so there's no need to commit them. What you do need to add to .gitignore is the test output:

node_modules/
test-results/
playwright-report/

#Setting Up playwright.config.ts

#Complete Configuration for a Project

The playwright.config.ts file is the command center of the entire suite. Here's a complete example that will be the pattern for this series:

Complete playwright.config.ts

import { defineConfig, devices } from '@playwright/test';
 
export default defineConfig({
  testDir: './tests',
  timeout: 30000,
  expect: {
    timeout: 5000,
  },
  fullyParallel: true,
  forbidOnly: !!process.env.CI,
  retries: process.env.CI ? 2 : 0,
  reporter: 'html',
  use: {
    baseURL: 'http://localhost:3000',
    trace: 'on-first-retry',
    screenshot: 'only-on-failure',
    video: 'retain-on-failure',
  },
  projects: [
    { name: 'chromium', use: { ...devices['Desktop Chrome'] } },
    { name: 'firefox', use: { ...devices['Desktop Firefox'] } },
    { name: 'webkit', use: { ...devices['Desktop Safari'] } },
  ],
});

The configuration above uses fullyParallel so tests run in parallel, forbidOnly to prevent test.only from slipping through in CI, and retries that automatically becomes more aggressive when running in CI. The reporter is set to html for easy result inspection.

#Running Your First Test with the CLI

#Example Test and Basic Commands

Create your first test:

tests/awal.spec.ts

import { test, expect } from '@playwright/test';
 
test('example page title', async ({ page }) => {
  await page.goto('https://example.com');
  await expect(page).toHaveTitle(/Example Domain/);
});

Run the whole suite:

npx playwright test

To run a single file, a single test, or with an interactive UI:

npx playwright test tests/awal.spec.ts
npx playwright test -g "example page title"
npx playwright test --ui
npx playwright test --headed

--ui opens the interactive Playwright UI, while --headed runs the browser with a visible window so you can watch the tests run.

#Opening the Report

After the suite finishes, open the HTML report:

npx playwright show-report

The HTML report shows results per test, step by step, along with trace and screenshots when available. This will be your trusty companion when debugging.

#Managing Timeout and Retries

#Timeout: Per Test vs Per Assertion

There are two timeout levels you'll set most often:

• Per test: the overall time limit for a single test, configured via timeout in the config.
• Per assertion: the waiting time limit for a single assertion, configured via expect.timeout.

The per-assertion timeout matters because Playwright's auto-waiting waits for the assertion's condition — for example, an element being visible — until this limit is reached before considering it failed.

#Retries and When to Use Them

Retries re-run failed tests. A healthy default for CI is 1-2 retries, and 0 locally for fast feedback:

local:   retries 0
ci:      retries 2
staging: retries 3

Verify that your configuration works with:

npx playwright --version
npx playwright test --list

npx playwright test --list lists the tests without running them — useful for confirming test files are picked up and test names are correct.

#Closing

This episode 3 got your Playwright project genuinely running: installing the package and browser dependencies, putting together a playwright.config.ts with Chromium, Firefox, and WebKit projects, running your first test via the CLI, and understanding how to manage timeouts and retries for a stable suite.

Key takeaways:

• npm init playwright@latest is the fastest path for a new project.
• npx playwright install is needed once to download the browser binaries.
• playwright.config.ts controls testDir, projects, timeout, and retries.
• expect.timeout sets how long an assertion waits for a condition.
• Retries mask flakiness, but the root cause still has to be resolved.

In the next episode we'll discuss locating elements and interacting with pages — locator strategies based on text, role, CSS, and XPath, basic interactions like click, fill, select, and hover, as well as how auto-waiting and retry-ability work behind every action.