Back to Details

playwright-page-object-model

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Playwright Page Object Model

Playwright 页面对象模型

Master the Page Object Model (POM) pattern to create maintainable, reusable, and scalable test automation code. This skill covers modern Playwright patterns including component-based architecture, locator strategies, and app actions.
掌握页面对象模型（POM）模式，以创建可维护、可复用且可扩展的测试自动化代码。本内容涵盖现代Playwright模式，包括基于组件的架构、定位器策略和应用操作。

Core POM Principles

核心POM原则

Single Responsibility

单一职责

Each page object should represent one page or component with a single, well-defined responsibility.
每个页面对象应代表一个页面或组件，具备单一、明确的职责。

Encapsulation

封装

Hide implementation details and expose only meaningful actions and assertions.
隐藏实现细节，仅暴露有意义的操作和断言。

Reusability

可复用性

Create reusable components that can be composed into larger page objects.
创建可复用的组件，这些组件可组合成更大的页面对象。

Maintainability

可维护性

When UI changes, update page objects in one place rather than across multiple tests.
当UI发生变化时，只需在一处更新页面对象，而非在多个测试中逐一修改。

Basic Page Object Pattern

基础页面对象模式

Simple Page Object

简单页面对象

typescript
// pages/login-page.ts
import { Page, Locator } from '@playwright/test';

export class LoginPage {
  readonly page: Page;
  readonly emailInput: Locator;
  readonly passwordInput: Locator;
  readonly loginButton: Locator;
  readonly errorMessage: Locator;

  constructor(page: Page) {
    this.page = page;
    this.emailInput = page.getByLabel('Email');
    this.passwordInput = page.getByLabel('Password');
    this.loginButton = page.getByRole('button', { name: 'Login' });
    this.errorMessage = page.getByRole('alert');
  }

  async goto() {
    await this.page.goto('/login');
  }

  async login(email: string, password: string) {
    await this.emailInput.fill(email);
    await this.passwordInput.fill(password);
    await this.loginButton.click();
  }

  async getErrorMessage() {
    return await this.errorMessage.textContent();
  }
}
typescript
// pages/login-page.ts
import { Page, Locator } from '@playwright/test';

export class LoginPage {
  readonly page: Page;
  readonly emailInput: Locator;
  readonly passwordInput: Locator;
  readonly loginButton: Locator;
  readonly errorMessage: Locator;

  constructor(page: Page) {
    this.page = page;
    this.emailInput = page.getByLabel('Email');
    this.passwordInput = page.getByLabel('Password');
    this.loginButton = page.getByRole('button', { name: 'Login' });
    this.errorMessage = page.getByRole('alert');
  }

  async goto() {
    await this.page.goto('/login');
  }

  async login(email: string, password: string) {
    await this.emailInput.fill(email);
    await this.passwordInput.fill(password);
    await this.loginButton.click();
  }

  async getErrorMessage() {
    return await this.errorMessage.textContent();
  }
}

Using Page Object in Tests

在测试中使用页面对象

typescript
// tests/login.spec.ts
import { test, expect } from '@playwright/test';
import { LoginPage } from '../pages/login-page';

test.describe('Login', () => {
  test('should login successfully', async ({ page }) => {
    const loginPage = new LoginPage(page);
    await loginPage.goto();
    await loginPage.login('user@example.com', 'password123');

    await expect(page).toHaveURL('/dashboard');
  });

  test('should show error on invalid credentials', async ({ page }) => {
    const loginPage = new LoginPage(page);
    await loginPage.goto();
    await loginPage.login('user@example.com', 'wrongpassword');

    const error = await loginPage.getErrorMessage();
    expect(error).toContain('Invalid credentials');
  });
});
typescript
// tests/login.spec.ts
import { test, expect } from '@playwright/test';
import { LoginPage } from '../pages/login-page';

test.describe('Login', () => {
  test('should login successfully', async ({ page }) => {
    const loginPage = new LoginPage(page);
    await loginPage.goto();
    await loginPage.login('user@example.com', 'password123');

    await expect(page).toHaveURL('/dashboard');
  });

  test('should show error on invalid credentials', async ({ page }) => {
    const loginPage = new LoginPage(page);
    await loginPage.goto();
    await loginPage.login('user@example.com', 'wrongpassword');

    const error = await loginPage.getErrorMessage();
    expect(error).toContain('Invalid credentials');
  });
});

Locator Strategies

定位器策略

Recommended Locator Priority

推荐的定位器优先级

  1. User-visible locators (getByRole, getByText, getByLabel)
  2. Test IDs (getByTestId)
  3. CSS/XPath (only as last resort)
  1. 用户可见定位器（getByRole、getByText、getByLabel）
  2. 测试ID（getByTestId）
  3. CSS/XPath（仅作为最后手段）

