chore: clock api review

docs/src/api/class-clock.md

@@ -6,11 +6,88 @@ Accurately simulating time-dependent behavior is essential for verifying the cor
 Note that clock is installed for the entire [BrowserContext], so the time
 in all the pages and iframes is controlled by the same clock.
 
-## async method: Clock.installFakeTimers
+## async method: Clock.fastForward
+* since: v1.45
+
+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**
+
+```js
+await page.clock.fastForward(1000);
+await page.clock.fastForward('30:00');
+```
+
+```python async
+await page.clock.fast_forward(1000)
+await page.clock.fast_forward('30:00')
+```
+
+```python sync
+page.clock.fast_forward(1000)
+page.clock.fast_forward('30:00')
+```
+
+```java
+page.clock().fastForward(1000);
+page.clock().fastForward("30:00");
+```
+
+```csharp
+await page.Clock.FastForwardAsync(1000);
+await page.Clock.FastForwardAsync("30:00");
+```
+
+### param: Clock.fastForward.ticks
+* since: v1.45
+- `ticks` <[int]|[string]>
+
+Time may be the 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.
+
+## async method: Clock.fastForwardTo
+* since: v1.45
+
+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 at the specified time.
+
+**Usage**
+
+```js
+await page.clock.fastForwardTo(new Date('2020-02-02'));
+await page.clock.fastForwardTo('2020-02-02');
+```
+
+```python async
+await page.clock.fast_forward_to(datetime.datetime(2020, 2, 2));
+await page.clock.fast_forward_to('2020-02-02')
+```
+
+```python sync
+page.clock.fast_forward_to(datetime.datetime(2020, 2, 2)
+page.clock.fast_forward_to('2020-02-02')
+```
+
+```java
+page.clock().fastForwardTo(Instant.parse("2020-02-02"));
+page.clock().fastForwardTo("2020-02-02");
+```
+
+```csharp
+await page.Clock.FastForwardToAsync(DateTime.Parse("2020-02-02"));
+await page.Clock.FastForwardToAsync("2020-02-02");
+```
+
+### param: Clock.fastForwardTo.time
+* since: v1.45
+- `time` <[int]|[string]|[Date]>
+
+## async method: Clock.install
 * since: v1.45
 
 Install fake implementations for the following time-related functions:
 
+* `Date`
 * `setTimeout`
 * `clearTimeout`
 * `setInterval`
@@ -21,41 +98,18 @@ Install fake implementations for the following time-related functions:
 * `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 [`method: Clock.runFor`] and [`method: Clock.skipTime`] for more information.
+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 [`method: Clock.runFor`] and [`method: Clock.fastForward`] for more information.
 
-### param: Clock.installFakeTimers.time
+### option: Clock.install.time
 * since: v1.45
 - `time` <[int]|[Date]>
 
-Install fake timers with the specified base time.
-
-### option: Clock.installFakeTimers.loopLimit
-* since: v1.45
-- `loopLimit` <[int]>
-
-The maximum number of timers that will be run in [`method: Clock.runAllTimers`]. Defaults to `1000`.
-
-## async method: Clock.runAllTimers
-* since: v1.45
-- returns: <[int]>
-
-Runs all pending timers until there are none remaining. If new timers are added while it is executing they will be run as well.
-Fake timers must be installed.
-Returns fake milliseconds since the unix epoch.
-
-**Details**
-
-This makes it easier to run asynchronous tests to completion without worrying about the number of timers they use, or the delays in those timers.
-It runs a maximum of [`option: loopLimit`] times after which it assumes there is an infinite loop of timers and throws an error.
-
+Time to initialize with, current system time by default.
 
 ## async method: Clock.runFor
 * since: v1.45
-- returns: <[int]>
 
-Advance the clock, firing callbacks if necessary. Returns fake milliseconds since the unix epoch.
-Fake timers must be installed.
-Returns fake milliseconds since the unix epoch.
+Advance the clock, firing all the time-related callbacks.
 
 **Usage**
 
@@ -84,84 +138,108 @@ await page.Clock.RunForAsync(1000);
 await page.Clock.RunForAsync("30:00");
 ```
 
-### param: Clock.runFor.time
+### param: Clock.runFor.ticks
 * since: v1.45
-- `time` <[int]|[string]>
+- `ticks` <[int]|[string]>
 
 Time may be the 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.
 
 
-## async method: Clock.runToLastTimer
+## async method: Clock.pause
 * since: v1.45
-- returns: <[int]>
 
-This takes note of the last scheduled timer when it is run, and advances the clock to that time firing callbacks as necessary.
-If new timers are added while it is executing they will be run only if they would occur before this time.
-This is useful when you want to run a test to completion, but the test recursively sets timers that would cause runAll to trigger an infinite loop warning.
-Fake timers must be installed.
-Returns fake milliseconds since the unix epoch.
+Pause timers. Once this method is called, no timers are fired unless [`method: Clock.runFor`], [`method: Clock.fastForward`], [`method: Clock.fastForwardTo`] or [`method: Clock.resume`] is called.
+
+## async method: Clock.resume
+* since: v1.45
 
