如何在不重写方法的前提下扩展Playwright Locator添加工具函数？

因为Playwright的Locator是接口而非可实例化的类，直接继承或实现它需要手动重写所有方法，显然不现实。正确的做法是用委托/代理模式：持有原生Locator实例，把所有未自定义的方法、属性都转发给原生实例，同时添加自己的工具函数。

下面提供两种实用方案：

方案一：手动委托（按需转发） #

适合需要精确控制哪些方法被转发的场景，手动实现常用方法的转发，同时添加自定义逻辑：

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

export class LocatorWrapper {
  private readonly locator: Locator;

  constructor(locator: Locator) {
    this.locator = locator;
  }

  // 自定义工具方法
  public async hoverAndDoubleClick() {
    await this.locator.hover();
    await this.locator.click();
    await this.locator.click();
  }

  // 转发原生Locator的常用方法/属性，按需添加即可
  get first() {
    return new LocatorWrapper(this.locator.first);
  }

  nth(index: number) {
    return new LocatorWrapper(this.locator.nth(index));
  }

  async click(options?: Parameters<Locator['click']>[0]) {
    return this.locator.click(options);
  }

  async hover(options?: Parameters<Locator['hover']>[0]) {
    return this.locator.hover(options);
  }

  async fill(value: string, options?: Parameters<Locator['fill']>[1]) {
    return this.locator.fill(value, options);
  }

  // 其他需要的原生方法，照着上面的格式转发就行
}

方案二：ES6 Proxy自动代理（更简洁） #

用Proxy自动拦截所有属性和方法的访问，无需手动一个个转发原生方法，还能自动处理链式调用（比如.first.nth(0)）：

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

export function createLocatorWrapper(locator: Locator): Locator & { hoverAndDoubleClick: () => Promise<void> } {
  const customMethods = {
    async hoverAndDoubleClick() {
      await locator.hover();
      await locator.click();
      await locator.click();
    }
  };

  return new Proxy(customMethods, {
    get(target, prop) {
      // 优先用自定义的方法/属性
      if (prop in target) {
        return (target as any)[prop];
      }
      // 拿到原生Locator对应的属性/方法
      const nativeItem = (locator as any)[prop];
      // 如果是函数，绑定原生上下文避免this指向错误
      if (typeof nativeItem === 'function') {
        return nativeItem.bind(locator);
      }
      // 如果是返回Locator的属性（比如first、last），递归包装成自定义实例
      if (typeof nativeItem === 'object' && nativeItem !== null) {
        return createLocatorWrapper(nativeItem as Locator);
      }
      // 其他类型直接返回原生值
      return nativeItem;
    }
  }) as Locator & { hoverAndDoubleClick: () => Promise<void> };
}

使用示例 #

不管用哪种方案，都能无缝兼容原生Locator的所有操作，同时调用自定义方法：

import { test } from '@playwright/test';
import { createLocatorWrapper } from './locator-wrapper'; // 或者导入LocatorWrapper类

test('测试包装后的Locator', async ({ page }) => {
  const nativeLoc = page.getByText('测试按钮');
  const wrappedLoc = createLocatorWrapper(nativeLoc); // 或者 new LocatorWrapper(nativeLoc)

  // 调用自定义方法
  await wrappedLoc.hoverAndDoubleClick();

  // 调用原生方法，完全和原生Locator一样用
  await wrappedLoc.fill('输入内容');
  await wrappedLoc.first.click();
});

内容的提问来源于stack exchange，提问作者Andrea Costanzo