feat: add deterministic async ui controls

Author: vitronai

CHANGELOG.md

@@ -16,6 +16,7 @@ All notable changes to this project are documented in this file.
 - Added project-aware JS/TS runtime support for TSX, ESM `.js`, `tsconfig` path aliases, `setupFiles`, and `jsdom` environments.
 - Added first-party snapshots, mocks, run-diff artifacts, and watch mode for tighter agent rerun loops.
 - Added a lightweight DOM-oriented `jsdom` UI test layer with `render`, `screen`, `fireEvent`, `waitFor`, `cleanup`, and UI matchers for text, attributes, and document presence.
+- Added deterministic async UI test controls with fake timers, microtask flushing, and first-party fetch mocking for `jsdom` tests.
 - Added an in-repo VS Code extension scaffold for artifact-driven result viewing, reruns, and HTML report opening.
 - Expanded the VS Code extension scaffold with generated-review navigation for source/test/hint mappings and unresolved generation backlog.
 - Refreshed README, AGENTS, and supporting docs to match the current package scope, JS/TS feature set, artifact contracts, and extension surface.

README.md

@@ -272,6 +272,9 @@ For UI-oriented `jsdom` tests, Themis also ships a lightweight DOM layer:
 - `fireEvent.click/change/input/submit/keyDown(...)`
 - `waitFor(asyncAssertion)`
 - `cleanup()`
+- `useFakeTimers()`, `advanceTimersByTime(ms)`, `runAllTimers()`, `useRealTimers()`
+- `flushMicrotasks()`
+- `mockFetch(...)`, `resetFetchMocks()`, `restoreFetch()`
 
 Example:
 
@@ -287,6 +290,30 @@ test('submits the form', async () => {
 });
 ```
 
+Network and async example:
+
+```ts
+test('loads api state deterministically', async () => {
+  useFakeTimers();
+  const fetchMock = mockFetch({ json: { ok: true } });
+
+  let done = false;
+  setTimeout(async () => {
+    const response = await fetch('/api/status');
+    const payload = await response.json();
+    done = payload.ok;
+  }, 50);
+
+  advanceTimersByTime(50);
+  await flushMicrotasks();
+
+  expect(done).toBe(true);
+  expect(fetchMock).toHaveBeenCalled();
+  useRealTimers();
+  restoreFetch();
+});
+```
+
 ## Intent Syntax
 
 Themis supports a strict code-native intent DSL:

docs/api.md

@@ -171,6 +171,14 @@ Themis exposes a lightweight DOM-oriented helper layer for `jsdom` tests:
 - `fireEvent.keyDown(node, payload?)`
 - `waitFor(assertion, options?)`
 - `cleanup()`
+- `useFakeTimers()`
+- `useRealTimers()`
+- `advanceTimersByTime(ms)`
+- `runAllTimers()`
+- `flushMicrotasks()`
+- `mockFetch(handlerOrResponse)`
+- `resetFetchMocks()`
+- `restoreFetch()`
 
 Supported DOM matchers:
 
@@ -180,6 +188,14 @@ Supported DOM matchers:
 
 These helpers are intentionally small and deterministic. They are designed for generated UI unit-layer tests and human-authored component tests running in Themis `jsdom` mode.
 
+`mockFetch(...)` accepts either:
+
+- a function `(input, init) => response`
+- a Response instance
+- a shorthand object like `{ status, headers, body }` or `{ status, json }`
+
+The fake timer helpers only patch the current Themis runtime. They do not mutate system time outside the active test process.
+
 ## Config File (`themis.config.json`)
 
 | Field | Type | Default | Notes |

globals.d.ts

@@ -12,6 +12,8 @@ import type {
   ScreenApi,
   SpyOn,
   Test,
+  FetchMock,
+  FlushMicrotasks,
   WaitFor
 } from './index';
 
@@ -37,6 +39,14 @@ declare global {
   var fireEvent: FireEventApi;
   var waitFor: WaitFor;
   var cleanup: Cleanup;
+  var useFakeTimers: () => void;
+  var useRealTimers: () => void;
+  var advanceTimersByTime: (ms: number) => void;
+  var runAllTimers: () => void;
+  var flushMicrotasks: FlushMicrotasks;
+  var mockFetch: (handlerOrResponse: unknown) => FetchMock;
+  var restoreFetch: () => void;
+  var resetFetchMocks: () => void;
 }
 
 export {};

index.d.ts

@@ -503,6 +503,15 @@ export interface FireEventApi {
 export type Render = (input: unknown, options?: { container?: HTMLElement }) => RenderResult;
 export type WaitFor = <T>(assertion: () => T | Promise<T>, options?: { timeout?: number; interval?: number }) => Promise<T>;
 export type Cleanup = () => void;
+export type FetchMock = MockFunction<any[], Promise<unknown>>;
+export type UseFakeTimers = () => void;
+export type UseRealTimers = () => void;
+export type AdvanceTimersByTime = (ms: number) => void;
+export type RunAllTimers = () => void;
+export type FlushMicrotasks = () => Promise<void>;
+export type MockFetch = (handlerOrResponse: unknown) => FetchMock;
+export type RestoreFetch = () => void;
+export type ResetFetchMocks = () => void;
 
 export type SuiteFn = () => void;
 export type TestFn = () => Awaitable<void>;

src/runtime.js

@@ -284,7 +284,15 @@ function installGlobals(api) {
     'screen',
     'fireEvent',
     'waitFor',
-    'cleanup'
+    'cleanup',
+    'useFakeTimers',
+    'useRealTimers',
+    'advanceTimersByTime',
+    'runAllTimers',
+    'flushMicrotasks',
+    'mockFetch',
+    'restoreFetch',
+    'resetFetchMocks'
   ];
   const previous = {};
   for (const name of names) {
@@ -312,6 +320,14 @@ function installGlobals(api) {
   global.fireEvent = api.fireEvent;
   global.waitFor = api.waitFor;
   global.cleanup = api.cleanup;
+  global.useFakeTimers = api.useFakeTimers;
+  global.useRealTimers = api.useRealTimers;
+  global.advanceTimersByTime = api.advanceTimersByTime;
+  global.runAllTimers = api.runAllTimers;
+  global.flushMicrotasks = api.flushMicrotasks;
+  global.mockFetch = api.mockFetch;
+  global.restoreFetch = api.restoreFetch;
+  global.resetFetchMocks = api.resetFetchMocks;
 
   return previous;
 }