[Bug]: Flaky behaviour on stopTime

[vvargas90]

Version

1.46.1

Steps to reproduce

1. Call this func to stop time:

export async function stopTime(page) {
    await page.clock.install();
    await page.clock.pauseAt(Date.now());
}

Expected behavior

Time is stopped at current time

Actual behavior

Sometimes I have this error:

Error: clock.pauseAt: Error: Cannot fast-forward to the past

    at ClockController._innerFastForwardTo (<anonymous>:164:13)
    at ClockController.pauseAt (<anonymous>:116:16)
    at eval (eval at evaluate (:234:30), <anonymous>:1:33)
    at eval (<anonymous>)
    at UtilityScript.evaluate (<anonymous>:234:30)
    at UtilityScript.<anonymous> (<anonymous>:1:44)
    at ClockController._innerFastForwardTo (/app/<anonymous>:164:13)
    at ClockController.pauseAt (/app/<anonymous>:116:16)
    at eval (/app/eval at evaluate (:234:30), <anonymous>:1:33)
    at UtilityScript.evaluate (/app/<anonymous>:234:30)
    at UtilityScript.<anonymous> (/app/<anonymous>:1:44)
    at stopTime (/app/uitests/utils/playwrightClock.ts:11:22)
    at /app/uitests/tests/mytest.spec.ts:213:13

Additional context

No response

Environment

System:
    OS: macOS 13.5
    CPU: (8) arm64 Apple M2
    Memory: 98.86 MB / 16.00 GB
  Binaries:
    Node: 20.18.0 - ~/.nvm/versions/node/v20.18.0/bin/node
    npm: 10.8.2 - ~/.nvm/versions/node/v20.18.0/bin/npm
  Languages:
    Bash: 3.2.57 - /bin/bash
  npmPackages:
    @playwright/test: 1.46.1 => 1.46.1

[yury-s]

This behavior is intentional. When you call initialize() without providing an explicit value, the clock continues ticking as usual. Later, if you attempt to set it to Date.now(), it throws an error due to the asynchronous nature of pauseAt. By the time Playwright pauses the clock on the page, the current time may already have advanced beyond the intended point.

As our example explains, you should "Initialize clock with some time before the test time" before pausing:

    const now = Date.now();
    await page.clock.install({ time: now - 3600*1000 });
    // initialize the page
    // ...
    await page.clock.pauseAt(now);

Usually, you'd install clock first then perform navigation and later pause the clock. This way the page can load normally, firing all the timers etc before you pause it. I will update our docs to clarify this and the rationale behind it.