企业官网建设流程全解析

Playwright Clock API 实战：在 Web 测试中精确模拟时间、定时器与页面老化

【免费下载链接】playwrightPlaywright is a framework for Web Testing and Automation. It allows testing Chromium, Firefox and WebKit with a single API.项目地址: https://gitcode.com/GitHub_Trending/pl/playwright

Playwright 的page.clock允许测试脚本对页面时间拥有完全的控制权：可以把Date.now()固定在某一刻，也可以暂停、快进、逐毫秒推进时间，从而在毫秒级成本内验证“倒计时到期”“空闲超时登出”“定时轮询”等依赖时间的行为。本文以官方文档 clock.md 为主线，完整覆盖setFixedTime、install/pauseAt/fastForward/runFor/resume、setSystemTime三类 API 的用法与多语言示例，并结合仓库中注入脚本、客户端与服务器端的时钟实现源码，解释这些方法在浏览器内部究竟做了什么。

一、Clock API 总览：能控制哪些时间函数

文档指出：准确模拟时间相关行为对验证应用正确性至关重要。Clock 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

调用顺序约束（文档中的 warning）：一旦在测试中调用了install，它必须先于其他所有时钟相关调用发生。乱序调用（例如先setInterval、再install、最后clearInterval）会导致未定义行为，因为install会覆盖这些时钟函数的原生定义。

从类型定义看（types.d.ts），时钟是安装在整个BrowserContext上的，也就是说该上下文内所有页面、所有 iframe 共享同一个时钟；fastForward的官方释义是“相当于用户合上笔记本电脑盖子一段时间后再打开”。

1.1 源码实现架构：三层时钟

从源码结构看，Playwright 的时钟由三层协作完成：

客户端层（packages/playwright-core/src/client/clock.ts）：Clock类的install、fastForward、pauseAt、resume、runFor、setFixedTime、setSystemTime都通过this._browserContext._channel转发为协议消息（clockInstall、clockFastForward等，见 channels.d.ts），并使用kNoTimeout表示这些操作不受常规操作超时限制。时间参数由parseTime统一解析：接受number（毫秒时间戳）、string（可被new Date()解析的字符串）或Date对象，非法日期直接抛出Invalid date错误；fastForward/runFor的刻度由parseTicks解析，同时支持毫秒数和字符串两种形态。

服务器层（packages/playwright-core/src/server/clock.ts）：这是理解“为什么时钟对页面导航仍然有效”的关键。_installIfNeeded()会把编译好的时钟注入脚本（generated/clockSource）通过addInitScript注册为初始化脚本，并立即在当前所有 frame 执行，脚本会在globalThis.__pwClock上构建ClockController。此后每一次时钟操作（如fastForward）都会做两件事：

1. 通过addInitScript追加一段controller.log('fastForward', <调用时刻>, <毫秒数>)—— 这样之后新建的页面或 frame（新文档、iframe 重载）执行初始化脚本时会先重放这份操作日志，保证跨导航的时间状态一致；
2. 通过safeNonStallingEvaluateInAllFrames在当前所有 frame 中真正执行controller.fastForward(...)。

服务器端的parseTicks（server/clock.ts）揭示了文档示例中'30:00'、'05:00'这类字符串的解析规则：支持数字毫秒，以及"08"（8 秒）、"01:00"（1 分钟）、"02:34:10"（2 小时 34 分 10 秒）两种人类可读格式；超过 3 段或某段 ≥ 60 会抛出Clock only understands numbers, 'mm:ss' and 'hh:mm:ss'错误。

注入层（packages/injected/src/clock.ts）：ClockController是页面内真正的时间引擎，值得注意的实现细节有：

• 时间模型由带品牌类型（brand type）的WallTime（墙钟毫秒）与Ticks（单调时钟刻度）组成；setFixedTime会置位isFixedTime标志，此后续刻推进只更新ticks而不更新墙钟时间，这正是“固定时间但定时器照常走”的底层机制；
• install()用假实现逐一替换全局对象：setTimeout/clearTimeout/setInterval/clearInterval、requestAnimationFrame/cancelAnimationFrame、requestIdleCallback/cancelIdleCallback、Date（构造 0 参时返回new NativeDate(clock.now())，Date.now委托给假时钟）、performance（now()返回假时钟刻度，并伪造timeOrigin、getEntries等）、Intl.DateTimeFormat（无参format()使用假时钟），此外还会改写Event.prototype.timeStamp的 getter，并用Object.defineProperty替换AbortSignal.timeout使其走假定时器；
• 同一全局对象上重复install会抛出Can't install fake timers twice on the same global object.，这与文档的调用顺序警告相呼应；
• fastForward与runFor的本质区别在_innerFastForwardTo与_runTo：快进时，所有到期时间早于目标时刻的定时器其callAt被直接搬到目标时刻，只在终点触发一次（“每个到期定时器最多触发一次”）；而runFor走_runTo，按callAt排序逐个触发沿途的每一个定时器（compareTimers先比触发时刻，再比 Immediate 优先、创建顺序、ID），期间Date也会随刻度的推进而更新；
• 定时器回调抛出的错误不会丢失：_runTo记录第一个异常并在推进结束后重新抛出，仓库测试 page-clock.spec.ts 中 “triggers event when some throw” 用例验证了runFor会rejects.toThrow()。

仓库中的 tests/library/page-clock.spec.ts 与 tests/library/page-clock.frozen.spec.ts 覆盖了runFor、fastForward等行为的详细回归，例如“同时到期定时器全部触发”“跨文档导航后状态可重放”等，可作为验证自身用法的参照。

二、场景一：用固定时间测试（setFixedTime）

很多时候你只需要伪造Date.now，而让定时器继续自然流动。这样时间照常流逝，但Date.now始终返回固定值。

被测页面（HTML 示例，来自原文档）：

<div id="current-time">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');

Python（async）：

await page.clock.set_fixed_time(datetime.datetime(2024, 2, 2, 10, 0, 0)) await page.goto("http://localhost:3333") await expect(page.get_by_test_id("current-time")).to_have_text("2/2/2024, 10:00:00 AM") await page.clock.set_fixed_time(datetime.datetime(2024, 2, 2, 10, 30, 0)) # We know that the page has a timer that updates the time every second. await expect(page.get_by_test_id("current-time")).to_have_text("2/2/2024, 10:30:00 AM")

Python（sync）：

page.clock.set_fixed_time(datetime.datetime(2024, 2, 2, 10, 0, 0)) page.goto("http://localhost:3333") expect(page.get_by_test_id("current-time")).to_have_text("2/2/2024, 10:00:00 AM") page.clock.set_fixed_time(datetime.datetime(2024, 2, 2, 10, 30, 0)) # We know that the page has a timer that updates the time every second. expect(page.get_by_test_id("current-time")).to_have_text("2/2/2024, 10:30:00 AM")

Java：

SimpleDateFormat format = new SimpleDateFormat("yyyy-MM-dd'T'HH:mm:ss"); page.clock().setFixedTime(format.parse("2024-02-02T10:00:00")); page.navigate("http://localhost:3333"); Locator locator = page.getByTestId("current-time"); assertThat(locator).hasText("2/2/2024, 10:00:00 AM"); page.clock().setFixedTime(format.parse("2024-02-02T10:30:00")); // We know that the page has a timer that updates the time every second. assertThat(locator).hasText("2/2/2024, 10:30:00 AM");

C#：

// Set the fixed time for the clock. await Page.Clock.SetFixedTimeAsync(new DateTime(2024, 2, 2, 10, 0, 0)); await Page.GotoAsync("http://localhost:3333"); await Expect(Page.GetByTestId("current-time")).ToHaveTextAsync("2/2/2024, 10:00:00 AM"); // Set the fixed time for the clock. await Page.Clock.SetFixedTimeAsync(new DateTime(2024, 2, 2, 10, 30, 0)); // We know that the page has a timer that updates the time every second. await Expect(Page.GetByTestId("current-time")).ToHaveTextAsync("2/2/2024, 10:30:00 AM");

