Skip to content

Commit

Permalink
api(clock): rework api based on the review (#31137)
Browse files Browse the repository at this point in the history
  • Loading branch information
@pavelfeldman
pavelfeldman authored Jun 4, 2024
1 parent 727b218 commit c516ba0
Show file tree
Hide file tree
Showing 13 changed files with 611 additions and 606 deletions.
202 changes: 76 additions & 126 deletions docs/src/api/class-clock.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -6,211 +6,161 @@ 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.install
## async method: Clock.installFakeTimers
* since: v1.45

Creates a clock and installs it globally.
Install fake implementations for the following time-related functions:

**Usage**

```js
await page.clock.install();
await page.clock.install({ now });
await page.clock.install({ now, toFake: ['Date'] });
```

```python async
await page.clock.install()
await page.clock.install(now=now)
await page.clock.install(now=now, toFake=['Date'])
```

```python sync
page.clock.install()
page.clock.install(now=now)
page.clock.install(now=now, toFake=['Date'])
```

```java
page.clock().install();
page.clock().install(
new Clock.InstallOptions()
.setNow(now));
page.clock().install(
new Clock.InstallOptions()
.setNow(now)
.setToFake(new String[]{"Date"}));
```

```csharp
await page.Clock.InstallAsync();
await page.Clock.InstallAsync(
new ClockInstallOptions { Now = now });
await page.Clock.InstallAsync(
new ClockInstallOptions
{
Now = now,
ToFake = new[] { "Date" }
});
```
* `setTimeout`
* `clearTimeout`
* `setInterval`
* `clearInterval`
* `requestAnimationFrame`
* `cancelAnimationFrame`
* `requestIdleCallback`
* `cancelIdleCallback`
* `performance`

### option: Clock.install.now
* since: v1.45
- `now` <[int]|[Date]>

Install fake timers with the specified unix epoch (default: 0).
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.

### option: Clock.install.toFake
### param: Clock.installFakeTimers.time
* since: v1.45
- `toFake` <[Array]<[FakeMethod]<"setTimeout"|"clearTimeout"|"setInterval"|"clearInterval"|"Date"|"requestAnimationFrame"|"cancelAnimationFrame"|"requestIdleCallback"|"cancelIdleCallback"|"performance">>>
- `time` <[int]|[Date]>

An array with names of global methods and APIs to fake. For instance, `await page.clock.install({ toFake: ['setTimeout'] })` will fake only `setTimeout()`.
By default, all the methods are faked.
Install fake timers with the specified base time.

### option: Clock.install.loopLimit
### option: Clock.installFakeTimers.loopLimit
* since: v1.45
- `loopLimit` <[int]>

The maximum number of timers that will be run when calling [`method: Clock.runAll`]. Defaults to `1000`.
The maximum number of timers that will be run in [`method: Clock.runAllTimers`]. Defaults to `1000`.

### option: Clock.install.shouldAdvanceTime
## async method: Clock.runAllTimers
* since: v1.45
- `shouldAdvanceTime` <[boolean]>
- 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.

Tells `@sinonjs/fake-timers` to increment mocked time automatically based on the real system time shift (e.g., the mocked time will be incremented by
20ms for every 20ms change in the real system time). Defaults to `false`.
**Details**

### option: Clock.install.advanceTimeDelta
* since: v1.45
- `advanceTimeDelta` <[int]>
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.

Relevant only when using with [`option: shouldAdvanceTime`]. Increment mocked time by advanceTimeDelta ms every advanceTimeDelta ms change
in the real system time (default: 20).

## async method: Clock.jump
## async method: Clock.runFor
* since: v1.45
- returns: <[int]>

Advance the clock by jumping forward in time, firing callbacks 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.
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.

**Usage**

```js
await page.clock.jump(1000);
await page.clock.jump('30:00');
await page.clock.runFor(1000);
await page.clock.runFor('30:00');
```

```python async
await page.clock.jump(1000);
await page.clock.jump('30:00')
await page.clock.run_for(1000);
await page.clock.run_for('30:00')
```

```python sync
page.clock.jump(1000);
page.clock.jump('30:00')
page.clock.run_for(1000);
page.clock.run_for('30:00')
```

```java
page.clock().jump(1000);
page.clock().jump("30:00");
page.clock().runFor(1000);
page.clock().runFor("30:00");
```

```csharp
await page.Clock.JumpAsync(1000);
await page.Clock.JumpAsync("30:00");
await page.Clock.RunForAsync(1000);
await page.Clock.RunForAsync("30:00");
```

### param: Clock.jump.time
### param: Clock.runFor.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.

## async method: Clock.next

## async method: Clock.runToLastTimer
* since: v1.45
- returns: <[int]>

Advances the clock to the the moment of the first scheduled timer, firing it.
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.

**Usage**

```js
await page.clock.next();
```

```python async
await page.clock.next()
```

```python sync
page.clock.next()
```

```java
page.clock().next();
```

```csharp
await page.Clock.NextAsync();
```

## async method: Clock.runAll
## async method: Clock.runToNextTimer
* 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. Returns fake milliseconds since the unix epoch.
Advances the clock to the the moment of the first scheduled timer, firing it.
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.
## async method: Clock.setTime
* since: v1.45

Set the clock to the specified time.

## async method: Clock.runToLast
* since: v1.45
- returns: <[int]>
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.

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.
Returns fake milliseconds since the unix epoch.
### param: Clock.setTime.time
* since: v1.45
- `time` <[int]|[Date]>


## async method: Clock.tick
## async method: Clock.skipTime
* since: v1.45
- returns: <[int]>

Advance the clock, firing callbacks if necessary. Returns fake milliseconds since the unix epoch. Returns fake milliseconds since the unix epoch.
Advance the clock by jumping forward in time, equivalent to running [`method: Clock.setTime`] with the new target time.

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.

**Usage**

```js
await page.clock.tick(1000);
await page.clock.tick('30:00');
await page.clock.skipTime(1000);
await page.clock.skipTime('30:00');
```

```python async
await page.clock.tick(1000);
await page.clock.tick('30:00')
await page.clock.skipTime(1000);
await page.clock.skipTime('30:00')
```

```python sync
page.clock.tick(1000);
page.clock.tick('30:00')
page.clock.skipTime(1000);
page.clock.skipTime('30:00')
```

```java
page.clock().tick(1000);
page.clock().tick("30:00");
page.clock().skipTime(1000);
page.clock().skipTime("30:00");
```

```csharp
await page.Clock.TickAsync(1000);
await page.Clock.TickAsync("30:00");
await page.Clock.SkipTimeAsync(1000);
await page.Clock.SkipTimeAsync("30:00");
```

### param: Clock.tick.time
### param: Clock.skipTime.time
* since: v1.45
- `time` <[int]|[string]>

Expand Down
Loading

0 comments on commit c516ba0

Please sign in to comment.