Playwright Tutorial for Beginners: Your First Test in 10 Minutes

What You'll Learn

By the end of this tutorial, you'll have:

Playwright installed on your machine
Written and run your first automated test
Understood the basic Playwright concepts
A foundation to build real-world test suites

Total time: about 10 minutes. Let's go.

Prerequisites

You need Node.js 18+ installed. Check your version:

node --version

If you need to install Node.js, download it from nodejs.org.

That's it. No other dependencies required.

Step 1: Create Your Project

Open your terminal and create a new folder:

mkdir playwright-tutorial

cd playwright-tutorial

Step 2: Install Playwright

Run the Playwright installer:

npm init playwright@latest

You'll see some prompts. Accept the defaults:

TypeScript or JavaScript? → TypeScript (recommended)
Where to put tests? → tests
Add GitHub Actions? → Yes (optional, but useful later)
Install browsers? → Yes

This installs Playwright, downloads browser binaries, and creates a basic project structure.

Step 3: Explore the Project Structure

After installation, you'll see:

tests/ — Your test files go here
playwright.config.ts — Configuration file
tests/example.spec.ts — A sample test (we'll replace this)

Step 4: Write Your First Test

Delete the example test and create a new file called tests/first.spec.ts:

import { test, expect } from '@playwright/test';
test('homepage has correct title', async ({ page }) => {
  await page.goto('https://playwright.dev');
  await expect(page).toHaveTitle(/Playwright/);
});

What this does:

test() — Defines a test with a name
page.goto() — Navigates to a URL
expect().toHaveTitle() — Asserts the page title contains "Playwright"

Step 5: Run Your Test

In your terminal:

npx playwright test

You should see:

Running 1 test using 1 worker
✓ first.spec.ts:3:1 › homepage has correct title (1.2s)
1 passed (2.1s)

Congratulations! You just ran your first Playwright test.

Step 6: See the Test Report

Playwright generates beautiful HTML reports. View it:

npx playwright show-report

This opens a browser with your test results, including timing, screenshots, and traces.

Step 7: Run Tests in UI Mode (Game Changer)

Playwright's UI mode lets you watch tests run in real-time:

npx playwright test --ui

This opens a visual interface where you can:

Watch tests execute step-by-step
Inspect DOM at any point
Debug failures visually
Re-run individual tests

This is my favorite Playwright feature for development.

Step 8: Add More Assertions

Let's expand our test to click a link and verify navigation:

import { test, expect } from '@playwright/test';
test('can navigate to getting started page', async ({ page }) => {
  await page.goto('https://playwright.dev');
  // Click the Getting Started link
  await page.getByRole('link', { name: 'Get started' }).click();
  // Verify we're on the right page
  await expect(page).toHaveURL(/.*intro/);
  // Check the heading exists
  await expect(page.getByRole('heading', { name: 'Installation' })).toBeVisible();
});

New concepts:

getByRole() — Finds elements by their accessibility role (best practice)
click() — Clicks an element
toHaveURL() — Asserts the current URL matches a pattern
toBeVisible() — Asserts an element is visible on page

Step 9: Use the Code Generator

Playwright can generate test code by recording your actions:

npx playwright codegen playwright.dev

This opens a browser. Click around, and Playwright writes code for you in real-time. Copy the generated code into your test file.

This is extremely useful for learning locators and speeding up test creation.

Understanding Key Concepts

Locators:

Playwright finds elements using locators. Best practices:

getByRole() — By accessibility role (button, link, heading)
getByText() — By visible text
getByLabel() — By form label
getByTestId() — By data-testid attribute

Avoid CSS selectors and XPath when possible — role-based locators are more resilient.

Auto-waiting:

Playwright automatically waits for elements to be ready before interacting. No more:

await page.waitForSelector('.button'); // Not needed!

Just write:

await page.click('.button'); // Playwright handles waiting

This dramatically reduces flaky tests.

Next Steps

Now that you have the basics:

Add more tests — Start testing your own application
Learn Page Object Model — Organize tests for maintainability
Set up CI/CD — Run tests on every pull request
Explore API testing — Playwright also tests REST APIs

Common Beginner Mistakes to Avoid

1. Using sleep/delay:

Bad:

await page.waitForTimeout(5000);

Good: Let Playwright's auto-waiting handle it, or wait for specific conditions.

2. Fragile locators:

Bad:

page.locator('#app > div:nth-child(3) > button')

Good:

page.getByRole('button', { name: 'Submit' })

3. Not using test isolation:

Each test should be independent. Don't rely on state from previous tests.

Resources

Official docs: playwright.dev/docs/intro
Test generator:

npx playwright codegen [url]

UI mode: