在Playwright测试项目中，随着用例数量增加，直接在测试函数里书写选择器会让代码变得难以维护。页面对象模型（POM）通过将页面元素和操作封装成类，让测试代码只关心业务步骤。可是不少团队虽然引入了POM，却依然使用纯JavaScript编写，享受不到类型系统带来的保护。TypeScript的加入可以改变这一局面，让编译器在测试运行前就发现属性拼写错误、参数类型不匹配等问题。本文会从基础的类型化页面对象开始，逐步讲解如何利用抽象基类、泛型以及Playwright的fixtures机制，构建一套健壮且易维护的类型化测试架构。

为什么需要类型化页面对象模型

传统的POM实现通常只借助JavaScript的class把选择器集中起来，测试代码通过调用页面对象的方法来操作页面。这种方式确实减少了选择器的重复，但无法阻止开发者写出错误的属性名或者传入错误类型的数据。例如，一个登录页面对象可能定义了usernameInput属性，但测试代码中不小心写成了userNameInput，拼写差异只有在运行时才可能暴露为undefined错误，浪费排查时间。更隐蔽的问题出现在方法参数上，比如登录方法期望接收字符串类型的用户名和密码，但调用时传入了对象，这种错误同样难以在早期发现。

TypeScript的静态类型检查可以很好地弥补这些缺陷。当你把页面对象类中的属性声明为Locator类型，把方法参数和返回值标注清楚之后，任何不符合约定的调用都会在编译阶段被拦截。这对多人协作的测试项目尤其重要，因为新加入的成员可以通过编辑器的自动补全和类型提示快速理解页面对象暴露了哪些能力，而无需打开实现文件逐行阅读。类型信息充当了活文档的角色，同时把一部分回归测试的负担转移到了编译器上。

下面看一个未使用类型约束的Playwright页面对象示例：

class LoginPage {
  constructor(page) {
    this.page = page;
  }
  async login(username, password) {
    await this.page.fill('#username', username);
    await this.page.fill('#password', password);
    await this.page.click('#login-button');
  }
}

这个类没有声明任何字段类型，方法参数也没有约束。调用login时如果传入数字或空值，测试仍会尝试运行，直到Playwright因为选择器无法定位或输入不符合预期而失败。而加入TypeScript之后，这些问题可以在开发阶段被识别。

用TypeScript定义基础页面对象

首先，将Playwright的Page和Locator类型引入到页面对象类中。通常建议把元素定位器声明为readonly属性，这样在类的实例创建后，外部代码无法重新赋值或替换定位器，保证页面对象始终指向正确的元素。构造函数的参数可以使用private修饰符，这样既保留了page的引用，又不会暴露给外部直接访问，维持封装性。

import { Page, Locator } from '@playwright/test';
export class LoginPage {
  readonly usernameInput: Locator;
  readonly passwordInput: Locator;
  readonly loginButton: Locator;
  constructor(private page: Page) {
    this.usernameInput = page.locator('#username');
    this.passwordInput = page.locator('#password');
    this.loginButton = page.locator('#login-button');
  }
  async login(username: string, password: string): Promise<void> {
    await this.usernameInput.fill(username);
    await this.passwordInput.fill(password);
    await this.loginButton.click();
  }
}

在这个类中，usernameInput、passwordInput和loginButton都被明确标注为Locator类型。当你在测试文件中输入loginPage.时，编辑器会列出这些属性以及login方法，并且每个属性的类型都是已知的。如果尝试访问一个不存在的属性，例如loginPage.userNameInput，TypeScript会立即给出编译错误。这种即时反馈大大减少了调试时间。

除了属性类型，方法的签名同样重要。login方法声明了username和password都必须是string类型，返回值是Promise<void>。如果测试代码传入一个数字，编译器会拒绝编译。这些约束确保了页面对象的使用者必须按照约定提供参数，避免了运行时类型错误。此外，readonly修饰符阻止了在测试中意外修改定位器的行为，例如把usernameInput指向另一个选择器，这类错误也被杜绝了。

利用抽象基类和泛型提升复用性

当项目中有多个页面对象时，很多操作是重复的，比如导航到指定URL、等待页面加载完成、获取页面标题等。可以把这些公共逻辑提取到一个抽象基类中，由具体页面类继承并实现各自的特定部分。泛型的引入则可以进一步提升灵活性，让基类的方法返回当前子类的类型，从而支持链式调用和更精确的类型推断。

import { Page } from '@playwright/test';
export abstract class BasePage<T extends BasePage<T>> {
  protected constructor(protected page: Page) {}
  abstract url: string;
  async navigate(): Promise<T> {
    await this.page.goto(this.url);
    return this as unknown as T;
  }
  async getTitle(): Promise<string> {
    return await this.page.title();
  }
}