User-Visible Locators

用户可见定位器

typescript
export class HomePage {
  readonly page: Page;

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

  // By role (ARIA role)
  get searchButton() {
    return this.page.getByRole('button', { name: 'Search' });
  }

  // By label (form inputs)
  get searchInput() {
    return this.page.getByLabel('Search products');
  }

  // By text
  get welcomeMessage() {
    return this.page.getByText('Welcome back');
  }

  // By placeholder
  get emailInput() {
    return this.page.getByPlaceholder('Enter your email');
  }

  // By alt text (images)
  get logo() {
    return this.page.getByAltText('Company Logo');
  }

  // By title
  get helpIcon() {
    return this.page.getByTitle('Help');
  }
}
typescript
export class HomePage {
  readonly page: Page;

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

  // By role (ARIA role)
  get searchButton() {
    return this.page.getByRole('button', { name: 'Search' });
  }

  // By label (form inputs)
  get searchInput() {
    return this.page.getByLabel('Search products');
  }

  // By text
  get welcomeMessage() {
    return this.page.getByText('Welcome back');
  }

  // By placeholder
  get emailInput() {
    return this.page.getByPlaceholder('Enter your email');
  }

  // By alt text (images)
  get logo() {
    return this.page.getByAltText('Company Logo');
  }

  // By title
  get helpIcon() {
    return this.page.getByTitle('Help');
  }
}

Test ID Locators

测试ID定位器

typescript
// Component with test IDs
// <button data-testid="submit-button">Submit</button>

export class FormPage {
  readonly page: Page;

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

  get submitButton() {
    return this.page.getByTestId('submit-button');
  }

  get formContainer() {
    return this.page.getByTestId('form-container');
  }
}
typescript
// Component with test IDs
// <button data-testid="submit-button">Submit</button>

export class FormPage {
  readonly page: Page;

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

  get submitButton() {
    return this.page.getByTestId('submit-button');
  }

  get formContainer() {
    return this.page.getByTestId('form-container');
  }
}

Locator Chaining

定位器链式调用

typescript
export class ProductPage {
  readonly page: Page;

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

  // Chain locators for specificity
  get priceInCart() {
    return this.page
      .getByTestId('shopping-cart')
      .getByRole('cell', { name: 'Price' });
  }

  // Filter locators
  getProductByName(name: string) {
    return this.page
      .getByRole('listitem')
      .filter({ hasText: name });
  }

  // Nth element
  get firstProduct() {
    return this.page.getByRole('article').nth(0);
  }
}
typescript
export class ProductPage {
  readonly page: Page;

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

  // Chain locators for specificity
  get priceInCart() {
    return this.page
      .getByTestId('shopping-cart')
      .getByRole('cell', { name: 'Price' });
  }

  // Filter locators
  getProductByName(name: string) {
    return this.page
      .getByRole('listitem')
      .filter({ hasText: name });
  }

  // Nth element
  get firstProduct() {
    return this.page.getByRole('article').nth(0);
  }
}

Component-Based Architecture

基于组件的架构

Reusable Component Objects

可复用组件对象

typescript
// components/navigation.ts
export class Navigation {
  readonly page: Page;
  readonly homeLink: Locator;
  readonly productsLink: Locator;
  readonly cartLink: Locator;
  readonly profileMenu: Locator;

  constructor(page: Page) {
    this.page = page;
    this.homeLink = page.getByRole('link', { name: 'Home' });
    this.productsLink = page.getByRole('link', { name: 'Products' });
    this.cartLink = page.getByRole('link', { name: 'Cart' });
    this.profileMenu = page.getByRole('button', { name: 'Profile' });
  }

  async navigateToHome() {
    await this.homeLink.click();
  }

  async navigateToProducts() {
    await this.productsLink.click();
  }

  async navigateToCart() {
    await this.cartLink.click();
  }

  async openProfileMenu() {
    await this.profileMenu.click();
  }
}
typescript
// components/navigation.ts
export class Navigation {
  readonly page: Page;
  readonly homeLink: Locator;
  readonly productsLink: Locator;
  readonly cartLink: Locator;
  readonly profileMenu: Locator;

  constructor(page: Page) {
    this.page = page;
    this.homeLink = page.getByRole('link', { name: 'Home' });
    this.productsLink = page.getByRole('link', { name: 'Products' });
    this.cartLink = page.getByRole('link', { name: 'Cart' });
    this.profileMenu = page.getByRole('button', { name: 'Profile' });
  }

  async navigateToHome() {
    await this.homeLink.click();
  }

  async navigateToProducts() {
    await this.productsLink.click();
  }

