Your First Playwright Test: Step-by-Step Tutorial (Beginner Friendly)

Getting started with Playwright feels refreshingly different from traditional automation tools. There are no drivers to download, no brittle waits to fight, and no mysterious timing issues on day one. In this step-by-step tutorial, you’ll write your very first Playwright test, understand what each line does, and learn the correct mental model for building stable UI automation.

This guide is optimized for absolute beginners, but it also sets the right foundation for scalable, professional Playwright frameworks.

---

What You’ll Learn in This Tutorial

By the end of this guide, you will:

• Install Playwright correctly

• Understand Playwright’s project structure

• Write your first UI test

• Run tests in headed and headless mode

• Understand assertions, locators, and auto-waiting

• Generate HTML test reports

---

Prerequisites

Before starting, make sure you have:

• Node.js (LTS version recommended)

• Basic JavaScript knowledge (async/await helps)

• Any modern code editor (VS Code recommended)

No Selenium or automation background is required.

---

Step 1: Create a New Playwright Project

Playwright provides a single command to bootstrap everything you need.

npm init playwright@latest

During setup, you’ll be prompted to choose:

• JavaScript or TypeScript

• Test folder name

• GitHub Actions CI setup

Once completed, Playwright installs:

• Playwright library

• Built-in test runner

• Browser binaries (Chromium, Firefox, WebKit)

---

Step 2: Understand the Playwright Folder Structure

After installation, your project will look like this:

playwright-project/
├── tests/
│   └── example.spec.ts
├── playwright.config.ts
├── package.json
└── node_modules/

Key Files Explained

• tests/: All your test files live here

• example.spec.ts: Sample test provided by Playwright

• playwright.config.ts: Central configuration file

This structure is intentionally simple and scalable.

---

Step 3: Write Your First Playwright Test

Let’s replace the sample test with your own.

Example: Verify Page Title

Create a new file: tests/first-test.spec.ts

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

test('verify homepage title', async ({ page }) => {
  await page.goto('https://example.com');
  await expect(page).toHaveTitle(/Example Domain/);
});

What’s Happening Here?

• test() defines a test case

• { page } gives you a fresh browser page

• page.goto() navigates to the URL

• expect() performs an assertion

Playwright automatically waits for navigation and page readiness.

---

Step 4: Run Your First Playwright Test

Run the test using:

npx playwright test

By default:

• Tests run headless

• All supported browsers execute

• Results are logged in the terminal

You’ve officially run your first Playwright automation test.

---

Step 5: Run Tests in Headed Mode

To visually watch your test execute:

npx playwright test --headed

This is extremely useful for debugging and learning application behavior.

---

Step 6: Understanding Auto-Waiting (Why Your Test Didn’t Flake)

Notice something missing? There are no waits in your test.

Playwright automatically waits for:

• Page navigation

• Elements to be visible

• Assertions to pass

This is why Playwright tests are stable by default.

👉 Suggested Article: Auto-Waiting in Playwright: Why Tests Don’t Flake

---

Step 7: Interacting with Page Elements

Let’s interact with real UI elements.

Example: Clicking a Button

await page.getByRole('link', { name: 'More information' }).click();

Why this works well:

• Uses accessibility roles

• Resistant to UI changes

• Automatically waits for element readiness

Avoid brittle CSS or XPath when possible.

👉 Suggested Article: Playwright Locators Explained: Best Practices

---

Step 8: Filling Forms in Playwright

await page.getByLabel('Username').fill('testuser');
await page.getByLabel('Password').fill('password123');
await page.getByRole('button', { name: 'Login' }).click();

Playwright waits for each field to become interactive before typing.

---

Step 9: Add Assertions (The Right Way)

Assertions in Playwright retry automatically.

await expect(page.locator('.success')).toBeVisible();
await expect(page.locator('.success')).toHaveText('Login successful');

These assertions wait until conditions are satisfied or timeout.

---

Step 10: Generate Playwright HTML Reports

After test execution, run:

npx playwright show-report

You’ll see:

• Passed/failed tests

• Execution time

• Screenshots (if enabled)

Reports make debugging and CI analysis effortless.

---

Step 11: Debug Your Test Like a Pro

Use Playwright’s debug mode:

npx playwright test --debug

This opens:

• Inspector

• Step-by-step execution

• Live DOM inspection

👉 Suggested Article: TBD - Debugging Playwright Tests Like a Pro

---

Step 12: Common Beginner Mistakes

Avoid these early traps:

• Using waitForTimeout

• Overusing XPath locators

• Hardcoding sleeps

• Testing too many things in one test

Playwright rewards simplicity and intent-driven tests.

---

Where to Go Next

Now that you’ve written your first Playwright test, the natural next steps are:

• Page Object Model (POM)

• API testing with Playwright

• CI/CD integration

• Parallel execution

👉 Suggested Article: Playwright Automation Testing: Complete Guide (2026)

---

Final Thoughts

Your first Playwright test may look small, but it represents a big shift in how UI automation should feel: predictable, readable, and stable.

Playwright removes the traditional friction of browser automation and lets you focus on testing behavior instead of timing.

If you master the fundamentals shown here, scaling Playwright to large production frameworks becomes surprisingly straightforward.