自动化测试 / 系统课时

配置断言超时

配置断言超时

断言超时决定 Playwright 愿意为“页面最终达到期望状态”等待多久。合理设置应覆盖正常业务延迟,又不能把真实故障拖成漫长等待。本节区分全局与局部断言超时,并用一个慢状态更新示例验证覆盖规则。

学习目标

  • 配置项目级 expect 断言超时
  • 为个别慢操作设置局部断言超时
  • 区分断言超时、测试超时与操作超时的职责

先分清断言超时的职责

Playwright 的 Web-First 断言会在超时窗口内重复检查条件。断言超时只控制这一类等待,不等于整个测试最多能运行多久,也不等于点击、填写等操作的超时。

常见的三个层次可以这样理解:

设置 控制范围 适合解决的问题
expect.timeout Web-First 断言 元素文本、可见性、数量等最终状态
timeout 整个测试 防止单个测试整体运行过久
actionTimeout 点击、填写等操作 限制单次页面操作的等待时间

断言等待上限必须小于测试整体还能提供的时间预算。否则即使给断言设置了更大的值,测试本身也可能先超时退出。

设置项目级断言上限

可以在 playwright.config.ts 的 expect 中定义统一上限。下面把普通断言等待设置为 1 秒,同时保留 10 秒的测试总超时,便于后面的慢断言做局部覆盖。

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

export default defineConfig({
  timeout: 10_000,
  expect: {
    timeout: 1_000,
  },
});

生效行为:未单独指定 timeout 的 Web-First 断言最多重试约 1 秒;测试整体仍受 10 秒上限约束。可通过运行任意故意延迟超过 1 秒的断言验证配置是否生效。

为慢断言做局部覆盖

如果只有少数业务动作天然更慢,不要把全局超时一起放大。下面页面在 1.5 秒后才把状态改成 done,因此该断言显式给出 2.5 秒上限。

ts
import { test, expect } from '@playwright/test';

test('慢状态使用局部断言超时', async ({ page }) => {
  await page.setContent(`
    <div data-testid="status">processing</div>
    <script>
      setTimeout(() => {
        document.querySelector('[data-testid="status"]').textContent = 'done';
      }, 1500);
    </script>
  `);

  const status = page.getByTestId('status');

  // 覆盖全局 1 秒限制,只放宽这一条确实较慢的断言。
  await expect(status).toHaveText('done', { timeout: 2_500 });
  console.log('status assertion passed');
});

预期输出:

text
status assertion passed

如果删除局部的 { timeout: 2_500 },这条断言会受全局 1 秒配置约束,并在状态更新前失败。

按业务响应时间确定数值

超时应该来自可解释的业务上限,而不是测试失败后不断加大。可以先观察正常环境中的接口和 UI 完成时间,再给少量网络与调度抖动留余量。例如,大多数搜索结果 1 秒内出现,就没有必要把所有断言统一放宽到几十秒。

超时失败时先查条件是否可能成立

断言超时表示在等待窗口内始终没有观察到期望状态,但根因不一定是“时间不够”。应先检查 Locator 是否指向正确元素、触发业务动作是否成功、页面是否进入了预期状态,再决定是否调整时间。

当某个场景确实有稳定且合理的较长响应上限时,用局部 timeout 明确表达例外;只有大多数断言都需要相同等待预算时,才调整项目级 expect.timeout。这样既保留正常测试的快速失败能力,也能容纳真正的慢业务流程。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

配置断言超时

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通