跳到主要内容

时钟

引言

准确模拟与时间相关的行为对于验证应用程序的正确性至关重要。利用时钟功能,开发人员可以在测试中操作和控制时间,从而能够精确验证渲染时间、超时、计划任务等功能,而无需忍受实时执行带来的延迟和不确定性。

时钟 API 提供了以下控制时间的方法

  • setFixedTime: 设置 Date.now()new Date() 的固定时间。
  • install: 初始化时钟并允许你
    • pauseAt: 在特定时间暂停时间。
    • fastForward: 快进时间。
    • runFor: 让时间运行指定时长。
    • resume: 恢复时间。
  • setSystemTime: 设置当前系统时间。

建议的方法是使用 setFixedTime 将时间设置为特定值。如果这种方法不适用于你的用例,你可以使用 install,它允许你稍后暂停时间、快进时间、让时间流逝等。 setSystemTime 仅建议用于高级用例。

注意

page.clock 会覆盖与时间相关的原生全局类和函数,从而可以手动控制它们

  • Date
  • setTimeout
  • clearTimeout
  • setInterval
  • clearInterval
  • requestAnimationFrame
  • cancelAnimationFrame
  • requestIdleCallback
  • cancelIdleCallback
  • performance
  • Event.timeStamp
警告

如果在测试中的任何地方调用 install,则该调用 必须 在任何其他时钟相关调用(参见上面的列表)之前发生。乱序调用这些方法将导致未定义的行为。例如,你不能先调用 setInterval,然后调用 install,再调用 clearInterval,因为 install 会覆盖时钟函数的原生定义。

使用预定义时间进行测试

通常,你只需要伪造 Date.now,同时让计时器正常运行。这样,时间会自然流逝,但 Date.now 始终返回固定值。

<div id="current-time" data-testid="current-time"></div>
<script>
const renderTime = () => {
document.getElementById('current-time').textContent =
new Date().toLocaleString();
};
setInterval(renderTime, 1000);
</script>
await page.clock.setFixedTime(new Date('2024-02-02T10:00:00'));
await page.goto('http://localhost:3333');
await expect(page.getByTestId('current-time')).toHaveText('2/2/2024, 10:00:00 AM');

await page.clock.setFixedTime(new Date('2024-02-02T10:30:00'));
// We know that the page has a timer that updates the time every second.
await expect(page.getByTestId('current-time')).toHaveText('2/2/2024, 10:30:00 AM');

一致的时间和计时器

有时你的计时器依赖于 Date.now,当 Date.now 值随时间不变时会感到困惑。在这种情况下,你可以在测试时安装时钟并快进到感兴趣的时间。

<div id="current-time" data-testid="current-time"></div>
<script>
const renderTime = () => {
document.getElementById('current-time').textContent =
new Date().toLocaleString();
};
setInterval(renderTime, 1000);
</script>
// Initialize clock with some time before the test time and let the page load
// naturally. `Date.now` will progress as the timers fire.
await page.clock.install({ time: new Date('2024-02-02T08:00:00') });
await page.goto('http://localhost:3333');

// Pretend that the user closed the laptop lid and opened it again at 10am,
// Pause the time once reached that point.
await page.clock.pauseAt(new Date('2024-02-02T10:00:00'));

// Assert the page state.
await expect(page.getByTestId('current-time')).toHaveText('2/2/2024, 10:00:00 AM');

// Close the laptop lid again and open it at 10:30am.
await page.clock.fastForward('30:00');
await expect(page.getByTestId('current-time')).toHaveText('2/2/2024, 10:30:00 AM');

测试非活动性监控

非活动性监控是 Web 应用程序中的一个常见功能,它会在一段非活动时间后注销用户。测试此功能可能很棘手,因为你需要等待很长时间才能看到效果。借助时钟功能,你可以加快时间并快速测试此功能。

<div id="remaining-time" data-testid="remaining-time"></div>
<script>
const endTime = Date.now() + 5 * 60_000;
const renderTime = () => {
const diffInSeconds = Math.round((endTime - Date.now()) / 1000);
if (diffInSeconds <= 0) {
document.getElementById('remaining-time').textContent =
'You have been logged out due to inactivity.';
} else {
document.getElementById('remaining-time').textContent =
`You will be logged out in ${diffInSeconds} seconds.`;
}
setTimeout(renderTime, 1000);
};
renderTime();
</script>
<button type="button">Interaction</button>
// Initial time does not matter for the test, so we can pick current time.
await page.clock.install();
await page.goto('http://localhost:3333');
// Interact with the page
await page.getByRole('button').click();

// Fast forward time 5 minutes as if the user did not do anything.
// Fast forward is like closing the laptop lid and opening it after 5 minutes.
// All the timers due will fire once immediately, as in the real browser.
await page.clock.fastForward('05:00');

// Check that the user was logged out automatically.
await expect(page.getByText('You have been logged out due to inactivity.')).toBeVisible();

手动推进时间,并一致地触发所有计时器

在极少数情况下,你可能希望手动推进时间,在此过程中触发所有计时器和动画帧,以便精细地控制时间的流逝。

<div id="current-time" data-testid="current-time"></div>
<script>
const renderTime = () => {
document.getElementById('current-time').textContent =
new Date().toLocaleString();
};
setInterval(renderTime, 1000);
</script>
// Initialize clock with a specific time, let the page load naturally.
await page.clock.install({ time: new Date('2024-02-02T08:00:00') });
await page.goto('http://localhost:3333');

// Pause the time flow, stop the timers, you now have manual control
// over the page time.
await page.clock.pauseAt(new Date('2024-02-02T10:00:00'));
await expect(page.getByTestId('current-time')).toHaveText('2/2/2024, 10:00:00 AM');

// Tick through time manually, firing all timers in the process.
// In this case, time will be updated in the screen 2 times.
await page.clock.runFor(2000);
await expect(page.getByTestId('current-time')).toHaveText('2/2/2024, 10:00:02 AM');