  async navigateToCart() {
    await this.cartLink.click();
  }

  async openProfileMenu() {
    await this.profileMenu.click();
  }
}

Composing Page Objects with Components

用组件组合页面对象

typescript
// pages/base-page.ts
import { Page } from '@playwright/test';
import { Navigation } from '../components/navigation';
import { Footer } from '../components/footer';

export class BasePage {
  readonly page: Page;
  readonly navigation: Navigation;
  readonly footer: Footer;

  constructor(page: Page) {
    this.page = page;
    this.navigation = new Navigation(page);
    this.footer = new Footer(page);
  }
}
typescript
// pages/product-page.ts
import { BasePage } from './base-page';
import { Page } from '@playwright/test';

export class ProductPage extends BasePage {
  readonly addToCartButton: Locator;
  readonly productTitle: Locator;
  readonly productPrice: Locator;

  constructor(page: Page) {
    super(page);
    this.addToCartButton = page.getByRole('button', { name: 'Add to Cart' });
    this.productTitle = page.getByRole('heading', { level: 1 });
    this.productPrice = page.getByTestId('product-price');
  }

  async goto(productId: string) {
    await this.page.goto(`/products/${productId}`);
  }

  async addToCart() {
    await this.addToCartButton.click();
    // Wait for cart update
    await this.page.waitForResponse(
      (response) => response.url().includes('/api/cart')
    );
  }

  async getProductTitle() {
    return await this.productTitle.textContent();
  }

  async getProductPrice() {
    const text = await this.productPrice.textContent();
    return parseFloat(text?.replace('$', '') || '0');
  }
}
typescript
// pages/base-page.ts
import { Page } from '@playwright/test';
import { Navigation } from '../components/navigation';
import { Footer } from '../components/footer';

export class BasePage {
  readonly page: Page;
  readonly navigation: Navigation;
  readonly footer: Footer;

  constructor(page: Page) {
    this.page = page;
    this.navigation = new Navigation(page);
    this.footer = new Footer(page);
  }
}
typescript
// pages/product-page.ts
import { BasePage } from './base-page';
import { Page } from '@playwright/test';

export class ProductPage extends BasePage {
  readonly addToCartButton: Locator;
  readonly productTitle: Locator;
  readonly productPrice: Locator;

  constructor(page: Page) {
    super(page);
    this.addToCartButton = page.getByRole('button', { name: 'Add to Cart' });
    this.productTitle = page.getByRole('heading', { level: 1 });
    this.productPrice = page.getByTestId('product-price');
  }

  async goto(productId: string) {
    await this.page.goto(`/products/${productId}`);
  }

  async addToCart() {
    await this.addToCartButton.click();
    // Wait for cart update
    await this.page.waitForResponse(
      (response) => response.url().includes('/api/cart')
    );
  }

  async getProductTitle() {
    return await this.productTitle.textContent();
  }

  async getProductPrice() {
    const text = await this.productPrice.textContent();
    return parseFloat(text?.replace('$', '') || '0');
  }
}

Modal and Dialog Components

模态框和对话框组件

typescript
// components/modal.ts
export class Modal {
  readonly page: Page;
  readonly container: Locator;
  readonly closeButton: Locator;
  readonly title: Locator;

  constructor(page: Page) {
    this.page = page;
    this.container = page.getByRole('dialog');
    this.closeButton = this.container.getByRole('button', { name: 'Close' });
    this.title = this.container.getByRole('heading');
  }

  async isVisible() {
    return await this.container.isVisible();
  }

  async getTitle() {
    return await this.title.textContent();
  }

  async close() {
    await this.closeButton.click();
    await this.container.waitFor({ state: 'hidden' });
  }
}
typescript
// components/confirmation-modal.ts
import { Modal } from './modal';
import { Page } from '@playwright/test';

export class ConfirmationModal extends Modal {
  readonly confirmButton: Locator;
  readonly cancelButton: Locator;
  readonly message: Locator;

  constructor(page: Page) {
    super(page);
    this.confirmButton = this.container.getByRole('button', {
      name: 'Confirm',
    });
    this.cancelButton = this.container.getByRole('button', {
      name: 'Cancel',
    });
    this.message = this.container.getByTestId('modal-message');
  }

  async confirm() {
    await this.confirmButton.click();
    await this.container.waitFor({ state: 'hidden' });
  }

  async cancel() {
    await this.cancelButton.click();
    await this.container.waitFor({ state: 'hidden' });
  }

  async getMessage() {
    return await this.message.textContent();
  }
}
typescript
// components/modal.ts
export class Modal {
  readonly page: Page;
  readonly container: Locator;
  readonly closeButton: Locator;
  readonly title: Locator;

