🎓Foundational Skills
Home/Playwright/Reference

Playwright Reference Documentation

ti
📖Need more details? Check the official documentation for complete API reference.
Official Docs

Quick Navigation

▸ Installation & Setup▸ Using Codegen▸ Running Tests▸ Selectors & Locators▸ Page Object Model▸ Debugging Techniques▸ Trace Files▸ Performance Optimization▸ Parallel Testing▸ Cypress Migration

Installation & Setup

Installing Playwright

  1. Navigate to your project directory: cd your-project
  2. Install Playwright: npm init playwright@latest
  3. Follow the prompts to set up a test project
  4. Install browsers: npx playwright install

💡 Pro Tip:

The installation wizard will create a basic test structure and configuration file for you.

Using Playwright Codegen

Playwright Codegen generates test scripts automatically by recording your interactions:

npx playwright codegen https://example.com

# Examples:
npx playwright codegen https://staging.meltwater.net/engage-next
npx playwright codegen https://app.meltwater.com
  1. Run the codegen command with your target URL
  2. Interact with your site in the opened browser
  3. Playwright generates test code in real-time
  4. Copy the generated script and modify as needed

⚠️ Best Practice:

Use codegen to generate initial selectors, then refactor into Page Object Model for maintainability.

Running Tests

npx playwright test

Run all tests

npx playwright test test-file.spec.ts

Run a specific test file

npx playwright test --headed

Run tests with browser UI visible

npx playwright test --ui

Open the interactive UI mode

npx playwright test --debug

Run in debug mode with inspector

Selectors & Locators

Working with Elements

Array of Elements:

this.savedSearches = this.dataGrid.locator('[data-field="name"]');

First Element:

this.firstSavedSearch = this.dataGrid.locator('[data-field="name"]').first();

Nth Element:

this.secondSavedSearch = this.dataGrid.locator('[data-field="name"]').nth(1);

Count Elements:

async getSavedSearchesCount() {
  const count = await this.savedSearches.count();
  console.log('count', count);
  return count;
}

🎯 Strict Mode:

Playwright operates in strict mode by default. If your selector matches multiple elements, it will throw an error unless you explicitly handle it with .first(), .nth(), or .all().

Page Object Model (POM)

Converting Codegen to POM

Transform generated code into maintainable Page Objects:

Step 1: Codegen Output

await page.goto('https://example.com/login');
await page.fill('[data-test="username"]', 'testuser');
await page.fill('[data-test="password"]', 'password123');
await page.click('[data-test="login-button"]');

Step 2: Refactor to Page Object

export class LoginPage {
  private page: Page;
  private usernameField = '[data-test="username"]';
  private passwordField = '[data-test="password"]';
  private loginButton = '[data-test="login-button"]';

  constructor(page: Page) {
    this.page = page;
  }

  async navigate() {
    await this.page.goto('https://example.com/login');
  }

  async login(username: string, password: string) {
    await this.page.fill(this.usernameField, username);
    await this.page.fill(this.passwordField, password);
    await this.page.click(this.loginButton);
  }
}

Step 3: Use in Tests

test('User can log in', async ({ page }) => {
  const loginPage = new LoginPage(page);
  
  await loginPage.navigate();
  await loginPage.login('testuser', 'password123');
  
  await expect(page).toHaveURL(/.*dashboard/);
});

Debugging Techniques

Pause Execution

Add this line to pause test execution interactively:

await page.pause();

Debug Mode

Run tests with the inspector:

npx playwright test --debug

UI Mode

Visual debugging with step-through capability:

npx playwright test --ui

Trace Files

Trace files allow you to replay and debug failed tests:

1. Enable tracing in playwright.config.ts:

use: {
  trace: 'retain-on-failure'  // Only save traces for failed tests
}

2. Run your tests:

npx playwright test

3. View trace for failed tests:

npx playwright show-trace test-results/trace.zip

Performance Optimization

Tips to Speed Up Tests

  • ✓
    Use selective tracing: Set trace: 'retain-on-failure' instead of trace: 'on'
  • ✓
    Disable unnecessary artifacts: Turn off video/screenshots for passing tests
  • ✓
    Clean up old traces: Regularly delete old trace files to save storage
  • ✓
    Use parallel execution: Run tests concurrently when possible

Parallel Testing

Running Tests in Parallel

Within a spec file, add this at the top:

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

test.describe.configure({ mode: 'parallel' });

test('Test 1', async ({ page }) => {
  // Test logic
});

test('Test 2', async ({ page }) => {
  // Test logic  
});

Control workers from command line:

npx playwright test --workers=4

Run with 4 parallel workers

npx playwright test --workers=1

Disable parallelism (serial execution)

Migrating from Cypress

Key Differences

Cypress:

cy.visit('/login');
cy.get('#username').type('user');
cy.get('#password').type('pass');
cy.get('#submit').click();

Playwright:

await page.goto('/login');
await page.fill('#username', 'user');
await page.fill('#password', 'pass');
await page.click('#submit');

⚠️ Key Differences:

  • • Playwright is async - use await
  • • No automatic waiting - be explicit with waits
  • • Different assertion syntax
  • • Page object passed to tests