wpt: run JS timers on virtual time, fast-forwarding instead of sleeping (#821)

Author: nicoburns

packages/blitz-vibey-script/src/clock.rs

@@ -0,0 +1,100 @@
+//! The clock which drives JS-observable time (timers and `Date`).
+
+use std::cell::RefCell;
+use std::rc::Rc;
+
+use web_time::{Duration, Instant, SystemTime, UNIX_EPOCH};
+
+/// The clock used for JS timer deadlines and `Date`.
+///
+/// In the default real mode it tracks the system's monotonic clock. In
+/// virtual mode, time only advances when [`advance_to`](ScriptClock::advance_to)
+/// is called: embedders which drive timers manually (e.g. test runners) can
+/// jump straight to the next timer deadline instead of sleeping until it,
+/// while preserving timer ordering.
+#[derive(Clone)]
+pub(crate) struct ScriptClock {
+    inner: Rc<RefCell<ClockMode>>,
+}
+
+enum ClockMode {
+    Real,
+    Virtual { now: Instant },
+}
+
+impl Default for ScriptClock {
+    fn default() -> Self {
+        Self {
+            inner: Rc::new(RefCell::new(ClockMode::Real)),
+        }
+    }
+}
+
+impl ScriptClock {
+    /// The current time according to this clock
+    pub fn now(&self) -> Instant {
+        match *self.inner.borrow() {
+            ClockMode::Real => Instant::now(),
+            ClockMode::Virtual { now } => now,
+        }
+    }
+
+    /// Switch to virtual mode. Time stops at the current instant and only
+    /// advances via [`advance_to`](Self::advance_to).
+    pub fn make_virtual(&self) {
+        let mut mode = self.inner.borrow_mut();
+        if matches!(*mode, ClockMode::Real) {
+            *mode = ClockMode::Virtual {
+                now: Instant::now(),
+            };
+        }
+    }
+
+    /// Advance a virtual clock to `deadline` (never backwards).
+    /// Does nothing in real mode.
+    pub fn advance_to(&self, deadline: Instant) {
+        if let ClockMode::Virtual { now } = &mut *self.inner.borrow_mut() {
+            *now = (*now).max(deadline);
+        }
+    }
+}
+
+/// Adapter exposing a [`ScriptClock`] as a Boa [`Clock`](boa_engine::context::Clock),
+/// so that `Date` observes virtual time consistently with timers.
+pub(crate) struct BoaClockAdapter {
+    pub clock: ScriptClock,
+    /// Anchor for converting `Instant`s to durations-since-an-epoch
+    pub base: Instant,
+    /// Wall-clock time (ms since the Unix epoch) at `base`
+    pub base_system_millis: i64,
+}
+
+impl BoaClockAdapter {
+    pub fn new(clock: ScriptClock) -> Self {
+        let base = clock.now();
+        let base_system_millis = SystemTime::now()
+            .duration_since(UNIX_EPOCH)
+            .unwrap_or(Duration::ZERO)
+            .as_millis() as i64;
+        Self {
+            clock,
+            base,
+            base_system_millis,
+        }
+    }
+
+    fn elapsed(&self) -> Duration {
+        self.clock.now().saturating_duration_since(self.base)
+    }
+}
+
+impl boa_engine::context::Clock for BoaClockAdapter {
+    fn now(&self) -> boa_engine::context::time::JsInstant {
+        let elapsed = self.elapsed();
+        boa_engine::context::time::JsInstant::new(elapsed.as_secs(), elapsed.subsec_nanos())
+    }
+
+    fn system_time_millis(&self) -> i64 {
+        self.base_system_millis + self.elapsed().as_millis() as i64
+    }
+}

packages/blitz-vibey-script/src/document.rs

@@ -116,6 +116,33 @@ impl ScriptDocument {
         self
     }
 
+    /// Switch the document's clock (which drives JS timer deadlines and
+    /// `Date`) to virtual time: time stops and only advances via
+    /// [`advance_clock_to`](Self::advance_clock_to).
+    ///
+    /// Intended for embedders which drive timers manually by polling
+    /// [`next_timer_deadline`](Self::next_timer_deadline) and calling
+    /// [`poll`](blitz_traits::Document::poll): instead of sleeping until the
+    /// next deadline they can jump the clock straight to it, preserving timer
+    /// ordering without wall-clock waiting. Should be combined with
+    /// [`without_timer_thread`](Self::without_timer_thread) (the timer thread
+    /// sleeps in real time).
+    pub fn with_virtual_time(self) -> Self {
+        self.runtime.ctx.state.borrow().clock.make_virtual();
+        self
+    }
+
+    /// The current time according to the document's clock (virtual or real)
+    pub fn clock_now(&self) -> Instant {
+        self.runtime.ctx.state.borrow().clock.now()
+    }
+
+    /// Advance a virtual clock to `deadline` (never backwards). Does nothing
+    /// unless [`with_virtual_time`](Self::with_virtual_time) was used.
+    pub fn advance_clock_to(&mut self, deadline: Instant) {
+        self.runtime.ctx.state.borrow().clock.advance_to(deadline);
+    }
+
     /// Override the [`ScriptFetcher`] used to load external (`src="..."`) scripts
     /// and ES module imports. The default fetcher supports `file:` and `data:` URLs.
     pub fn with_fetcher(self, fetcher: impl ScriptFetcher) -> Self {

packages/blitz-vibey-script/src/lib.rs

@@ -29,6 +29,7 @@
 
 #![allow(clippy::collapsible_if)]
 
+mod clock;
 mod document;
 mod dom;
 mod event_handler;

packages/blitz-vibey-script/src/runtime.rs

@@ -513,11 +513,15 @@ impl ScriptRuntime {
             base_url: base_url.cloned(),
             modules: RefCell::new(HashMap::new()),
         });
+        let ctx = DomCtx::new(doc);
+        // Share the runtime's clock with boa so that `Date` observes the same
+        // (possibly virtual) time as timers
+        let clock = ctx.state.borrow().clock.clone();
         let mut context = Context::builder()
             .module_loader(module_loader.clone())
+            .clock(Rc::new(crate::clock::BoaClockAdapter::new(clock)))
             .build()
             .expect("failed to build JS context");
-        let ctx = DomCtx::new(doc);
         context.insert_data(ctx.clone());
 
         Console::register_with_logger(LogCrateLogger, &mut context)
@@ -812,7 +816,11 @@ impl ScriptRuntime {
 
     /// Run all timers that are currently due. Returns `true` if any JavaScript was run.
     pub fn run_due_timers(&mut self) -> bool {
-        let due = self.ctx.state.borrow_mut().timers.take_due(Instant::now());
+        let due = {
+            let mut state = self.ctx.state.borrow_mut();
+            let now = state.clock.now();
+            state.timers.take_due(now)
+        };
         if due.is_empty() {
             return false;
         }
@@ -1262,11 +1270,9 @@ fn set_timeout(_: &JsValue, args: &[JsValue], context: &mut Context) -> JsResult
     let Some((callback, delay, rest)) = timer_args(args, context)? else {
         return Ok(JsValue::from(0));
     };
-    let id = ctx
-        .state
-        .borrow_mut()
-        .timers
-        .add(delay, None, callback, rest);
+    let mut state = ctx.state.borrow_mut();
+    let now = state.clock.now();
+    let id = state.timers.add(now, delay, None, callback, rest);
     Ok(JsValue::from(id as f64))
 }
 
@@ -1275,11 +1281,9 @@ fn set_interval(_: &JsValue, args: &[JsValue], context: &mut Context) -> JsResul
     let Some((callback, delay, rest)) = timer_args(args, context)? else {
         return Ok(JsValue::from(0));
     };
-    let id = ctx
-        .state
-        .borrow_mut()
-        .timers
-        .add(delay, Some(delay), callback, rest);
+    let mut state = ctx.state.borrow_mut();
+    let now = state.clock.now();
+    let id = state.timers.add(now, delay, Some(delay), callback, rest);
     Ok(JsValue::from(id as f64))
 }
 
@@ -1298,7 +1302,10 @@ fn request_animation_frame(
     };
     // Approximate the next frame as ~16ms away
     let timestamp = JsValue::from(16.0);
-    let id = ctx.state.borrow_mut().timers.add(
+    let mut state = ctx.state.borrow_mut();
+    let now = state.clock.now();
+    let id = state.timers.add(
+        now,
         Duration::from_millis(16),
         None,
         callback,

packages/blitz-vibey-script/src/state.rs

@@ -9,6 +9,7 @@ use blitz_dom::{BaseDocument, NodeId};
 use boa_engine::object::JsObject;
 use boa_engine::{Finalize, JsData, Trace};
 
+use crate::clock::ScriptClock;
 use crate::timers::TimerQueue;
 
 /// Prototype objects for the DOM wrapper classes
@@ -73,6 +74,8 @@ pub(crate) struct RuntimeState {
     pub window_listeners: ListenerMap,
     /// Pending timers (`setTimeout`/`setInterval`/`requestAnimationFrame`)
     pub timers: TimerQueue,
+    /// The clock driving timer deadlines and `Date`
+    pub clock: ScriptClock,
     /// Messages sent from JavaScript to the embedder via the
     /// `__blitz_send_message` native function. Drained with
     /// [`ScriptDocument::take_messages`](crate::ScriptDocument::take_messages).

packages/blitz-vibey-script/src/timers.rs

@@ -22,6 +22,7 @@ pub(crate) struct TimerQueue {
 impl TimerQueue {
     pub fn add(
         &mut self,
+        now: Instant,
         delay: Duration,
         interval: Option<Duration>,
         callback: JsObject,
@@ -31,7 +32,7 @@ impl TimerQueue {
         let id = self.next_id;
         self.timers.push(Timer {
             id,
-            deadline: Instant::now() + delay,
+            deadline: now + delay,
             interval,
             callback,
             args,

wpt/runner/src/test_runners/mod.rs

@@ -119,9 +119,12 @@ pub fn attr_test_needs_scripts(doc: &BaseDocument) -> bool {
 /// and execute its scripts
 pub fn run_document_scripts(ctx: &ThreadCtx, document: BaseDocument) -> ScriptDocument {
     // The runner drives timers manually via `pump_timers`, so the background
-    // timer wakeup thread is unnecessary
+    // timer wakeup thread is unnecessary. Timers run on virtual time: there is
+    // no external event source, so `pump_timers` fast-forwards the clock to
+    // each timer deadline instead of sleeping until it.
     let mut script_document = ScriptDocument::from_base_document(document)
         .without_timer_thread()
+        .with_virtual_time()
         .with_fetcher(WptScriptFetcher::new(ctx.wpt_dir.clone()));
     script_document.execute_scripts();
     script_document
@@ -130,22 +133,28 @@ pub fn run_document_scripts(ctx: &ThreadCtx, document: BaseDocument) -> ScriptDo
 /// Pump the document's pending JS timers until `check` produces a result or
 /// there are no more timers due within `budget`. `check` runs once before any
 /// timer fires and again after each timer poll.
+///
+/// The document runs on virtual time (see [`run_document_scripts`]): instead
+/// of sleeping until the next timer deadline, the clock is fast-forwarded to
+/// it, so timers fire in deadline order without wall-clock waiting. `budget`
+/// bounds both virtual time and (as a backstop for timer callbacks which
+/// reschedule themselves indefinitely, e.g. rAF loops) real time.
 pub fn pump_timers<T>(
     document: &mut ScriptDocument,
     budget: Duration,
     mut check: impl FnMut(&mut ScriptDocument) -> Option<T>,
 ) -> Option<T> {
-    let deadline = Instant::now() + budget;
+    let real_deadline = Instant::now() + budget;
+    let virtual_deadline = document.clock_now() + budget;
     loop {
         if let Some(result) = check(document) {
             return Some(result);
         }
         match document.next_timer_deadline() {
-            Some(timer_deadline) if timer_deadline <= deadline => {
-                let now = Instant::now();
-                if timer_deadline > now {
-                    std::thread::sleep(timer_deadline - now);
-                }
+            Some(timer_deadline)
+                if timer_deadline <= virtual_deadline && Instant::now() < real_deadline =>
+            {
+                document.advance_clock_to(timer_deadline);
                 document.poll(None);
             }
             // Timer budget expired, or no pending timers