  constructor(page: Page) {
    this.page = page;
    this.container = page.getByRole('dialog');
    this.closeButton = this.container.getByRole('button', { name: 'Close' });
    this.title = this.container.getByRole('heading');
  }

  async isVisible() {
    return await this.container.isVisible();
  }

  async getTitle() {
    return await this.title.textContent();
  }

  async close() {
    await this.closeButton.click();
    await this.container.waitFor({ state: 'hidden' });
  }
}
typescript
// components/confirmation-modal.ts
import { Modal } from './modal';
import { Page } from '@playwright/test';

export class ConfirmationModal extends Modal {
  readonly confirmButton: Locator;
  readonly cancelButton: Locator;
  readonly message: Locator;

  constructor(page: Page) {
    super(page);
    this.confirmButton = this.container.getByRole('button', {
      name: 'Confirm',
    });
    this.cancelButton = this.container.getByRole('button', {
      name: 'Cancel',
    });
    this.message = this.container.getByTestId('modal-message');
  }

  async confirm() {
    await this.confirmButton.click();
    await this.container.waitFor({ state: 'hidden' });
  }

  async cancel() {
    await this.cancelButton.click();
    await this.container.waitFor({ state: 'hidden' });
  }

  async getMessage() {
    return await this.message.textContent();
  }
}

App Actions Pattern

应用操作模式

High-Level Actions

高级操作

typescript
// pages/app-actions.ts
import { Page } from '@playwright/test';
import { LoginPage } from './login-page';
import { ProductPage } from './product-page';

export class AppActions {
  readonly page: Page;

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

  async login(email: string, password: string) {
    const loginPage = new LoginPage(this.page);
    await loginPage.goto();
    await loginPage.login(email, password);
    await this.page.waitForURL('/dashboard');
  }

  async addProductToCart(productId: string) {
    const productPage = new ProductPage(this.page);
    await productPage.goto(productId);
    await productPage.addToCart();
  }

  async completeCheckout(paymentDetails: PaymentDetails) {
    await this.page.goto('/checkout');
    await this.fillShippingInfo(paymentDetails.shipping);
    await this.fillPaymentInfo(paymentDetails.payment);
    await this.page.getByRole('button', { name: 'Place Order' }).click();
    await this.page.waitForURL('/order-confirmation');
  }

  private async fillShippingInfo(shipping: ShippingInfo) {
    await this.page.getByLabel('Full Name').fill(shipping.name);
    await this.page.getByLabel('Address').fill(shipping.address);
    await this.page.getByLabel('City').fill(shipping.city);
    await this.page.getByLabel('Postal Code').fill(shipping.postalCode);
  }

  private async fillPaymentInfo(payment: PaymentInfo) {
    await this.page.getByLabel('Card Number').fill(payment.cardNumber);
    await this.page.getByLabel('Expiry Date').fill(payment.expiry);
    await this.page.getByLabel('CVV').fill(payment.cvv);
  }
}

interface PaymentDetails {
  shipping: ShippingInfo;
  payment: PaymentInfo;
}

interface ShippingInfo {
  name: string;
  address: string;
  city: string;
  postalCode: string;
}

interface PaymentInfo {
  cardNumber: string;
  expiry: string;
  cvv: string;
}
typescript
// pages/app-actions.ts
import { Page } from '@playwright/test';
import { LoginPage } from './login-page';
import { ProductPage } from './product-page';

export class AppActions {
  readonly page: Page;

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

  async login(email: string, password: string) {
    const loginPage = new LoginPage(this.page);
    await loginPage.goto();
    await loginPage.login(email, password);
    await this.page.waitForURL('/dashboard');
  }

  async addProductToCart(productId: string) {
    const productPage = new ProductPage(this.page);
    await productPage.goto(productId);
    await productPage.addToCart();
  }

  async completeCheckout(paymentDetails: PaymentDetails) {
    await this.page.goto('/checkout');
    await this.fillShippingInfo(paymentDetails.shipping);
    await this.fillPaymentInfo(paymentDetails.payment);
    await this.page.getByRole('button', { name: 'Place Order' }).click();
    await this.page.waitForURL('/order-confirmation');
  }

  private async fillShippingInfo(shipping: ShippingInfo) {
    await this.page.getByLabel('Full Name').fill(shipping.name);
    await this.page.getByLabel('Address').fill(shipping.address);
    await this.page.getByLabel('City').fill(shipping.city);
    await this.page.getByLabel('Postal Code').fill(shipping.postalCode);
  }

  private async fillPaymentInfo(payment: PaymentInfo) {
    await this.page.getByLabel('Card Number').fill(payment.cardNumber);
    await this.page.getByLabel('Expiry Date').fill(payment.expiry);
    await this.page.getByLabel('CVV').fill(payment.cvv);
  }
}