+Resumes timers. Once this method is called, time resumes flowing, timers are fired as usual.
 
-## async method: Clock.runToNextTimer
+## async method: Clock.setFixedTime
 * since: v1.45
-- returns: <[int]>
 
-Advances the clock to the moment of the first scheduled timer, firing it.
-Fake timers must be installed.
-Returns fake milliseconds since the unix epoch.
+Makes `Date.now` and `new Date()` return fixed fake time, keeps all the timers running.
 
+**Usage**
 
-## async method: Clock.setTime
-* since: v1.45
+```js
+await page.clock.setFixedTime(Date.now());
+await page.clock.setFixedTime(new Date('2020-02-02'));
+await page.clock.setFixedTime('2020-02-02');
+```
 
-Set the clock to the specified time.
+```python async
+await page.clock.set_fixed_time(datetime.datetime.now())
+await page.clock.set_fixed_time(datetime.datetime(2020, 2, 2))
+await page.clock.set_fixed_time('2020-02-02')
+```
 
-When fake timers are installed, only fires timers at most once. This can be used to simulate the JS engine (such as a browser)
-being put to sleep and resumed later, skipping intermediary timers.
+```python sync
+page.clock.set_fixed_time(datetime.datetime.now())
+page.clock.set_fixed_time(datetime.datetime(2020, 2, 2))
+page.clock.set_fixed_time('2020-02-02')
+```
 
-### param: Clock.setTime.time
-* since: v1.45
-- `time` <[int]|[Date]>
+```java
+page.clock().setFixedTime(Instant.now());
+page.clock().setFixedTime(Instant.parse("2020-02-02"));
+page.clock().setFixedTime("2020-02-02");
+```
 
+```csharp
+await page.Clock.SetFixedTimeAsync(DateTime.Now);
+await page.Clock.SetFixedTimeAsync(new DateTime(2020, 2, 2));
+await page.Clock.SetFixedTimeAsync("2020-02-02");
+```
 
-## async method: Clock.skipTime
+### param: Clock.setFixedTime.time
 * since: v1.45
-- returns: <[int]>
+- `time` <[int]|[string]|[Date]>
 
-Advance the clock by jumping forward in time, equivalent to running [`method: Clock.setTime`] with the new target time.
+Time to be set.
 
-When fake timers are installed, [`method: Clock.skipTime`] only fires due timers at most once, while [`method: Clock.runFor`] fires all the timers up to the current time.
-Returns fake milliseconds since the unix epoch.
+## async method: Clock.setSystemTime
+* since: v1.45
+
+Sets current system time, keeps the time flowing and all the timers intact.
 
 **Usage**
 
 ```js
-await page.clock.skipTime(1000);
-await page.clock.skipTime('30:00');
+await page.clock.setTime(Date.now());
+await page.clock.setTime(new Date('2020-02-02'));
+await page.clock.setTime('2020-02-02');
+await page.clock.setTime('2020-02-02', { pause: true });
 ```
 
 ```python async
-await page.clock.skipTime(1000);
-await page.clock.skipTime('30:00')
+await page.clock.set_time(datetime.datetime.now())
+await page.clock.set_time(datetime.datetime(2020, 2, 2))
+await page.clock.set_time('2020-02-02')
+await page.clock.setTime('2020-02-02', pause=True)
 ```
 
 ```python sync
-page.clock.skipTime(1000);
-page.clock.skipTime('30:00')
+page.clock.set_time(datetime.datetime.now())
+page.clock.set_time(datetime.datetime(2020, 2, 2))
+page.clock.set_time('2020-02-02')
+page.clock.setTime('2020-02-02', pause=True)
 ```
 
 ```java
-page.clock().skipTime(1000);
-page.clock().skipTime("30:00");
+page.clock().setTime(Instant.now());
+page.clock().setTime(Instant.parse("2020-02-02"));
+page.clock().setTime("2020-02-02");
+page.clock().setTime("2020-02-02", new Clock.SetTimeOptions().setPause(true));
 ```
 
 ```csharp
-await page.Clock.SkipTimeAsync(1000);
-await page.Clock.SkipTimeAsync("30:00");
+await page.Clock.SetTimeAsync(DateTime.Now);
+await page.Clock.SetTimeAsync(new DateTime(2020, 2, 2));
+await page.Clock.SetTimeAsync("2020-02-02");
+await page.Clock.SetTimeAsync("2020-02-02", new { Pause = true });
 ```
 
-### param: Clock.skipTime.time
+### param: Clock.setSystemTime.time
 * since: v1.45
-- `time` <[int]|[string]>
-
-Time may be the 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.
+- `time` <[int]|[string]|[Date]>