Skip to main content

Clock

Introduction​

Accurately simulating time-dependent behavior is essential for verifying the correctness of applications. Utilizing Clock functionality allows developers to manipulate and control time within tests, enabling the precise validation of features such as rendering time, timeouts, scheduled tasks without the delays and variability of real-time execution.

The Clock API provides the following methods to control time:

  • setFixedTime: Sets the fixed time for Date.now() and new Date().
  • install: initializes the clock and allows you to:
    • pauseAt: Pauses the time at a specific time.
    • fastForward: Fast forwards the time.
    • runFor: Runs the time for a specific duration.
    • resume: Resumes the time.
  • setSystemTime: Sets the current system time.

The recommended approach is to use setFixedTime to set the time to a specific value. If that doesn't work for your use case, you can use install which allows you to pause time later on, fast forward it, tick it, etc. setSystemTime is only recommended for advanced use cases.

note

Page.clock() overrides native global classes and functions related to time allowing them to be manually controlled:

  • Date
  • Temporal.Now
  • setTimeout
  • clearTimeout
  • setInterval
  • clearInterval
  • requestAnimationFrame
  • cancelAnimationFrame
  • requestIdleCallback
  • cancelIdleCallback
  • performance
  • Event.timeStamp
warning

If you call install at any point in your test, the call MUST occur before any other clock related calls (see note above for list). Calling these methods out of order will result in undefined behavior. For example, you cannot call setInterval, followed by install, then clearInterval, as install overrides the native definition of the clock functions.

Test with predefined time​

Often you only need to fake Date.now while keeping the timers going. That way the time flows naturally, but Date.now always returns a fixed value.

<div id="current-time" data-testid="current-time"></div>
<script>
const renderTime = () => {
document.getElementById('current-time').textContent =
new Date().toLocaleString();
};
setInterval(renderTime, 1000);
</script>
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");

Consistent time and timers​

Sometimes your timers depend on Date.now and are confused when the Date.now value does not change over time. In this case, you can install the clock and fast forward to the time of interest when testing.

<div id="current-time" data-testid="current-time"></div>
<script>
const renderTime = () => {