Module 2: Playwright Fundamentals

Now we get hands-on. Playwright is the browser-automation framework at the heart of this course, and this module takes you from an empty folder to a passing test you wrote yourself, then shows you the tools that make debugging almost pleasant. You will install Playwright the official way, understand every file it creates, write your first test() with an expect() assertion, run it headed and headless and in the interactive UI, open a trace of a failed run, and let codegen write a first draft for you. These are the everyday motions of a Playwright engineer—by the end you will have performed all of them.

What Playwright is, and why it’s popular

Playwright is an open-source end-to-end testing framework created by Microsoft. One API drives all three major browser engines—Chromium (Chrome, Edge), Firefox, and WebKit (Safari)—so a single test suite can verify your app across the engines your users actually run. It ships with its own test runner, assertion library, parallel execution, and reporting, so you rarely need to bolt on extra tools.

It became the default choice for new projects for a handful of concrete reasons:

• Auto-waiting. Before every action, Playwright waits for the element to be present, visible, stable, and ready. This removes the single biggest source of flakiness in older tools: the manual sleep.
• Web-first assertions. Assertions like expect(locator).toBeVisible() automatically retry until the condition is true or a timeout is reached, so timing races mostly disappear.
• Isolation by default. Each test runs in a fresh browser context—like a brand-new incognito window—so tests do not leak cookies or state into one another.
• First-class tooling. The trace viewer, UI mode, and codegen make writing and debugging tests genuinely productive.
• Speed. Tests run in parallel across workers out of the box.

Installing Playwright

You need Node.js installed first (a current LTS release). Then, in an empty project folder, run the official initializer:

npm init playwright@latest

This interactive command asks a few questions—whether to use TypeScript or JavaScript (choose TypeScript; Module 3 explains why), what folder to put tests in (the default tests is fine), whether to add a GitHub Actions workflow, and whether to download browsers. Say yes to the browsers; Playwright downloads its own pinned builds of Chromium, Firefox, and WebKit so everyone on the team runs identical versions.

When it finishes you have a ready-to-run project. You can prove it immediately:

npx playwright test

That runs the example test the initializer created and prints a pass/fail summary. If it passes, your installation works.

npx playwright install

npx playwright install --with-deps

Project structure

After initialization, a typical project looks like this:

my-project/
  tests/
    example.spec.ts        ← your test files live here
  tests-examples/
    demo-todo-app.spec.ts  ← a larger example to learn from
  playwright.config.ts     ← central configuration (Module 5)
  package.json             ← dependencies and npm scripts
  package-lock.json
  .github/
    workflows/
      playwright.yml       ← optional CI workflow

The two parts you touch daily are the tests/ folder, where your .spec.ts files go, and playwright.config.ts, the single place that controls how the whole suite behaves. We cover the config in depth in Module 5; for now, know that .spec.ts is the conventional suffix that tells Playwright “this file contains tests”.

Your first test

Create tests/first.spec.ts and write this:

import { test, expect } from '@playwright/test';

test('has the right page title', async ({ page }) => {
  await page.goto('https://playwright.dev/');
  await expect(page).toHaveTitle(/Playwright/);
});

Let us read it line by line, because every Playwright test shares this shape.

• import { test, expect } brings in the two core building blocks: the function that declares a test, and the function that makes assertions.
• test('has the right page title', async ({ page }) => { ... }) declares a test with a human-readable name. The second argument is an async function—browser actions take time, so almost everything is awaited (Module 3 covers async/await fully).
• { page } is a fixture: Playwright hands your test a fresh, isolated browser page to work with. You did not create it; the framework provides it.
• await page.goto(...) navigates the page to a URL and waits for it to load.
• await expect(page).toHaveTitle(/Playwright/) asserts that the page title matches the regular expression /Playwright/, retrying until it does or the timeout expires.

Here is a slightly richer example that clicks a link and checks the result—the bread and butter of UI testing:

import { test, expect } from '@playwright/test';

test('get started link navigates to the docs', async ({ page }) => {
  await page.goto('https://playwright.dev/');

  // Click the "Get started" link.
  await page.getByRole('link', { name: 'Get started' }).click();

  // The Installation heading should now be visible.
  await expect(
    page.getByRole('heading', { name: 'Installation' })
  ).toBeVisible();
});

Notice again: no sleeps. Playwright waits for the link to be clickable before clicking, then toBeVisible() retries until the heading appears. You describe what should be true; the framework handles the when.

Running tests: headless, headed, and UI mode

By default Playwright runs headless—no visible browser window. This is fast and exactly what you want in CI:

npx playwright test

When you are debugging and want to watch the browser do its thing, run headed:

npx playwright test --headed

You can also target a single file or a single test by name:

# Just one file
npx playwright test tests/first.spec.ts

# Only tests whose title contains "title"
npx playwright test -g "title"

The tool you will reach for most while developing is UI mode, an interactive runner with a time-travel view of every step:

npx playwright test --ui

UI mode lets you pick tests to run, watch them execute step by step, hover over each action to see a before/after snapshot of the page, inspect locators live, and re-run on save. For day-to-day authoring it is the single most useful command in the toolkit.

"scripts": {
  "test": "playwright test",
  "test:ui": "playwright test --ui",
  "test:headed": "playwright test --headed",
  "report": "playwright show-report"
}

The trace viewer

When a test fails in CI—on a machine you cannot see—how do you debug it? Playwright’s answer is the trace: a complete recording of the run including a DOM snapshot before and after every action, console logs, network requests, and the source line for each step. Enable traces in playwright.config.ts (Module 5 shows the config in full); a common setting records a trace only when a test fails on retry:

// playwright.config.ts (excerpt)
export default defineConfig({
  use: {
    trace: 'on-first-retry',
  },
});

After a failing run, open the trace with:

npx playwright show-trace trace.zip

The viewer gives you a timeline of actions. Click any step to see exactly what the page looked like at that moment, what the selector matched, and what the network was doing. Debugging a failure you never witnessed becomes a matter of scrubbing through a recording rather than guessing.

Codegen: let Playwright write a draft

You do not have to write every locator by hand. codegen opens a browser, records your clicks and typing, and emits working Playwright code as you go:

npx playwright codegen https://playwright.dev/

As you interact with the site, a window shows generated code using recommended, resilient locators (role- and text-based, which you will learn to prefer in Module 4). Copy the result into a spec file and refine it. Codegen is a brilliant starting point—but treat its output like any generated code: review it, rename the test meaningfully, remove redundant steps, and tighten the assertions. It gets you to a draft fast; the engineering judgement is still yours.