示例中先固定到 10:00，再固定到 10:30：由于页面每秒用setInterval重渲染一次new Date()，当假时钟被拨到 10:30 后，下一次秒级定时回调就会把新时间画到页面上——断言由 Playwright 自动重试，因此无需显式sleep。对应到实现层，setFixedTime走 client/clock.ts 的clockSetFixedTime通道，最终调用注入层ClockController.setFixedTime，置位isFixedTime后所有Date.now()/new Date()都返回固定值，而ticks仍随真实时间同步推进，定时器行为不受影响。

三、场景二：时间与定时器保持一致（install + pauseAt + fastForward）

有些场景里，定时器逻辑依赖Date.now()的差值来计算剩余时间，当Date.now被固定不变时这类代码会“懵掉”。这时应安装完整时钟，让时间先自然流动，再在需要时快进。

被测页面与场景一相同（每秒渲染一次时间的setInterval页面）。

JavaScript：

// 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');

Python（async）：

# 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=datetime.datetime(2024, 2, 2, 8, 0, 0)) 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.pause_at(datetime.datetime(2024, 2, 2, 10, 0, 0)) # Assert the page state. await expect(page.get_by_test_id("current-time")).to_have_text("2/2/2024, 10:00:00 AM") # Close the laptop lid again and open it at 10:30am. await page.clock.fast_forward("30:00") await expect(page.get_by_test_id("current-time")).to_have_text("2/2/2024, 10:30:00 AM")

Python（sync）：

# Initialize clock with some time before the test time and let the page load # naturally. `Date.now` will progress as the timers fire. page.clock.install(time=datetime.datetime(2024, 2, 2, 8, 0, 0)) 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. page.clock.pause_at(datetime.datetime(2024, 2, 2, 10, 0, 0)) # Assert the page state. expect(page.get_by_test_id("current-time")).to_have_text("2/2/2024, 10:00:00 AM") # Close the laptop lid again and open it at 10:30am. page.clock.fast_forward("30:00") expect(page.get_by_test_id("current-time")).to_have_text("2/2/2024, 10:30:00 AM")

Java：

// Initialize clock with some time before the test time and let the page load // naturally. `Date.now` will progress as the timers fire. SimpleDateFormat format = new SimpleDateFormat("yyyy-MM-dd'T'HH:mm:ss"); page.clock().install(new Clock.InstallOptions().setTime(format.parse("2024-02-02T08:00:00"))); page.navigate("http://localhost:3333"); Locator locator = page.getByTestId("current-time"); // Pretend that the user closed the laptop lid and opened it again at 10am. // Pause the time once reached that point. page.clock().pauseAt(format.parse("2024-02-02T10:00:00")); // Assert the page state. assertThat(locator).hasText("2/2/2024, 10:00:00 AM"); // Close the laptop lid again and open it at 10:30am. page.clock().fastForward("30:00"); assertThat(locator).hasText("2/2/2024, 10:30:00 AM");

C#：

// 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.InstallAsync(new() { TimeDate = new DateTime(2024, 2, 2, 8, 0, 0) }); await Page.GotoAsync("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.PauseAtAsync(new DateTime(2024, 2, 2, 10, 0, 0)); // Assert the page state. await Expect(Page.GetByTestId("current-time")).ToHaveTextAsync("2/2/2024, 10:00:00 AM"); // Close the laptop lid again and open it at 10:30am. await Page.Clock.FastForwardAsync("30:00"); await Expect(Page.GetByTestId("current-time")).ToHaveTextAsync("2/2/2024, 10:30:00 AM");

