microsoft/playwright
1
1
Fork 0
mirror of https://github.com/microsoft/playwright.git synced 2025-01-05 19:04:43 +03:00
Code Issues Projects Releases Wiki Activity

docs: start adding clock docs (#31111)

Browse Source
This commit is contained in:
Pavel Feldman 2024-06-01 07:30:58 -07:00 committed by GitHub
parent 4655a30bdd
commit fc6c67f5f9
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
3 changed files with 347 additions and 3 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

121
docs/src/api/class-clock.md
View File

@ -10,6 +10,49 @@ in all the pages and iframes is controlled by the same clock.
Creates a clock and installs it globally.
**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" }
});
```
### option: Clock.install.now
* since: v1.45
- `now` <[int]|[Date]>
@ -50,6 +93,27 @@ in the real system time (default: 20).
Advances the clock to the the moment of the first scheduled timer, firing it.
**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.jump
* since: v1.45
@ -57,6 +121,33 @@ Advances the clock to the the moment of the first scheduled timer, firing it.
Advance the clock by jumping forward in time, firing callbacks at most once. Returns fake milliseconds since the unix epoch.
This can be used to simulate the JS engine (such as a browser) being put to sleep and resumed later, skipping intermediary timers.
**Usage**
```js
await page.clock.jump(1000);
await page.clock.jump('30:00');
```
```python async
await page.clock.jump(1000);
await page.clock.jump('30:00')
```
```python sync
page.clock.jump(1000);
page.clock.jump('30:00')
```
```java
page.clock().jump(1000);
page.clock().jump("30:00");
```
```csharp
await page.Clock.JumpAsync(1000);
await page.Clock.JumpAsync("30:00");
```
### param: Clock.jump.time
* since: v1.45
- `time` <[int]|[string]>
@ -68,6 +159,9 @@ Time may be the number of milliseconds to advance the clock by or a human-readab
- returns: <[int]> Fake milliseconds since the unix epoch.
Runs all pending timers until there are none remaining. If new timers are added while it is executing they will be run as well.
**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.
@ -87,6 +181,33 @@ This is useful when you want to run a test to completion, but the test recursive
Advance the clock, firing callbacks if necessary. Returns fake milliseconds since the unix epoch.
**Usage**
```js
await page.clock.tick(1000);
await page.clock.tick('30:00');
```
```python async
await page.clock.tick(1000);
await page.clock.tick('30:00')
```
```python sync
page.clock.tick(1000);
page.clock.tick('30:00')
```
```java
page.clock().tick(1000);
page.clock().tick("30:00");
```
```csharp
await page.Clock.TickAsync(1000);
await page.Clock.TickAsync("30:00");
```
### param: Clock.tick.time
* since: v1.45
- `time` <[int]|[string]>

187
docs/src/clock.md Normal file
View File

@ -0,0 +1,187 @@
---
id: clock
title: "Clock"
---
## Introduction
[`property: Page.clock`] overrides native global functions related to time allowing them to be manually controlled:
- `setTimeout`
- `clearTimeout`
- `setInterval`
- `clearInterval`
- `Date`
- `requestAnimationFrame`
- `cancelAnimationFrame`
- `requestIdleCallback`
By default, the clock starts at the unix epoch (timestamp of 0), but you can override it using the `now` option.
```js
await page.clock.install();
await page.clock.install({ now: new Date('2020-02-02') });
```
## Only fake Date.now
```html card
<input type="datetime-local" id="my-time" data-testid="my-time">
<script>
const renderTime = () => {
const time = new Date();
document.getElementById('my-time').value = time.toISOString().slice(0, 16);
setTimeout(renderTime, 1000);
};
renderTime();
</script>
```
```js
// Initialize clock with a specific time.
await page.clock.install({
now: new Date('2024-01-01T10:00:00Z'),
toFake: ['Date'],
});
await page.goto('http://localhost:3333');
await expect(page.getByTestId('my-time')).toHaveValue('2024-01-01T10:00');
```
```python async
# Initialize clock with a specific time.
await page.clock.install(
now=datetime.datetime(2024, 1, 1, 10, 0, 0, tzinfo=datetime.timezone.utc),
toFake=['Date'],
)
await page.goto('http://localhost:3333')
locator = page.get_by_test_id('my-time')
await expect(locator).to_have_value('2024-01-01T10:00')
```
```python sync
# Initialize clock with a specific time.
page.clock.install(
now=datetime.datetime(2024, 1, 1, 10, 0, 0, tzinfo=datetime.timezone.utc),
to_fake=['Date'],
)
page.goto('http://localhost:3333')
locator = page.get_by_test_id('my-time')
expect(locator).to_have_value('2024-01-01T10:00')
```
```java
// Initialize clock with a specific time.
page.clock().install(
new Clock.InstallOptions()
.setNow(Instant.parse("2024-01-01T10:00:00Z"))
.setToFake(new String[]{"Date"})
);
page.navigate("http://localhost:3333");
Locator locator = page.getByTestId("my-time");
assertThat(locator).hasValue("2024-01-01T10:00");
```
```csharp
// Initialize clock with a specific time.
await page.Clock.InstallAsync(
new ClockInstallOptions
{
Now = new DateTime(2024, 1, 1, 10, 0, 0, DateTimeKind.Utc),
ToFake = new[] { "Date" }
});
await page.GotoAsync("http://localhost:3333");
var locator = page.GetByTestId("my-time");
await Expect(locator).ToHaveValueAsync("2024-01-01T10:00");
```
## Assert page at different points in time
```html card
<input type="datetime-local" id="my-time" data-testid="my-time">
<script>
const renderTime = () => {
const time = new Date();
document.getElementById('my-time').value = time.toISOString().slice(0, 16);
setTimeout(renderTime, 1000);
};
renderTime();
</script>
```
```js
// Initialize clock with a specific time.
await page.clock.install({ now: new Date('2024-01-01T10:00:00Z') });
await page.goto('http://localhost:3333');
await expect(page.getByTestId('my-time')).toHaveValue('2024-01-01T10:00');
// Fast forward time 30 minutes without firing intermediate timers, as if the user
// closed and opened the lid of the laptop.
await page.clock.jump('30:00');
await expect(page.getByTestId('my-time')).toHaveValue('2024-01-01T10:30');
```
```python async
# Initialize clock with a specific time.
await page.clock.install(
now=datetime.datetime(2024, 1, 1, 10, 0, 0, tzinfo=datetime.timezone.utc),
toFake=['Date'],
)
await page.goto('http://localhost:3333')
locator = page.get_by_test_id('my-time')
await expect(locator).to_have_value('2024-01-01T10:00')
# Fast forward time 30 minutes without firing intermediate timers, as if the user
# closed and opened the lid of the laptop.
await page.clock.jump('30:00')
await expect(locator).to_have_value('2024-01-01T10:30')
```
```python sync
# Initialize clock with a specific time.
page.clock.install(
now=datetime.datetime(2024, 1, 1, 10, 0, 0, tzinfo=datetime.timezone.utc),
to_fake=['Date'],
)
page.goto('http://localhost:3333')
locator = page.get_by_test_id('my-time')
expect(locator).to_have_value('2024-01-01T10:00')
# Fast forward time 30 minutes without firing intermediate timers, as if the user
# closed and opened the lid of the laptop.
page.clock.jump('30:00')
expect(locator).to_have_value('2024-01-01T10:30')
```
```java
// Initialize clock with a specific time.
page.clock().install(
new Clock.InstallOptions()
.setNow(Instant.parse("2024-01-01T10:00:00Z"))
.setToFake(new String[]{"Date"})
);
page.navigate("http://localhost:3333");
Locator locator = page.getByTestId("my-time");
assertThat(locator).hasValue("2024-01-01T10:00");
// Fast forward time 30 minutes without firing intermediate timers, as if the user
// closed and opened the lid of the laptop.
page.clock().jump("30:00");
assertThat(locator).hasValue("2024-01-01T10:30");
```
```csharp
// Initialize clock with a specific time.
await page.Clock.InstallAsync(
new ClockInstallOptions
{
Now = new DateTime(2024, 1, 1, 10, 0, 0, DateTimeKind.Utc),
ToFake = new[] { "Date" }
});
await page.GotoAsync("http://localhost:3333");
var locator = page.GetByTestId("my-time");
await Expect(locator).ToHaveValueAsync("2024-01-01T10:00");
// Fast forward time 30 minutes without firing intermediate timers, as if the user
// closed and opened the lid of the laptop.
await page.Clock.JumpAsync("30:00");
await Expect(locator).ToHaveValueAsync("2024-01-01T10:30");
```

42
packages/playwright-core/types/types.d.ts vendored
View File

@ -17246,6 +17246,15 @@ export interface BrowserServer {
export interface Clock {
/**
* Creates a clock and installs it globally.
*
* **Usage**
*
* ```js
* await page.clock.install();
* await page.clock.install({ now });
* await page.clock.install({ now, toFake: ['Date'] });
* ```
*
* @param options
*/
install(options?: {
@ -17283,6 +17292,14 @@ export interface Clock {
* Advance the clock by jumping forward in time, firing callbacks at most once. Returns fake milliseconds since the
* unix epoch. This can be used to simulate the JS engine (such as a browser) being put to sleep and resumed later,
* skipping intermediary timers.
*
* **Usage**
*
* ```js
* await page.clock.jump(1000);
* await page.clock.jump('30:00');
* ```
*
* @param time 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.
*/
@ -17290,14 +17307,25 @@ export interface Clock {
/**
* Advances the clock to the the moment of the first scheduled timer, firing it.
*
* **Usage**
*
* ```js
* await page.clock.next();
* ```
*
*/
next(): Promise<number>;
/**
* Runs all pending timers until there are none remaining. If new timers are added while it is executing they will be
* run as well. 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 `loopLimit` times after which it assumes there
* is an infinite loop of timers and throws an error.
* run as well.
*
* **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 `loopLimit` times after which it assumes there is an infinite
* loop of timers and throws an error.
*/
runAll(): Promise<number>;
@ -17311,6 +17339,14 @@ export interface Clock {
/**
* Advance the clock, firing callbacks if necessary. Returns fake milliseconds since the unix epoch.
*
* **Usage**
*
* ```js
* await page.clock.tick(1000);
* await page.clock.tick('30:00');
* ```
*
* @param time 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.
*/