interface PaymentDetails {
  shipping: ShippingInfo;
  payment: PaymentInfo;
}

interface ShippingInfo {
  name: string;
  address: string;
  city: string;
  postalCode: string;
}

interface PaymentInfo {
  cardNumber: string;
  expiry: string;
  cvv: string;
}

Using App Actions in Tests

在测试中使用应用操作

typescript
// tests/checkout.spec.ts
import { test, expect } from '@playwright/test';
import { AppActions } from '../pages/app-actions';

test('should complete checkout flow', async ({ page }) => {
  const app = new AppActions(page);

  await app.login('user@example.com', 'password123');
  await app.addProductToCart('product-123');
  await app.completeCheckout({
    shipping: {
      name: 'John Doe',
      address: '123 Main St',
      city: 'New York',
      postalCode: '10001',
    },
    payment: {
      cardNumber: '4111111111111111',
      expiry: '12/25',
      cvv: '123',
    },
  });

  await expect(page.getByText('Order confirmed')).toBeVisible();
});
typescript
// tests/checkout.spec.ts
import { test, expect } from '@playwright/test';
import { AppActions } from '../pages/app-actions';

test('should complete checkout flow', async ({ page }) => {
  const app = new AppActions(page);

  await app.login('user@example.com', 'password123');
  await app.addProductToCart('product-123');
  await app.completeCheckout({
    shipping: {
      name: 'John Doe',
      address: '123 Main St',
      city: 'New York',
      postalCode: '10001',
    },
    payment: {
      cardNumber: '4111111111111111',
      expiry: '12/25',
      cvv: '123',
    },
  });

  await expect(page.getByText('Order confirmed')).toBeVisible();
});

Advanced Patterns

高级模式

Generic Table Component

通用表格组件

typescript
// components/table.ts
export class Table {
  readonly page: Page;
  readonly container: Locator;

  constructor(page: Page, testId?: string) {
    this.page = page;
    this.container = testId
      ? page.getByTestId(testId)
      : page.getByRole('table');
  }

  async getHeaders() {
    const headers = await this.container
      .getByRole('columnheader')
      .allTextContents();
    return headers;
  }

  async getRowCount() {
    return await this.container.getByRole('row').count() - 1; // Exclude header
  }

  async getRow(index: number) {
    return this.container.getByRole('row').nth(index + 1); // Skip header
  }

  async getCellValue(row: number, column: number) {
    const rowLocator = await this.getRow(row);
    const cell = rowLocator.getByRole('cell').nth(column);
    return await cell.textContent();
  }

  async getCellByColumnName(row: number, columnName: string) {
    const headers = await this.getHeaders();
    const columnIndex = headers.indexOf(columnName);
    if (columnIndex === -1) {
      throw new Error(`Column "${columnName}" not found`);
    }
    return await this.getCellValue(row, columnIndex);
  }

  async findRowByValue(columnName: string, value: string) {
    const headers = await this.getHeaders();
    const columnIndex = headers.indexOf(columnName);
    const rowCount = await this.getRowCount();

    for (let i = 0; i < rowCount; i++) {
      const cellValue = await this.getCellValue(i, columnIndex);
      if (cellValue === value) {
        return await this.getRow(i);
      }
    }

    return null;
  }
}
typescript
// components/table.ts
export class Table {
  readonly page: Page;
  readonly container: Locator;

  constructor(page: Page, testId?: string) {
    this.page = page;
    this.container = testId
      ? page.getByTestId(testId)
      : page.getByRole('table');
  }

  async getHeaders() {
    const headers = await this.container
      .getByRole('columnheader')
      .allTextContents();
    return headers;
  }

  async getRowCount() {
    return await this.container.getByRole('row').count() - 1; // Exclude header
  }

  async getRow(index: number) {
    return this.container.getByRole('row').nth(index + 1); // Skip header
  }

  async getCellValue(row: number, column: number) {
    const rowLocator = await this.getRow(row);
    const cell = rowLocator.getByRole('cell').nth(column);
    return await cell.textContent();
  }

  async getCellByColumnName(row: number, columnName: string) {
    const headers = await this.getHeaders();
    const columnIndex = headers.indexOf(columnName);
    if (columnIndex === -1) {
      throw new Error(`Column "${columnName}" not found`);
    }
    return await this.getCellValue(row, columnIndex);
  }

  async findRowByValue(columnName: string, value: string) {
    const headers = await this.getHeaders();
    const columnIndex = headers.indexOf(columnName);
    const rowCount = await this.getRowCount();

    for (let i = 0; i < rowCount; i++) {
      const cellValue = await this.getCellValue(i, columnIndex);
      if (cellValue === value) {
        return await this.getRow(i);
      }
    }

    return null;
  }
}

