Playwright+Cucumber.js(TS)原生断言功能失效的解决方案咨询

问题背景 #

使用TypeScript编写Playwright与Cucumber.js结合的测试时，遇到原生断言的自定义错误消息、软断言功能失效的问题；既需要自定义错误消息，又不想放弃Playwright原生断言的自动等待特性，同时对自行编写的轮询断言可靠性存疑。

一、修复Playwright原生断言在Cucumber中的适配问题 #

1. 自定义错误消息失效修复

Playwright原生断言的{ message: "自定义内容" }参数在Cucumber中无法正常显示，是因为Cucumber默认会捕获并格式化错误输出。可以通过手动包装断言逻辑，强制注入自定义消息：

// 封装带自定义消息的Playwright断言
async function assertElementVisible(locator: Locator, customMsg: string) {
  try {
    await locator.waitFor({ state: "visible" });
  } catch (err) {
    throw new Error(`${customMsg}: ${(err as Error).message}`);
  }
}

2. 软断言功能修复

Playwright默认的软断言依赖其内置Test Runner的上下文，与Cucumber上下文不兼容。可以手动实现简易软断言，在Cucumber钩子中统一抛出错误：

// 收集软断言错误的数组
const softAssertErrors: Error[] = [];

// 软断言封装
async function softAssert(condition: Promise<boolean>, errorMsg: string) {
  try {
    const result = await condition;
    if (!result) throw new Error(errorMsg);
  } catch (err) {
    softAssertErrors.push(err as Error);
  }
}

// 在Cucumber的After钩子中检查并抛出软断言错误
After(async function () {
  if (softAssertErrors.length > 0) {
    throw new Error(`软断言失败汇总：\n${softAssertErrors.map(e => e.message).join("\n")}`);
  }
});

二、混合使用Playwright自动等待与Chai断言 #

如果需要稳定的自定义错误消息功能，可以保留Playwright的自动等待能力，搭配Chai做断言逻辑：

import { expect as chaiExpect } from "chai";

// 封装：用Playwright等待元素状态，用Chai做断言
async function assertElementText(locator: Locator, expectedText: string, customMsg: string) {
  // 利用Playwright自动等待获取元素文本
  const actualText = await locator.textContent({ timeout: 5000 });
  // 用Chai实现断言并传入自定义错误消息
  chaiExpect(actualText).to.equal(expectedText, customMsg);
}

这种方式既保留了Playwright对元素状态的自动等待，又能完全利用Chai灵活的断言语法和自定义错误消息能力。

三、优化自定义轮询断言 #

你当前的waitForPooling存在核心问题：传入的condition是同步布尔值，无法处理Playwright的异步操作（如元素状态检查）。优化后的版本支持异步条件，且错误消息稳定可靠：

public static async waitForPolling(
  condition: () => Promise<boolean>,
  timeout: number = settings.std_timeout,
  interval: number = settings.interval_timeout,
  errMsg: string = ''
): Promise<void> {
  const startTime = Date.now();
  while (Date.now() - startTime < timeout) {
    try {
      const result = await condition();
      if (result) return;
    } catch {}
    await new Promise(resolve => setTimeout(resolve, interval));
  }
  // 超时后抛出自定义或默认消息
  const message = errMsg || `Timeout after ${timeout}ms`;
  throw new Error(message);
}

// 使用示例：检查提交按钮是否可见
await waitForPolling(
  async () => await page.locator("#submit-btn").isVisible(),
  5000,
  100,
  "提交按钮未在5秒内加载完成"
);

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