这一步“把install的时间设到略早于测试目标时间、让页面自然加载完再pauseAt”正是类型定义中pauseAt文档给出的最佳实践（types.d.ts），目的是保证页面加载期间的定时器正常运转，避免页面卡死在某个等待状态。从注入层源码看，pauseAt(time)先执行_innerPause()停掉与真实时间的同步，再调用_innerFastForwardTo一次性快进到目标时刻——途中所有早于该时刻到期的定时器只会各触发一次；fastForward('30:00')中的'30:00'字符串由 server/clock.ts 的 parseTicks 解析为 30 分钟对应的毫秒数。

四、场景三：测试空闲超时登出（install + fastForward）

“无操作一段时间自动登出”是 Web 应用常见功能，真等超时既慢又不可靠。利用时钟可以把 5 分钟压缩成一次调用。

被测页面：

<div id="remaining-time">// 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();

Python（async）：

# 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.get_by_role("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.fast_forward("05:00") # Check that the user was logged out automatically. await expect(page.getByText("You have been logged out due to inactivity.")).toBeVisible()

Python（sync）：

# Initial time does not matter for the test, so we can pick current time. page.clock.install() page.goto("http://localhost:3333") # Interact with the page page.get_by_role("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. page.clock.fast_forward("05:00") # Check that the user was logged out automatically. expect(page.getByText("You have been logged out due to inactivity.")).to_be_visible()

Java：

// Initial time does not matter for the test, so we can pick current time. page.clock().install(); page.navigate("http://localhost:3333"); Locator locator = page.getByRole("button"); // Interact with the page locator.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. page.clock().fastForward("05:00"); // Check that the user was logged out automatically. assertThat(page.getByText("You have been logged out due to inactivity.")).isVisible();

C#：

// Initial time does not matter for the test, so we can pick current time. await Page.Clock.InstallAsync(); await page.GotoAsync("http://localhost:3333"); // Interact with the page await page.GetByRole("button").ClickAsync(); // 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.FastForwardAsync("05:00"); // Check that the user was logged out automatically. await Expect(Page.GetByText("You have been logged out due to inactivity.")).ToBeVisibleAsync();

这里install()不带参数，默认以“当前系统时间”初始化（见 types.d.ts 中install(options?: { time?: number|string|Date })的说明：Time to initialize with, current system time by default；server/clock.ts 中time === undefined时取Date.now()）。fastForward('05:00')之后，所有到期定时器会像真实浏览器一样各触发一次，递归的setTimeout(renderTime, 1000)链被“压缩”执行，Date.now也随之推进 5 分钟，diffInSeconds变为负数，页面显示已登出。

五、场景四：手动逐刻推进时间（pauseAt + runFor）

少数场景需要细粒度控制时间的流逝过程——手动拨动时钟，让途中每一个定时器和动画帧按顺序触发。runFor与fastForward的关键区别就在于此：runFor沿途触发每一个到期定时器，fastForward只把每个到期定时器在终点触发一次。

被测页面仍为每秒渲染时间的setInterval页面（同场景一、二的 HTML）。

JavaScript：

// 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');

Python（async）：

# Initialize clock with a specific time, let the page load naturally. await page.clock.install(time= datetime.datetime(2024, 2, 2, 8, 0, 0, tzinfo=datetime.timezone.pst), ) await page.goto("http://localhost:3333") locator = page.get_by_test_id("current-time") # Pause the time flow, stop the timers, you now have manual control # over the page time. await page.clock.pause_at(datetime.datetime(2024, 2, 2, 10, 0, 0)) await expect(locator).to_have_text("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.run_for(2000) await expect(locator).to_have_text("2/2/2024, 10:00:02 AM")

Python（sync）：

# Initialize clock with a specific time, let the page load naturally. page.clock.install( time=datetime.datetime(2024, 2, 2, 8, 0, 0, tzinfo=datetime.timezone.pst), ) page.goto("http://localhost:3333") locator = page.get_by_test_id("current-time") # Pause the time flow, stop the timers, you now have manual control # over the page time. page.clock.pause_at(datetime.datetime(2024, 2, 2, 10, 0, 0)) expect(locator).to_have_text("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. page.clock.run_for(2000) expect(locator).to_have_text("2/2/2024, 10:00:02 AM")