Form Component with Validation

带验证的表单组件

typescript
// components/form.ts
export class Form {
  readonly page: Page;
  readonly container: Locator;
  readonly submitButton: Locator;

  constructor(page: Page, formTestId: string) {
    this.page = page;
    this.container = page.getByTestId(formTestId);
    this.submitButton = this.container.getByRole('button', {
      name: /submit|save|create/i,
    });
  }

  async fillField(label: string, value: string) {
    await this.container.getByLabel(label).fill(value);
  }

  async selectOption(label: string, value: string) {
    await this.container.getByLabel(label).selectOption(value);
  }

  async checkCheckbox(label: string) {
    await this.container.getByLabel(label).check();
  }

  async uncheckCheckbox(label: string) {
    await this.container.getByLabel(label).uncheck();
  }

  async submit() {
    await this.submitButton.click();
  }

  async getFieldError(label: string) {
    const field = this.container.getByLabel(label);
    const fieldId = await field.getAttribute('id');
    const error = this.container.locator(`[aria-describedby="${fieldId}"]`);
    return await error.textContent();
  }

  async hasError(label: string) {
    const error = await this.getFieldError(label);
    return error !== null && error.trim() !== '';
  }

  async getFormErrors() {
    const errors = await this.container
      .locator('[role="alert"]')
      .allTextContents();
    return errors.filter((e) => e.trim() !== '');
  }
}
typescript
// components/form.ts
export class Form {
  readonly page: Page;
  readonly container: Locator;
  readonly submitButton: Locator;

  constructor(page: Page, formTestId: string) {
    this.page = page;
    this.container = page.getByTestId(formTestId);
    this.submitButton = this.container.getByRole('button', {
      name: /submit|save|create/i,
    });
  }

  async fillField(label: string, value: string) {
    await this.container.getByLabel(label).fill(value);
  }

  async selectOption(label: string, value: string) {
    await this.container.getByLabel(label).selectOption(value);
  }

  async checkCheckbox(label: string) {
    await this.container.getByLabel(label).check();
  }

  async uncheckCheckbox(label: string) {
    await this.container.getByLabel(label).uncheck();
  }

  async submit() {
    await this.submitButton.click();
  }

  async getFieldError(label: string) {
    const field = this.container.getByLabel(label);
    const fieldId = await field.getAttribute('id');
    const error = this.container.locator(`[aria-describedby="${fieldId}"]`);
    return await error.textContent();
  }

  async hasError(label: string) {
    const error = await this.getFieldError(label);
    return error !== null && error.trim() !== '';
  }

  async getFormErrors() {
    const errors = await this.container
      .locator('[role="alert"]')
      .allTextContents();
    return errors.filter((e) => e.trim() !== '');
  }
}

Waiting Strategies in Page Objects

页面对象中的等待策略

typescript
export class DashboardPage {
  readonly page: Page;
  readonly loadingSpinner: Locator;
  readonly dataTable: Locator;

  constructor(page: Page) {
    this.page = page;
    this.loadingSpinner = page.getByTestId('loading-spinner');
    this.dataTable = page.getByRole('table');
  }

  async goto() {
    await this.page.goto('/dashboard');
    await this.waitForPageLoad();
  }

  async waitForPageLoad() {
    // Wait for loading spinner to disappear
    await this.loadingSpinner.waitFor({ state: 'hidden' });

    // Wait for data to load
    await this.dataTable.waitFor({ state: 'visible' });

    // Wait for network idle
    await this.page.waitForLoadState('networkidle');
  }

  async refreshData() {
    const refreshButton = this.page.getByRole('button', { name: 'Refresh' });
    await refreshButton.click();

    // Wait for API response
    await this.page.waitForResponse(
      (response) =>
        response.url().includes('/api/dashboard') && response.status() === 200
    );

    await this.waitForPageLoad();
  }
}
typescript
export class DashboardPage {
  readonly page: Page;
  readonly loadingSpinner: Locator;
  readonly dataTable: Locator;

  constructor(page: Page) {
    this.page = page;
    this.loadingSpinner = page.getByTestId('loading-spinner');
    this.dataTable = page.getByRole('table');
  }

  async goto() {
    await this.page.goto('/dashboard');
    await this.waitForPageLoad();
  }

  async waitForPageLoad() {
    // Wait for loading spinner to disappear
    await this.loadingSpinner.waitFor({ state: 'hidden' });

    // Wait for data to load
    await this.dataTable.waitFor({ state: 'visible' });

    // Wait for network idle
    await this.page.waitForLoadState('networkidle');
  }