这里的BasePage<T>使用了递归泛型约束，要求类型参数T必须是BasePage<T>的子类型。这样做的好处是，navigate方法返回Promise<T>，当子类调用navigate时，返回值会被推断为子类自身的类型。例如，LoginPage继承BasePage<LoginPage>后，调用navigate()得到的就是LoginPage实例，而不是笼统的BasePage。这为测试代码提供了更准确的类型信息，也避免了不必要的类型断言。

import { Page } from '@playwright/test';
import { BasePage } from './BasePage';
export class LoginPage extends BasePage<LoginPage> {
  readonly url = '/login';
  constructor(page: Page) {
    super(page);
  }
}

子类只需要提供url属性并调用super构造函数，就自动获得了navigate和getTitle方法。在测试中，你可以直接写const login = await new LoginPage(page).navigate();，此时login的类型就是LoginPage，后续调用login.usernameInput都会得到类型提示。这种模式减少了样板代码，保持了页面对象之间的统一风格。

通过测试夹具注入类型化页面对象

Playwright Test提供了fixture机制，可以在测试运行前创建并注入所需的对象。配合TypeScript，我们可以把页面对象类型定义到fixture中，让测试函数签名自动获得准确的类型提示。这样测试代码就不需要手动实例化页面对象，也便于统一处理页面对象的创建和销毁逻辑。

import { test as base, expect } from '@playwright/test';
import { LoginPage } from './pages/LoginPage';
type Pages = {
  loginPage: LoginPage;
};
export const test = base.extend<Pages>({
  loginPage: async ({ page }, use) => {
    const loginPage = new LoginPage(page);
    await use(loginPage);
  },
});
export { expect };

在上述代码中，base.extend<Pages>声明了扩展后的test对象拥有loginPage这个fixture，类型为LoginPage。在具体的测试用例中，只要从签名中解构出loginPage，TypeScript就会自动推断它的类型，并提供所有页面对象方法和属性的补全。如果页面对象发生了变化，例如某个方法被重命名或删除，测试文件会在编译阶段报错，而不是等到测试执行时才发现问题。

这种类型化fixture的另一个优势是，它可以和其他fixture组合使用。比如你可以在loginPage的fixture中先执行一些前置操作，比如设置本地存储或模拟API响应，然后再将页面对象实例交给测试。页面对象本身也可以在构造函数中接收更多依赖，只要把这些依赖也定义成fixture并注入即可。类型系统会保证所有依赖的匹配关系正确无误。

处理动态内容和复杂交互

页面对象中经常需要处理动态加载的元素或者需要等待特定状态出现后才能继续操作。TypeScript并不会影响这些异步行为的写法，但可以帮助你把等待逻辑封装得更清晰。比如，一个仪表盘页面可能有一个异步渲染的图表区域，你可以提供一个方法专门等待该区域可见，并在方法签名中明确返回Promise<void>，让调用方知道这是一个异步操作。

import { Page, Locator } from '@playwright/test';
export class DashboardPage {
  readonly chartArea: Locator;
  constructor(private page: Page) {
    this.chartArea = page.locator('.chart-area');
  }
  async waitForChartReady(): Promise<void> {
    await this.chartArea.waitFor({ state: 'visible' });
    await this.page.waitForTimeout(500);
  }
  async getChartData(): Promise<string[]> {
    await this.waitForChartReady();
    return await this.chartArea.locator('li').allTextContents();
  }
}

在这个示例中，waitForChartReady方法负责处理等待逻辑，返回Promise<void>。getChartData方法则先调用waitForChartReady，再获取所有列表项的文本内容，返回值类型是Promise<string[]>。这样的设计把动态等待的复杂性隐藏在页面对象内部，测试代码只需调用getChartData并断言返回的数组内容即可。如果方法返回类型标注不准确，TypeScript会给出错误提示，避免测试中对返回值进行不恰当的操作。

对于包含多个参数的方法，可以使用接口来约束参数对象的结构。例如，一个搜索页面可能接收一组过滤条件，定义SearchFilters接口可以确保调用方传入所有必填字段并且类型正确。类型系统在这里起到了文档和约束的双重作用，让页面对象的使用者无需阅读实现就能理解所需的数据结构。

类型安全还能延伸到Playwright的断言环节。虽然断言通常直接写在测试里，但你可以把常用的断言逻辑封装到页面对象的方法中，并用类型标注返回结果。这样既能复用断言代码，又能保持类型一致性。当页面结构变化导致某个断言不再适用时，修改页面对象即可，所有使用该方法的测试都会自动感知类型变化。