docs: add examples to new and updated fake timers pages

Each new clock API page now includes a runnable test file wired up via
the VitePress <<< snippet include. Tests are written to match the real
behavior validated in sinonjs/fake-timers:

- jump: ignores timers outside window, fires at destination time,
  fires intervals at most once, accepts human-readable strings
- runToLast: returns time of last timer, skips timers added beyond
  last scheduled time, runToLastAsync resolves microtasks first
- runToFrame: advances to successive 16ms boundaries, fires timers in frame
- runMicrotasks: flushes nextTick and queueMicrotask, skips setTimeout
- countTimers: zero on fresh clock, counts remaining after tick,
  includes nextTick microtasks
- setSystemTime: does not affect timer scheduling (key subtlety),
  accepts number or Date
- reset: empties queue and returns to install time

Also adds <<< snippet include to index.md (existing _index.test.js).

Author: Julia Miller

docs/concepts/fake-timers/count-timers.md

@@ -6,3 +6,5 @@ description: Returns the number of waiting timers.
 # `clock.countTimers()`
 
 Returns the number of waiting timers.
+
+<<< ../../.vitepress/tests/docs/fake-timers/api/count-timers.test.js

docs/concepts/fake-timers/index.md

@@ -13,3 +13,5 @@ Fake timers provide a `clock` object to pass time, which can also be used to con
 
 For standalone usage of fake timers it is recommended to use [fake-timers](https://github.com/sinonjs/fake-timers) package instead. It provides the same
 set of features (Sinon uses it under the hood) and was previously extracted from Sinon.JS.
+
+<<< ../../.vitepress/tests/docs/fake-timers/_index.test.js

docs/concepts/fake-timers/jump.md

@@ -9,3 +9,5 @@ Advance the clock by jumping forward in time, firing callbacks at most once.
 `time` takes the same formats as [`clock.tick`](./tick).
 
 This can be used to simulate the JS engine (such as a browser) being put to sleep and resumed later, skipping intermediary timers.
+
+<<< ../../.vitepress/tests/docs/fake-timers/api/jump.test.js

docs/concepts/fake-timers/reset.md

@@ -6,3 +6,5 @@ description: Resets the clock to its initial now value and clears all pending ti
 # `clock.reset()`
 
 Resets the clock to its initial `now` value and clears all pending timers.
+
+<<< ../../.vitepress/tests/docs/fake-timers/api/reset.test.js

docs/concepts/fake-timers/run-microtasks.md

@@ -6,3 +6,5 @@ description: Runs all pending microtasks such as process.nextTick or Promise cal
 # `clock.runMicrotasks()`
 
 Runs all pending microtasks (e.g. `process.nextTick` or `Promise` callbacks).
+
+<<< ../../.vitepress/tests/docs/fake-timers/api/run-microtasks.test.js

docs/concepts/fake-timers/run-to-frame.md

@@ -6,3 +6,5 @@ description: Advances the clock to the next animation frame (standard 16ms).
 # `clock.runToFrame()`
 
 Advances the clock to the next animation frame (standard 16ms).
+
+<<< ../../.vitepress/tests/docs/fake-timers/api/run-to-frame.test.js

docs/concepts/fake-timers/run-to-last.md

@@ -8,3 +8,5 @@ description: Runs all pending timers until the last timer has been fired. Use ru
 This runs all pending timers until the last timer has been fired. If new timers are added while it is executing they will be run as well.
 
 The `runToLastAsync()` will also break the event loop, allowing any scheduled promise callbacks to execute _before_ running the timers.
+
+<<< ../../.vitepress/tests/docs/fake-timers/api/run-to-last.test.js

docs/concepts/fake-timers/set-system-time.md

@@ -6,3 +6,5 @@ description: Change the system time without firing any timers.
 # `clock.setSystemTime([now])`
 
 This allows you to change the system time to the provided `now` (number or Date) without firing any timers.
+
+<<< ../../.vitepress/tests/docs/fake-timers/api/set-system-time.test.js

docs/tests/docs/fake-timers/api/count-timers.test.js

@@ -0,0 +1,41 @@
+import t from "tap";
+import sinon from "sinon";
+
+t.test("clock.countTimers returns zero for a fresh clock", (t) => {
+  const clock = sinon.useFakeTimers();
+
+  t.equal(clock.countTimers(), 0, "fresh clock should have no pending timers");
+
+  clock.restore();
+  t.end();
+});
+
+t.test("clock.countTimers counts remaining timers after a tick", (t) => {
+  const clock = sinon.useFakeTimers();
+
+  setTimeout(() => {}, 100);
+  setTimeout(() => {}, 200);
+  setTimeout(() => {}, 300);
+
+  clock.tick(150);
+
+  t.equal(clock.countTimers(), 2, "two timers should remain after 150ms");
+
+  clock.restore();
+  t.end();
+});
+
+t.test("clock.countTimers includes microtasks such as nextTick", (t) => {
+  const clock = sinon.useFakeTimers({ toFake: ["nextTick"] });
+
+  process.nextTick(() => {});
+
+  t.equal(
+    clock.countTimers(),
+    1,
+    "nextTick callback should count as a pending timer"
+  );
+
+  clock.restore();
+  t.end();
+});

docs/tests/docs/fake-timers/api/jump.test.js

@@ -0,0 +1,70 @@
+import t from "tap";
+import sinon from "sinon";
+
+t.test("clock.jump ignores timers not within the jump window", (t) => {
+  const clock = sinon.useFakeTimers({ now: 0 });
+
+  let called = false;
+  setTimeout(() => {
+    called = true;
+  }, 1000);
+
+  clock.jump(500);
+
+  t.notOk(called, "timer beyond jump window should not have fired");
+
+  clock.restore();
+  t.end();
+});
+
+t.test("clock.jump fires timers within the jump window at the destination time", (t) => {
+  const clock = sinon.useFakeTimers({ now: 0 });
+
+  let calledAt = null;
+  setTimeout(() => {
+    calledAt = Date.now();
+  }, 1000);
+
+  clock.jump(2000);
+
+  t.equal(calledAt, 2000, "timer should fire and see the jump destination as the current time");
+
+  clock.restore();
+  t.end();
+});
+
+t.test(
+  "clock.jump fires each interval at most once regardless of elapsed time",
+  (t) => {
+    const clock = sinon.useFakeTimers({ now: 0 });
+
+    let callCount = 0;
+    setInterval(() => {
+      callCount++;
+    }, 100);
+
+    // A plain tick(1500) would fire the interval ~15 times; jump fires it once
+    clock.jump(1500);
+
+    t.equal(callCount, 1, "interval should have fired at most once");
+
+    clock.restore();
+    t.end();
+  }
+);
+
+t.test("clock.jump supports human-readable string time arguments", (t) => {
+  const clock = sinon.useFakeTimers({ now: 0 });
+
+  let called = false;
+  setTimeout(() => {
+    called = true;
+  }, 100000); // 1 minute 40 seconds
+
+  clock.jump("01:50"); // 1 minute 50 seconds
+
+  t.ok(called, "timer should have fired after string-format jump");
+
+  clock.restore();
+  t.end();
+});