1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
//! Clock operations for time manipulation.
use std::time::Duration;
use tracing::{debug, instrument};
use viewpoint_js::js;
use super::{Clock, TimeValue};
use crate::error::PageError;
impl Clock<'_> {
/// Set a fixed time that doesn't advance.
///
/// All calls to `Date.now()` and new `Date()` will return this time.
/// Time remains frozen until you call `run_for`, `fast_forward`,
/// `set_system_time`, or `resume`.
///
/// # Arguments
///
/// * `time` - The time to set, either as an ISO 8601 string (e.g., "2024-01-01T00:00:00Z")
/// or a Unix timestamp in milliseconds.
///
/// # Errors
///
/// Returns an error if setting the time fails.
#[instrument(level = "debug", skip(self, time))]
pub async fn set_fixed_time(&self, time: impl Into<TimeValue>) -> Result<(), PageError> {
let time_value = time.into();
match &time_value {
TimeValue::Timestamp(ts) => {
self.evaluate(&js! { window.__viewpointClock.setFixedTime(#{ts}) })
.await?;
}
TimeValue::IsoString(s) => {
self.evaluate(&js! { window.__viewpointClock.setFixedTime(#{s}) })
.await?;
}
}
debug!(time = ?time_value, "Fixed time set");
Ok(())
}
/// Set the system time that flows normally.
///
/// Time starts from the specified value and advances in real time.
///
/// # Arguments
///
/// * `time` - The starting time, either as an ISO 8601 string or Unix timestamp.
///
/// # Errors
///
/// Returns an error if setting the time fails.
#[instrument(level = "debug", skip(self, time))]
pub async fn set_system_time(&self, time: impl Into<TimeValue>) -> Result<(), PageError> {
let time_value = time.into();
match &time_value {
TimeValue::Timestamp(ts) => {
self.evaluate(&js! { window.__viewpointClock.setSystemTime(#{ts}) })
.await?;
}
TimeValue::IsoString(s) => {
self.evaluate(&js! { window.__viewpointClock.setSystemTime(#{s}) })
.await?;
}
}
debug!(time = ?time_value, "System time set");
Ok(())
}
/// Advance time by a duration, firing any scheduled timers.
///
/// This advances the clock and executes any setTimeout/setInterval
/// callbacks that were scheduled to fire during that period.
///
/// # Arguments
///
/// * `duration` - The amount of time to advance.
///
/// # Returns
///
/// The number of timers that were fired.
///
/// # Errors
///
/// Returns an error if advancing time fails.
#[instrument(level = "debug", skip(self))]
pub async fn run_for(&self, duration: Duration) -> Result<u32, PageError> {
let ms = duration.as_millis();
let result: f64 = self
.evaluate_value(&js! { window.__viewpointClock.runFor(#{ms}) })
.await?;
debug!(
duration_ms = ms,
timers_fired = result as u32,
"Time advanced"
);
Ok(result as u32)
}
/// Fast-forward time without firing timers.
///
/// This advances the clock but does NOT execute scheduled timers.
/// Use this when you want to jump ahead in time quickly.
///
/// # Arguments
///
/// * `duration` - The amount of time to skip.
///
/// # Errors
///
/// Returns an error if fast-forwarding fails.
#[instrument(level = "debug", skip(self))]
pub async fn fast_forward(&self, duration: Duration) -> Result<(), PageError> {
let ms = duration.as_millis();
self.evaluate(&js! { window.__viewpointClock.fastForward(#{ms}) })
.await?;
debug!(duration_ms = ms, "Time fast-forwarded");
Ok(())
}
/// Pause at a specific time.
///
/// This sets the clock to the specified time and pauses it there.
///
/// # Arguments
///
/// * `time` - The time to pause at, as an ISO string or timestamp.
///
/// # Errors
///
/// Returns an error if pausing fails.
#[instrument(level = "debug", skip(self, time))]
pub async fn pause_at(&self, time: impl Into<TimeValue>) -> Result<(), PageError> {
let time_value = time.into();
match &time_value {
TimeValue::Timestamp(ts) => {
self.evaluate(&js! { window.__viewpointClock.pauseAt(#{ts}) })
.await?;
}
TimeValue::IsoString(s) => {
self.evaluate(&js! { window.__viewpointClock.pauseAt(#{s}) })
.await?;
}
}
debug!(time = ?time_value, "Clock paused");
Ok(())
}
/// Resume normal time flow.
///
/// After calling this, time will advance normally from the current
/// mocked time value.
///
/// # Errors
///
/// Returns an error if resuming fails.
#[instrument(level = "debug", skip(self))]
pub async fn resume(&self) -> Result<(), PageError> {
self.evaluate(js! { window.__viewpointClock.resume() })
.await?;
debug!("Clock resumed");
Ok(())
}
/// Run all pending timers.
///
/// This advances time to execute all scheduled setTimeout and setInterval
/// callbacks, as well as requestAnimationFrame callbacks.
///
/// # Returns
///
/// The number of timers that were fired.
///
/// # Errors
///
/// Returns an error if running timers fails.
#[instrument(level = "debug", skip(self))]
pub async fn run_all_timers(&self) -> Result<u32, PageError> {
let result: f64 = self
.evaluate_value(js! { window.__viewpointClock.runAllTimers() })
.await?;
debug!(timers_fired = result as u32, "All timers executed");
Ok(result as u32)
}
/// Run to the last scheduled timer.
///
/// This advances time to the last scheduled timer and executes all
/// timers up to that point.
///
/// # Returns
///
/// The number of timers that were fired.
///
/// # Errors
///
/// Returns an error if running timers fails.
#[instrument(level = "debug", skip(self))]
pub async fn run_to_last(&self) -> Result<u32, PageError> {
let result: f64 = self
.evaluate_value(js! { window.__viewpointClock.runToLast() })
.await?;
debug!(timers_fired = result as u32, "Ran to last timer");
Ok(result as u32)
}
/// Get the number of pending timers.
///
/// This includes setTimeout, setInterval, and requestAnimationFrame callbacks.
///
/// # Errors
///
/// Returns an error if getting the count fails.
#[instrument(level = "debug", skip(self))]
pub async fn pending_timer_count(&self) -> Result<u32, PageError> {
let result: f64 = self
.evaluate_value(js! { window.__viewpointClock.pendingTimerCount() })
.await?;
Ok(result as u32)
}
/// Check if clock mocking is installed.
///
/// # Errors
///
/// Returns an error if the check fails.
pub async fn is_installed(&self) -> Result<bool, PageError> {
let result: bool = self
.evaluate_value(
js! { window.__viewpointClock && window.__viewpointClock.isInstalled() },
)
.await
.unwrap_or(false);
Ok(result)
}
}