How to Use Playwright for Test Automation: A Complete Beginner’s Guide (2025)

1. What is Playwright & Why Use It in 2025?

Playwright is an open-source end-to-end testing framework built by Microsoft. It lets you write automated tests that control a real browser — clicking buttons, filling forms, navigating pages — exactly like a real user would. What makes it special is that it works across Chromium, Firefox, and WebKit (Safari) with a single test script.

In 2025, Playwright has overtaken Selenium as the most popular automation framework according to the State of Testing survey. Here’s why teams are switching:

• Auto-waiting — Playwright waits for elements to be ready before interacting. No more flaky tests from timing issues.
• Cross-browser by default — run the same test on Chrome, Firefox, and Safari with one command.
• Built-in tracing & video recording — every failed test automatically captures a video, screenshot, and trace log.
• Modern JavaScript/TypeScript support — async/await syntax, full TypeScript support out of the box.
• Free and open source — maintained by Microsoft with frequent updates and a huge community.

2. Playwright vs Selenium vs Cypress

Before investing time learning a new tool, it’s worth understanding how it compares to alternatives. Here’s an honest side-by-side comparison:

Our recommendation: use Playwright if you’re starting fresh in 2025. It handles the widest range of scenarios with the least configuration. Its Python support also means both JavaScript developers and Python-based QA engineers can use the same framework.

3. Installation & Project Setup

Playwright requires Node.js. Download the LTS version from nodejs.org if you don’t have it. Then open your terminal and run:

# Create a new project folder
mkdir my-playwright-tests
cd my-playwright-tests

# Run Playwright's interactive setup wizard
npm init playwright@latest

The setup wizard will ask a few questions. Choose these options:
• Language: JavaScript
• Test directory: tests
• GitHub Actions workflow: Yes
• Install browsers: Yes

Once done, run the example tests to confirm everything works:

npx playwright test

You’ll see Playwright run its sample tests across three browsers. Green ticks mean you’re set up correctly and ready to write real tests.

4. Writing Your First Automated Test

Let’s write a real test — a login flow. This is the most common test in any web application and a perfect starting point. Create a file at tests/login.spec.js and paste this:

const { test, expect } = require('@playwright/test');

test('User can log in with valid credentials', async ({ page }) => {

  // 1. Navigate to the login page
  await page.goto('https://yourapp.com/login');

  // 2. Fill in the email field
  await page.fill('#email', 'testuser@example.com');

  // 3. Fill in the password field
  await page.fill('#password', 'SecurePassword123');

  // 4. Click the login button
  await page.click('button[type="submit"]');

  // 5. Assert that the user landed on the dashboard
  await expect(page).toHaveURL(/.*dashboard/);
  await expect(page.locator('h1')).toContainText('Welcome');

});

Run it with: npx playwright test tests/login.spec.js --headed

The --headed flag opens a visible browser window so you can watch Playwright work in real time. Remove it in CI/CD to run headlessly. On any failure, Playwright automatically saves a screenshot and video of what went wrong inside the test-results/ folder.

5. Locators & Selectors That Actually Work

The most common reason Playwright tests break is fragile selectors. If you use a CSS class that changes when the UI is redesigned, your test breaks. Playwright’s recommended locator methods are resilient to change:

• page.getByRole('button', { name: 'Submit' }) — targets by ARIA role. Best for buttons, links, checkboxes.
• page.getByLabel('Email address') — targets an input by its visible label. Works even if the input ID changes.
• page.getByText('Welcome back') — targets by visible text content on the page.
• page.getByPlaceholder('Enter your email') — targets by placeholder text inside an input.
• page.getByTestId('submit-btn') — targets by data-testid attribute. The most stable option.
• page.locator('#user-email') — CSS/ID selector. Use only when the options above don’t work.

6. Assertions — Verifying What You Expect

Assertions are how you tell Playwright what a successful test looks like. Without assertions, a test can pass even when the wrong thing happened. Here are the most useful built-in assertions:

// ✅ Check the page URL
await expect(page).toHaveURL(/.*dashboard/);

// ✅ Check the page title
await expect(page).toHaveTitle('My App — Dashboard');

// ✅ Check an element is visible
await expect(page.locator('.success-message')).toBeVisible();

// ✅ Check element contains text
await expect(page.locator('h1')).toContainText('Welcome back');

// ✅ Check an input field value
await expect(page.locator('#email')).toHaveValue('user@example.com');

// ✅ Count elements on the page
await expect(page.locator('.product-card')).toHaveCount(5);

// ✅ Check an element is NOT visible
await expect(page.locator('.error')).not.toBeVisible();

7. Running Playwright in CI/CD (GitHub Actions)

The real power of Playwright is running it automatically on every code push. If a new feature breaks an existing flow, the test fails and the pull request is blocked — broken code never reaches production.

Paste this into .github/workflows/playwright.yml in your repository:

name: Playwright Tests

on:
  push:
    branches: [ main, develop ]
  pull_request:
    branches: [ main ]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:

      - name: Checkout code
        uses: actions/checkout@v4

      - name: Set up Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '20'

      - name: Install dependencies
        run: npm ci

      - name: Install Playwright browsers
        run: npx playwright install --with-deps

      - name: Run all Playwright tests
        run: npx playwright test

      - name: Upload HTML test report
        uses: actions/upload-artifact@v4
        if: always()
        with:
          name: playwright-report
          path: playwright-report/
          retention-days: 30

With this in place, every pull request triggers a full browser test run. The HTML report artifact lets you download and review results — including screenshots and videos — directly from GitHub Actions.

Key Takeaways & Next Steps

• ✅ Playwright is the best automation framework to learn in 2025 — fast, reliable, cross-browser
• ✅ Install with npm init playwright@latest — setup takes under 5 minutes
• ✅ Use role-based and label-based locators — far more stable than CSS class selectors
• ✅ Always add assertions — a test without assertions is not really a test
• ✅ Integrate with GitHub Actions to run tests automatically on every pull request
• ✅ Start by automating your highest-risk flows: login, checkout, onboarding
• ✅ Ask developers to add data-testid attributes for the most resilient selectors