Java：

SimpleDateFormat format = new SimpleDateFormat("yyyy-MM-dd'T'HH:mm:ss"); // Initialize clock with a specific time, let the page load naturally. page.clock().install(new Clock.InstallOptions() .setTime(format.parse("2024-02-02T08:00:00"))); page.navigate("http://localhost:3333"); Locator locator = page.getByTestId("current-time"); // Pause the time flow, stop the timers, you now have manual control // over the page time. page.clock().pauseAt(format.parse("2024-02-02T10:00:00")); assertThat(locator).hasText("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. page.clock().runFor(2000); assertThat(locator).hasText("2/2/2024, 10:00:02 AM");

C#：

// Initialize clock with a specific time, let the page load naturally. await Page.Clock.InstallAsync(new() { TimeDate = new DateTime(2024, 2, 2, 8, 0, 0, DateTimeKind.Pst) }); await page.GotoAsync("http://localhost:3333"); var locator = page.GetByTestId("current-time"); // Pause the time flow, stop the timers, you now have manual control // over the page time. await Page.Clock.PauseAtAsync(new DateTime(2024, 2, 2, 10, 0, 0)); await Expect(locator).ToHaveTextAsync("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.RunForAsync(2000); await Expect(locator).ToHaveTextAsync("2/2/2024, 10:00:02 AM");

pauseAt之后时间冻结、定时器全部停摆，页面时间完全由测试掌控；runFor(2000)手动拨过 2000 毫秒，1 秒间隔的setInterval在其中触发 2 次，屏幕上的时间因此更新了 2 次。对应到注入层，这正是ClockController._runTo的循环：每轮取出下一个最早到期的定时器、推进now到其callAt、执行回调（Interval类型触发后重新排期，Timeout类型触发后删除），直到没有更早的定时器为止——仓库测试 page-clock.spec.ts 中 “creates updated Date while ticking” 用例还验证了runFor过程中new Date().getTime()会随每一次setInterval回调同步更新（10ms 间隔 100ms 内依次得到 10…100）。若只想让时间自然恢复流动，可调用resume()（server/clock.ts 中服务器端会同时写入可重放的log('resume', ...)初始化脚本，保证后续新文档中时间继续自然流动）。

六、选型建议与使用边界

结合文档推荐与源码实现，可以把选择策略总结为：

需要牢记的边界条件：

1. 作用域是整个BrowserContext：同一上下文的所有页面和 iframe 共享一个时钟，不要误以为它是 Page 级的独立开关；
2. 调用顺序：install（或任何时钟方法触发的自动安装，见 server/clock.ts 的_installIfNeeded）之后再进行其他时间相关调用；同一全局对象上重复安装会直接抛错；
3. 时间字符串格式：fastForward/runFor接受毫秒数或"mm:ss"/"hh:mm:ss"（如'05:00'、'02:34:10'），格式不合法会抛出明确错误；
4. fastForward不能快进到过去：注入层_innerFastForwardTo对to < 当前刻度抛出Cannot fast-forward to the past；
5. 错误不会被吞：定时器回调抛出的异常会由runFor/fastForward的 Promise 重新抛出，测试会失败并暴露页面内真实的 JS 错误。

以上示例中的页面均假设由本地测试服务器（如 Playwright Test 的webServer配置）在http://localhost:3333提供；时钟 API 对 Chromium、Firefox、WebKit 三个受支持内核均通过同一套注入脚本生效（注入脚本中的browserName参数仅用于让AbortSignal.timeout的超时错误文案贴近各浏览器原生日志）。

【免费下载链接】playwrightPlaywright is a framework for Web Testing and Automation. It allows testing Chromium, Firefox and WebKit with a single API.项目地址: https://gitcode.com/GitHub_Trending/pl/playwright