  async refreshData() {
    const refreshButton = this.page.getByRole('button', { name: 'Refresh' });
    await refreshButton.click();

    // Wait for API response
    await this.page.waitForResponse(
      (response) =>
        response.url().includes('/api/dashboard') && response.status() === 200
    );

    await this.waitForPageLoad();
  }
}

Handling Dynamic Content

处理动态内容

Lists and Collections

列表和集合

typescript
export class ProductListPage {
  readonly page: Page;
  readonly productCards: Locator;

  constructor(page: Page) {
    this.page = page;
    this.productCards = page.getByTestId('product-card');
  }

  async goto() {
    await this.page.goto('/products');
  }

  async getProductCount() {
    return await this.productCards.count();
  }

  async getProductCard(index: number) {
    return this.productCards.nth(index);
  }

  async getProductCardByName(name: string) {
    return this.productCards.filter({ hasText: name }).first();
  }

  async getAllProductNames() {
    const names = await this.productCards
      .locator('h3')
      .allTextContents();
    return names;
  }

  async clickProduct(name: string) {
    const card = await this.getProductCardByName(name);
    await card.click();
  }

  async addToCartByName(name: string) {
    const card = await this.getProductCardByName(name);
    await card.getByRole('button', { name: 'Add to Cart' }).click();
  }
}
typescript
export class ProductListPage {
  readonly page: Page;
  readonly productCards: Locator;

  constructor(page: Page) {
    this.page = page;
    this.productCards = page.getByTestId('product-card');
  }

  async goto() {
    await this.page.goto('/products');
  }

  async getProductCount() {
    return await this.productCards.count();
  }

  async getProductCard(index: number) {
    return this.productCards.nth(index);
  }

  async getProductCardByName(name: string) {
    return this.productCards.filter({ hasText: name }).first();
  }

  async getAllProductNames() {
    const names = await this.productCards
      .locator('h3')
      .allTextContents();
    return names;
  }

  async clickProduct(name: string) {
    const card = await this.getProductCardByName(name);
    await card.click();
  }

  async addToCartByName(name: string) {
    const card = await this.getProductCardByName(name);
    await card.getByRole('button', { name: 'Add to Cart' }).click();
  }
}

Search and Filter

搜索和筛选

typescript
export class SearchPage {
  readonly page: Page;
  readonly searchInput: Locator;
  readonly searchButton: Locator;
  readonly results: Locator;
  readonly filters: Locator;

  constructor(page: Page) {
    this.page = page;
    this.searchInput = page.getByRole('searchbox');
    this.searchButton = page.getByRole('button', { name: 'Search' });
    this.results = page.getByTestId('search-results');
    this.filters = page.getByTestId('filters');
  }

  async search(query: string) {
    await this.searchInput.fill(query);
    await this.searchButton.click();
    await this.waitForResults();
  }

  async applyFilter(filterName: string, value: string) {
    await this.filters
      .getByRole('button', { name: filterName })
      .click();
    await this.page
      .getByRole('checkbox', { name: value })
      .check();
    await this.waitForResults();
  }

  async getResultCount() {
    const countText = await this.results
      .getByTestId('result-count')
      .textContent();
    return parseInt(countText?.match(/\d+/)?.[0] || '0');
  }

  private async waitForResults() {
    await this.page.waitForResponse(
      (response) => response.url().includes('/api/search')
    );
    await this.results.getByTestId('result-item').first().waitFor();
  }
}
typescript
export class SearchPage {
  readonly page: Page;
  readonly searchInput: Locator;
  readonly searchButton: Locator;
  readonly results: Locator;
  readonly filters: Locator;

  constructor(page: Page) {
    this.page = page;
    this.searchInput = page.getByRole('searchbox');
    this.searchButton = page.getByRole('button', { name: 'Search' });
    this.results = page.getByTestId('search-results');
    this.filters = page.getByTestId('filters');
  }

  async search(query: string) {
    await this.searchInput.fill(query);
    await this.searchButton.click();
    await this.waitForResults();
  }

  async applyFilter(filterName: string, value: string) {
    await this.filters
      .getByRole('button', { name: filterName })
      .click();
    await this.page
      .getByRole('checkbox', { name: value })
      .check();
    await this.waitForResults();
  }

  async getResultCount() {
    const countText = await this.results
      .getByTestId('result-count')
      .textContent();
    return parseInt(countText?.match(/\d+/)?.[0] || '0');
  }

  private async waitForResults() {
    await this.page.waitForResponse(
      (response) => response.url().includes('/api/search')
    );
    await this.results.getByTestId('result-item').first().waitFor();
  }
}

Type-Safe Page Objects

类型安全的页面对象

Using TypeScript Interfaces

使用TypeScript接口

typescript
// types/user.ts
export interface User {
  email: string;
  password: string;
  firstName?: string;
  lastName?: string;
}

