Your First Playwright Test

Let's skip the lengthy intro — you're here to write tests. In the next 5 minutes, you'll have Playwright installed and your first test running. Let's go!

What Makes Playwright Different?

"Why not just use Selenium or Cypress?"

Great question. Here's the quick version:

• Auto-waits for elements — no more sleep() or flaky waits (seriously, this alone is worth the switch)
• Runs tests in parallel by default
• Works with Chrome, Firefox, and Safari out of the box
• Great debugging tools — trace viewer, UI mode, inspector

Okay, enough talk. Let's code.

Installation

Create a new project (or use an existing one) and run:

npm init playwright@latest

You'll get a few prompts. Here's what I recommend:

• TypeScript or JavaScript? → TypeScript (better autocomplete, catches mistakes early)
• Where to put tests? → tests (the default is fine)
• Add GitHub Actions? → Yes if you want CI, No if you're just exploring
• Install browsers? → Yes

Boom! This creates a project structure like:

your-project/
├── tests/
│   └── example.spec.ts    # Sample test
├── playwright.config.ts    # Configuration
├── package.json
└── ...

Your First Test

Open tests/example.spec.ts. You'll see a sample test. Let's replace it with something simpler:

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

test('Google search works', async ({ page }) => {
  // Go to Google
  await page.goto('https://www.google.com');

  // Type in the search box
  await page.getByRole('combobox', { name: 'Search' }).fill('Playwright testing');

  // Press Enter
  await page.keyboard.press('Enter');

  // Check that results appeared
  await expect(page.getByRole('heading', { name: /Playwright/i })).toBeVisible();
});

Notice a few things (this is important, dude):

1. test and expect come from Playwright — no need to install separate assertion libraries
2. { page } is a "fixture" — Playwright gives you a fresh browser page for each test
3. getByRole finds elements by their accessibility role — more on this in the locators tutorial
4. Everything is async/await — Playwright is promise-based

Running the Test

npx playwright test

You'll see output like:

Running 1 test using 1 worker

  ✓ tests/example.spec.ts:3:1 › Google search works (2.1s)

  1 passed (3.2s)

By default, tests run in headless mode (no visible browser). To see the browser:

npx playwright test --headed

Want to slow it down and watch what's happening?

npx playwright test --headed --slowmo=500

The Test Report

"Where do I see the results?"

After running tests, Playwright generates an HTML report. Open it with:

npx playwright show-report

This shows you:

• Which tests passed/failed
• How long each took
• Screenshots and traces (if configured)

Try UI Mode (You'll Love This)

"Is there a way to actually SEE what's happening?"

Oh yeah. Playwright has a killer feature called UI Mode. Run:

npx playwright test --ui

This opens an interactive window where you can:

• See tests in real-time
• Step through each action
• Time-travel through the test
• Inspect the DOM at each step

Seriously, try it. It makes debugging so much easier. How cool is that?

Quick Config Overview

Your playwright.config.ts controls how tests run. Here are the key settings:

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

export default defineConfig({
  // Where your tests live
  testDir: './tests',

  // Run tests in parallel
  fullyParallel: true,

  // Fail fast or run all?
  retries: process.env.CI ? 2 : 0,

  // Browsers to test
  projects: [
    { name: 'chromium', use: { browserName: 'chromium' } },
    { name: 'firefox', use: { browserName: 'firefox' } },
    { name: 'webkit', use: { browserName: 'webkit' } },
  ],
});

For now, the defaults work great. We'll customize this later.

Common First-Time Issues

"Browser not found" Run npx playwright install to download browsers.

"Test times out"
The default timeout is 30 seconds. For slow pages, add test.setTimeout(60000) in your test.

"Element not found"
The element might not be visible yet. Playwright auto-waits, but sometimes you need await page.waitForLoadState('networkidle'). More on this in navigation.

What's Next?

You've got Playwright running — nice! You learned how to:

• Install Playwright with npm init playwright@latest
• Write tests using test() and expect()
• Run tests with npx playwright test
• Use --headed to see the browser
• Use --ui for interactive debugging

But that getByRole thing probably feels a bit magical. Let's demystify it in the next tutorial: Finding Elements the Right Way. Let's go!