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:

npx playwright test --ui

• Report viewer:

npx playwright show-report

Need Hands-On Help?

If you're building a test automation framework for your team and want guidance from someone who's done it at Apple and Fortune 500 companies, I offer consulting and training.

Learn more about working with me