Playwright.Clock (Playwright v1.65.0-rc.3)

Copy Markdown View Source

Accurately simulating time-dependent behavior is essential for verifying the correctness of applications. Learn more about clock emulation.

Note that clock is installed for the entire BrowserContext, so the time in all the pages and iframes is controlled by the same clock.

Since Playwright 1.45.

The examples alias the modules they use (alias Playwright.{Locator, Page}).

Summary

Types

Options of install/2, see its docs.

t()

A Clock handle. Compare handles with ==, their fields are internal.

Functions

Advance the clock by jumping forward in time. Only fires due timers at most once. This is equivalent to user closing the laptop lid for a while and reopening it later, after given time.

Like fast_forward/2, but returns the value and raises on error.

Install fake implementations for the following time-related functions

Like install/2, but returns the value and raises on error.

Advance the clock by jumping forward in time and pause the time. Once this method is called, no timers are fired unless Playwright.Clock.run_for/2, Playwright.Clock.fast_forward/2, Playwright.Clock.pause_at/2 or Playwright.Clock.resume/1 is called.

Like pause_at/2, but returns the value and raises on error.

Resumes timers. Once this method is called, time resumes flowing, timers are fired as usual.

Like resume/1, but returns the value and raises on error.

Advance the clock, firing all the time-related callbacks.

Like run_for/2, but returns the value and raises on error.

Makes Date.now and new Date() return fixed fake time at all times, keeps all the timers running.

Like set_fixed_time/2, but returns the value and raises on error.

Sets system time, but does not trigger any timers. Use this to test how the web page reacts to a time shift, for example switching from summer to winter time, or changing time zones.

Like set_system_time/2, but returns the value and raises on error.

Types

install_options()

@type install_options() ::
  [{:time, integer() | String.t() | DateTime.t()}]
  | %{optional(:time) => integer() | String.t() | DateTime.t()}

Options of install/2, see its docs.

t()

@type t() :: %Playwright.Clock{_browserContext: term()}

A Clock handle. Compare handles with ==, their fields are internal.

Functions

fast_forward(clock, ticks)

@spec fast_forward(t(), integer() | String.t()) :: :ok | {:error, Playwright.error()}

Advance the clock by jumping forward in time. Only fires due timers at most once. This is equivalent to user closing the laptop lid for a while and reopening it later, after given time.

Usage

Page.clock(page) |> Clock.fast_forward!(1000)
Page.clock(page) |> Clock.fast_forward!("30:00")

Since Playwright 1.45.

Arguments

  • ticks - Time may be a finite number of milliseconds to advance the clock by or a human-readable string. Valid string formats are "08" for eight seconds, "01:00" for one minute and "02:34:10" for two hours, 34 minutes and ten seconds.

fast_forward!(clock, ticks)

@spec fast_forward!(t(), integer() | String.t()) :: :ok

Like fast_forward/2, but returns the value and raises on error.

install(clock, options \\ [])

@spec install(t(), install_options()) :: :ok | {:error, Playwright.error()}

Install fake implementations for the following time-related functions:

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

Fake timers are used to manually control the flow of time in tests. They allow you to advance time, fire timers, and control the behavior of time-dependent functions. See Playwright.Clock.run_for/2 and Playwright.Clock.fast_forward/2 for more information.

Since Playwright 1.45.

Options

install!(clock, options \\ [])

@spec install!(t(), install_options()) :: :ok

Like install/2, but returns the value and raises on error.

pause_at(clock, time)

@spec pause_at(t(), integer() | String.t() | DateTime.t()) ::
  :ok | {:error, Playwright.error()}

Advance the clock by jumping forward in time and pause the time. Once this method is called, no timers are fired unless Playwright.Clock.run_for/2, Playwright.Clock.fast_forward/2, Playwright.Clock.pause_at/2 or Playwright.Clock.resume/1 is called.

Only fires due timers at most once. This is equivalent to user closing the laptop lid for a while and reopening it at the specified time and pausing.

Usage

Page.clock(page) |> Clock.pause_at!(~U[2020-02-02 00:00:00Z])
Page.clock(page) |> Clock.pause_at!("2020-02-02")

For best results, install the clock before navigating the page and set it to a time slightly before the intended test time. This ensures that all timers run normally during page loading, preventing the page from getting stuck. Once the page has fully loaded, you can safely use Playwright.Clock.pause_at/2 to pause the clock.

# 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(page) |> Clock.install!(time: ~U[2024-12-10 08:00:00Z])
Page.goto!(page, "http://localhost:3333")
Page.clock(page) |> Clock.pause_at!(~U[2024-12-10 10:00:00Z])

Since Playwright 1.45.

Arguments

  • time - Time to pause at.

pause_at!(clock, time)

@spec pause_at!(t(), integer() | String.t() | DateTime.t()) :: :ok

Like pause_at/2, but returns the value and raises on error.

resume(clock)

@spec resume(t()) :: :ok | {:error, Playwright.error()}

Resumes timers. Once this method is called, time resumes flowing, timers are fired as usual.

Since Playwright 1.45.

resume!(clock)

@spec resume!(t()) :: :ok

Like resume/1, but returns the value and raises on error.

run_for(clock, ticks)

@spec run_for(t(), integer() | String.t()) :: :ok | {:error, Playwright.error()}

Advance the clock, firing all the time-related callbacks.

Usage

Page.clock(page) |> Clock.run_for!(1000)
Page.clock(page) |> Clock.run_for!("30:00")

Since Playwright 1.45.

Arguments

  • ticks - Time may be a finite number of milliseconds to advance the clock by or a human-readable string. Valid string formats are "08" for eight seconds, "01:00" for one minute and "02:34:10" for two hours, 34 minutes and ten seconds.

run_for!(clock, ticks)

@spec run_for!(t(), integer() | String.t()) :: :ok

Like run_for/2, but returns the value and raises on error.

set_fixed_time(clock, time)

@spec set_fixed_time(t(), integer() | String.t() | DateTime.t()) ::
  :ok | {:error, Playwright.error()}

Makes Date.now and new Date() return fixed fake time at all times, keeps all the timers running.

Use this method for simple scenarios where you only need to test with a predefined time. For more advanced scenarios, use Playwright.Clock.install/2 instead. Read docs on clock emulation to learn more.

Usage

Page.clock(page) |> Clock.set_fixed_time!(DateTime.utc_now())
Page.clock(page) |> Clock.set_fixed_time!(~U[2020-02-02 00:00:00Z])
Page.clock(page) |> Clock.set_fixed_time!("2020-02-02")

Since Playwright 1.45.

Arguments

  • time - Time to be set in milliseconds.

set_fixed_time!(clock, time)

@spec set_fixed_time!(t(), integer() | String.t() | DateTime.t()) :: :ok

Like set_fixed_time/2, but returns the value and raises on error.

set_system_time(clock, time)

@spec set_system_time(t(), integer() | String.t() | DateTime.t()) ::
  :ok | {:error, Playwright.error()}

Sets system time, but does not trigger any timers. Use this to test how the web page reacts to a time shift, for example switching from summer to winter time, or changing time zones.

Usage

Page.clock(page) |> Clock.set_system_time!(DateTime.utc_now())
Page.clock(page) |> Clock.set_system_time!(~U[2020-02-02 00:00:00Z])
Page.clock(page) |> Clock.set_system_time!("2020-02-02")

Since Playwright 1.45.

Arguments

  • time - Time to be set in milliseconds.

set_system_time!(clock, time)

@spec set_system_time!(t(), integer() | String.t() | DateTime.t()) :: :ok

Like set_system_time/2, but returns the value and raises on error.