Your First Playwright Test — Line by Line

A Playwright test is an async function inside test('name', async ({ page }) => {...}). Inside it you navigate, interact with locators, and assert with web-first expect(). Here's the smallest real test:

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

test('Playwright.dev homepage links to docs', async ({ page }) => {
  await page.goto('https://playwright.dev/');
  await page.getByRole('link', { name: 'Get started' }).click();
  await expect(page).toHaveURL(/docs\/intro/);
  await expect(page.getByRole('heading', { name: 'Installation' })).toBeVisible();
});

• Playwright installed — see Lesson 2.
• A code editor (VS Code recommended).
• Basic idea of JavaScript syntax — variables and functions. That's it.

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

test.describe('Sign up flow', () => {                // 2. group
  test('shows success banner', async ({ page }) => { // 3. one test
    await page.goto('/signup');                      // 4. arrange
    await page.getByLabel('Email').fill('a@b.co');   // 5. act
    await page.getByRole('button', { name: 'Sign up' }).click();
    await expect(page.getByRole('status')).toHaveText('Welcome!'); // 6. assert
  });
});

• test.describe — groups related tests in the report.
• page — a fresh browser tab, provided as a fixture. New tab per test, so tests are isolated.
• await before every Playwright call — non-negotiable.
• getByRole / getByLabel — user-facing locators that mirror how screen readers see the page.
• expect(...).toBe... — web-first assertion, auto-retries for up to 5 s.

1. 1

   Create the file

   Inside the Playwright project from Lesson 2, create tests/todo.spec.ts.

2. 2

   Paste this test

   tests/todo.spec.ts

   tsCopy

   import { test, expect } from '@playwright/test';
   
   test('adds a todo to the demo app', async ({ page }) => {
     await page.goto('https://demo.playwright.dev/todomvc');
   
     const input = page.getByPlaceholder('What needs to be done?');
     await input.fill('Write my first Playwright test');
     await input.press('Enter');
   
     const todo = page.getByTestId('todo-title');
     await expect(todo).toHaveText('Write my first Playwright test');
     await expect(page.getByTestId('todo-count')).toHaveText('1 item left');
   });

3. 3

   Run it in UI Mode

   Copy

   npx playwright test tests/todo.spec.ts --ui

4. 4

   Watch it turn green

   Use the time-travel slider on the left to scrub through every step and see the DOM at that moment. This is what makes Playwright dramatically faster to debug than Selenium.

Web-first assertions poll the DOM until they pass or hit their timeout. They replace every waitForTimeoutyou would otherwise write.

// ❌ Flaky — sleep, then guess
await page.waitForTimeout(3000);
expect(await page.locator('.badge').textContent()).toBe('1');

// ✅ Auto-retrying, deterministic
await expect(page.locator('.badge')).toHaveText('1');

1. 1

   Reproduce in UI Mode

   Open npx playwright test --ui, run the failing test, use the time-travel slider to find the first step that looks wrong.

2. 2

   Pin the browser open with page.pause()

   Copy

   await page.getByLabel('Email').fill('a@b.co');
   await page.pause();                     // Inspector opens here
   await page.getByRole('button', { name: 'Sign up' }).click();

3. 3

   Use the Locator picker

   Inside the Inspector or UI Mode, click "Pick locator" and hover the element. Playwright suggests the most stable selector — usually getByRole.

4. 4

   Save a trace on CI

   playwright.config.ts

   tsCopy

   export default defineConfig({
     use: { trace: 'on-first-retry', screenshot: 'only-on-failure' },
   });

1. 1

   Automate a todo app end-to-end

   Extend the demo test above so it: adds 3 todos, marks the second as complete, deletes the first, and asserts the remaining count is 1.

2. 2

   Add a failing assertion on purpose

   Change one expected value. Run --ui and use the time-travel slider to identify the exact step that mismatches.

3. 3

   Commit

   Copy

   git add tests/todo.spec.ts
   git commit -m "test(todo): first e2e — add, complete, delete"

Green tests are easy. Reading a red one — quickly — is the real skill. Continue to Module 1 / Lesson 4: How to Read a Failing Playwright Test.

Docs: Writing tests · Assertions reference