export interface Product {
  id: string;
  name: string;
  price: number;
  description?: string;
}
typescript
// pages/registration-page.ts
import { User } from '../types/user';

export class RegistrationPage {
  readonly page: Page;

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

  async goto() {
    await this.page.goto('/register');
  }

  async register(user: User) {
    await this.page.getByLabel('Email').fill(user.email);
    await this.page.getByLabel('Password').fill(user.password);

    if (user.firstName) {
      await this.page.getByLabel('First Name').fill(user.firstName);
    }

    if (user.lastName) {
      await this.page.getByLabel('Last Name').fill(user.lastName);
    }

    await this.page.getByRole('button', { name: 'Register' }).click();
  }
}
typescript
// types/user.ts
export interface User {
  email: string;
  password: string;
  firstName?: string;
  lastName?: string;
}

export interface Product {
  id: string;
  name: string;
  price: number;
  description?: string;
}
typescript
// pages/registration-page.ts
import { User } from '../types/user';

export class RegistrationPage {
  readonly page: Page;

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

  async goto() {
    await this.page.goto('/register');
  }

  async register(user: User) {
    await this.page.getByLabel('Email').fill(user.email);
    await this.page.getByLabel('Password').fill(user.password);

    if (user.firstName) {
      await this.page.getByLabel('First Name').fill(user.firstName);
    }

    if (user.lastName) {
      await this.page.getByLabel('Last Name').fill(user.lastName);
    }

    await this.page.getByRole('button', { name: 'Register' }).click();
  }
}

Builder Pattern for Test Data

测试数据的构建器模式

typescript
// builders/user-builder.ts
import { User } from '../types/user';

export class UserBuilder {
  private user: Partial<User> = {};

  withEmail(email: string): this {
    this.user.email = email;
    return this;
  }

  withPassword(password: string): this {
    this.user.password = password;
    return this;
  }

  withName(firstName: string, lastName: string): this {
    this.user.firstName = firstName;
    this.user.lastName = lastName;
    return this;
  }

  build(): User {
    if (!this.user.email || !this.user.password) {
      throw new Error('Email and password are required');
    }
    return this.user as User;
  }
}
typescript
// tests/registration.spec.ts
import { UserBuilder } from '../builders/user-builder';
import { RegistrationPage } from '../pages/registration-page';

test('should register new user', async ({ page }) => {
  const user = new UserBuilder()
    .withEmail('newuser@example.com')
    .withPassword('SecurePass123!')
    .withName('John', 'Doe')
    .build();

  const registrationPage = new RegistrationPage(page);
  await registrationPage.goto();
  await registrationPage.register(user);

  await expect(page).toHaveURL('/welcome');
});
typescript
// builders/user-builder.ts
import { User } from '../types/user';

export class UserBuilder {
  private user: Partial<User> = {};

  withEmail(email: string): this {
    this.user.email = email;
    return this;
  }

  withPassword(password: string): this {
    this.user.password = password;
    return this;
  }

  withName(firstName: string, lastName: string): this {
    this.user.firstName = firstName;
    this.user.lastName = lastName;
    return this;
  }

  build(): User {
    if (!this.user.email || !this.user.password) {
      throw new Error('Email and password are required');
    }
    return this.user as User;
  }
}
typescript
// tests/registration.spec.ts
import { UserBuilder } from '../builders/user-builder';
import { RegistrationPage } from '../pages/registration-page';

test('should register new user', async ({ page }) => {
  const user = new UserBuilder()
    .withEmail('newuser@example.com')
    .withPassword('SecurePass123!')
    .withName('John', 'Doe')
    .build();

  const registrationPage = new RegistrationPage(page);
  await registrationPage.goto();
  await registrationPage.register(user);

  await expect(page).toHaveURL('/welcome');
});

When to Use This Skill

何时使用本技能

  • Creating new page objects for test automation
  • Refactoring existing tests to use Page Object Model
  • Building reusable component libraries for tests
  • Implementing app actions for complex user flows
  • Standardizing locator strategies across a test suite
  • Creating type-safe page objects with TypeScript
  • Designing maintainable test architecture
  • Handling dynamic content and complex UI interactions
  • Building form and table abstractions
  • Establishing page object patterns for a team
  • 创建新的测试自动化页面对象
  • 重构现有测试以使用页面对象模型
  • 构建可复用的测试组件库
  • 为复杂用户流实现应用操作
  • 在测试套件中标准化定位器策略
  • 使用TypeScript创建类型安全的页面对象
  • 设计可维护的测试架构
  • 处理动态内容和复杂UI交互
  • 构建表单和表格抽象
  • 为团队建立页面对象模式

Resources

资源