feat: allow custom advanceTimers implementation and update tick to microtask based approach (#231)

* feat: allow custom advanceTimers method to be passed to start

- Reworks userEvent to use a common user event session across all commands.

* test: add tests for custom advanceTimers

* feat: convert tick to microtask approach with Promise.resolve

* be more explicit in type forcing userEvent

* properly mark UserEvent import as a type import

* remove unnecessary checkUserEvent method

Author: OiNutter

src/Virtual.ts

@@ -8,13 +8,13 @@ import {
   ERR_VIRTUAL_NOT_STARTED,
 } from "./errors";
 import { getLiveSpokenPhrase, LIVE } from "./getLiveSpokenPhrase";
+import { type UserEvent, userEvent } from "@testing-library/user-event";
 import { flattenTree } from "./flattenTree";
 import { getElementNode } from "./commands/getElementNode";
 import { getItemText } from "./getItemText";
 import { getSpokenPhrase } from "./getSpokenPhrase";
 import { observeDOM } from "./observeDOM";
 import { tick } from "./tick";
-import { userEvent } from "@testing-library/user-event";
 import type { VirtualCommandArgs } from "./commands/types";
 
 /**
@@ -100,6 +100,15 @@ export interface StartOptions {
    * Defaults to `false`.
    */
   displayCursor?: boolean;
+
+  /**
+   * A function to be called internally to advance your fake timers (if applicable)
+   *
+   * @example jest.advanceTimersByTime
+   *
+   * @returns A promise that resolves after the specified delay, or void if not asynchronous.
+   */
+  advanceTimers?: (delay: number) => Promise<void> | void;
 }
 
 const defaultUserEventOptions = {
@@ -206,6 +215,7 @@ export class Virtual {
   #treeCache: AccessibilityNode[] | null = null;
   #disconnectDOMObserver: (() => void) | null = null;
   #boundHandleFocusChange: ((event: Event) => Promise<void>) | null = null;
+  #userEvent: UserEvent | null = null;
 
   #checkContainer() {
     if (!this.#container) {
@@ -284,7 +294,7 @@ export class Virtual {
      * REF: https://www.w3.org/TR/wai-aria-1.2/#aria-modal
      */
     return tree.filter(
-      ({ parentDialog }) => this.#activeNode!.parentDialog === parentDialog
+      ({ parentDialog }) => this.#activeNode!.parentDialog === parentDialog,
     );
   }
 
@@ -330,7 +340,7 @@ export class Virtual {
         getLiveSpokenPhrase({
           container,
           mutation,
-        })
+        }),
       )
       .filter(Boolean)
       .forEach((spokenPhrase) => {
@@ -342,7 +352,7 @@ export class Virtual {
     return this.#spokenPhraseLog.filter(
       (spokenPhrase) =>
         !spokenPhrase.startsWith(LIVE.ASSERTIVE) &&
-        !spokenPhrase.startsWith(LIVE.POLITE)
+        !spokenPhrase.startsWith(LIVE.POLITE),
     );
   }
 
@@ -368,7 +378,7 @@ export class Virtual {
       // cursor has changed.
       const tree = this.#getAccessibilityTree();
       const parentDialogNode = tree.find(
-        ({ node }) => node === accessibilityNode.parentDialog
+        ({ node }) => node === accessibilityNode.parentDialog,
       )!;
 
       const spokenPhrase = getSpokenPhrase(parentDialogNode);
@@ -426,7 +436,7 @@ export class Virtual {
         accessibleValue === this.#activeNode?.accessibleValue &&
         node === this.#activeNode?.node &&
         role === this.#activeNode?.role &&
-        spokenRole === this.#activeNode?.spokenRole
+        spokenRole === this.#activeNode?.spokenRole,
     );
   }
 
@@ -490,8 +500,8 @@ export class Virtual {
   get commands() {
     return Object.fromEntries<keyof VirtualCommands>(
       (Object.keys(commands) as (keyof VirtualCommands)[]).map(
-        (command: keyof VirtualCommands) => [command, command]
-      )
+        (command: keyof VirtualCommands) => [command, command],
+      ),
     ) as { [K in keyof VirtualCommands]: K };
   }
 
@@ -568,10 +578,15 @@ export class Virtual {
   // @ts-ignore for non-TS users we default the container to `null` which
   // prompts the missing container error.
   async start(
-    { container, displayCursor = false, window: root }: StartOptions = {
+    {
+      container,
+      displayCursor = false,
+      window: root,
+      advanceTimers,
+    }: StartOptions = {
       container: null as never,
       displayCursor: false,
-    }
+    },
   ) {
     if (!container) {
       throw new Error(ERR_VIRTUAL_MISSING_CONTAINER);
@@ -593,9 +608,15 @@ export class Virtual {
       (mutations: MutationRecord[]) => {
         this.#invalidateTreeCache();
         this.#announceLiveRegions(mutations);
-      }
+      },
     );
 
+    this.#userEvent = userEvent.setup({
+      ...defaultUserEventOptions,
+      document: container.ownerDocument ?? globalThis.document,
+      ...(advanceTimers ? { advanceTimers } : {}),
+    });
+
     const tree = this.#getAccessibilityTree();
 
     if (!tree.length) {
@@ -634,7 +655,10 @@ export class Virtual {
    */
   async stop() {
     this.#disconnectDOMObserver?.();
-    this.#container?.removeEventListener("focusin", this.#boundHandleFocusChange);
+    this.#container?.removeEventListener(
+      "focusin",
+      this.#boundHandleFocusChange,
+    );
     this.#invalidateTreeCache();
 
     if (this.#cursor) {
@@ -647,6 +671,7 @@ export class Virtual {
     this.#itemTextLog = [];
     this.#spokenPhraseLog = [];
     this.#boundHandleFocusChange = null;
+    this.#userEvent = null;
     return;
   }
 
@@ -762,6 +787,7 @@ export class Virtual {
    */
   async act() {
     this.#checkContainer();
+
     await tick();
 
     if (!this.#activeNode) {
@@ -776,7 +802,7 @@ export class Virtual {
      *
      * REF: https://www.w3.org/TR/core-aam-1.2/#mapping_actions
      */
-    await userEvent.click(target, defaultUserEventOptions);
+    await this.#userEvent!.click(target);
 
     return;
   }
@@ -878,7 +904,7 @@ export class Virtual {
     ].join("");
 
     this.#focusActiveElement();
-    await userEvent.keyboard(keyboardCommand, defaultUserEventOptions);
+    await this.#userEvent!.keyboard(keyboardCommand);
     await this.#refreshState(true);
 
     return;
@@ -918,7 +944,7 @@ export class Virtual {
     }
 
     const target = getElementNode(this.#activeNode);
-    await userEvent.type(target, text, defaultUserEventOptions);
+    await this.#userEvent!.type(target, text);
     await this.#refreshState(true);
 
     return;
@@ -949,7 +975,7 @@ export class Virtual {
    */
   async perform<
     T extends keyof VirtualCommands,
-    K extends Omit<Parameters<VirtualCommands[T]>[0], keyof VirtualCommandArgs>
+    K extends Omit<Parameters<VirtualCommands[T]>[0], keyof VirtualCommandArgs>,
   >(command: T, options?: { [L in keyof K]: K[L] }) {
     this.#checkContainer();
     await tick();
@@ -1023,10 +1049,7 @@ export class Virtual {
     const keys = key.repeat(clickCount);
     const target = getElementNode(this.#activeNode);
 
-    await userEvent.pointer(
-      [{ target }, { keys, target }],
-      defaultUserEventOptions
-    );
+    await this.#userEvent!.pointer([{ target }, { keys, target }]);
 
     return;
   }

src/tick.ts

@@ -1,3 +1,3 @@
 export async function tick() {
-  return await new Promise<void>((resolve) => setTimeout(() => resolve()));
+  return await Promise.resolve();
 }

test/int/act.int.test.ts

@@ -10,10 +10,8 @@ function setupButtonPage() {
   const button = document.createElement("button");
 
   button.addEventListener("click", function (event) {
-     
-    document.getElementById(
-      "status"
-    )!.innerHTML = `Clicked ${event.detail} Time(s)`;
+    document.getElementById("status")!.innerHTML =
+      `Clicked ${event.detail} Time(s)`;
   });
 
   button.innerHTML = "Click Me";
@@ -51,7 +49,6 @@ describe("act", () => {
   });
 
   it("should handle requests to perform the default action on hidden container gracefully", async () => {
-     
     const container = document.querySelector("#hidden")!;
 
     await virtual.start({ container });
@@ -63,4 +60,30 @@ describe("act", () => {
 
     await virtual.stop();
   });
+
+  it("should support custom advanceTimers implementations", async () => {
+    const container = document.body;
+
+    const advanceTimers = jest.fn();
+    await virtual.start({ container, advanceTimers });
+
+    expect(getByText(container, "Not Clicked")).toBeInTheDocument();
+
+    while ((await virtual.itemText()) !== "Click Me") {
+      await virtual.next();
+    }
+
+    await virtual.act();
+
+    expect(queryByText(container, "Not Clicked")).not.toBeInTheDocument();
+    expect(getByText(container, "Clicked 1 Time(s)")).toBeInTheDocument();
+    expect(advanceTimers).toHaveBeenCalled();
+
+    await virtual.previous();
+    await virtual.previous();
+
+    expect(await virtual.lastSpokenPhrase()).toEqual("Clicked 1 Time(s)");
+
+    await virtual.stop();
+  });
 });

test/int/click.int.test.ts

@@ -10,18 +10,15 @@ function setupButtonPage() {
   const button = document.createElement("button");
 
   button.addEventListener("click", function (event) {
-     
-    document.getElementById(
-      "status"
-    )!.innerHTML = `Clicked ${event.detail} Time(s)`;
+    document.getElementById("status")!.innerHTML =
+      `Clicked ${event.detail} Time(s)`;
   });
 
   button.innerHTML = "Click Me";
 
   document.body.appendChild(button);
 
   document.body.addEventListener("contextmenu", () => {
-     
     document.getElementById("status")!.innerHTML = "Right Clicked";
   });
 }
@@ -128,7 +125,6 @@ describe("click", () => {
   });
 
   it("should handle requests to click on hidden container gracefully", async () => {
-     
     const container = document.querySelector("#hidden")!;
 
     await virtual.start({ container });
@@ -140,4 +136,31 @@ describe("click", () => {
 
     await virtual.stop();
   });
+
+  it("should support custom advance timers implementations", async () => {
+    const container = document.body;
+
+    const advanceTimers = jest.fn();
+
+    await virtual.start({ container, advanceTimers });
+
+    expect(getByText(container, "Not Clicked")).toBeInTheDocument();
+
+    while ((await virtual.itemText()) !== "Click Me") {
+      await virtual.next();
+    }
+
+    await virtual.click();
+
+    expect(queryByText(container, "Not Clicked")).not.toBeInTheDocument();
+    expect(getByText(container, "Clicked 1 Time(s)")).toBeInTheDocument();
+    expect(advanceTimers).toHaveBeenCalled();
+
+    await virtual.previous();
+    await virtual.previous();
+
+    expect(await virtual.lastSpokenPhrase()).toEqual("Clicked 1 Time(s)");
+
+    await virtual.stop();
+  });
 });

test/int/press.int.test.ts

@@ -43,7 +43,6 @@ describe("press", () => {
   });
 
   it("should handle requests to press on hidden container gracefully", async () => {
-     
     const container = document.querySelector("#hidden")!;
 
     await virtual.start({ container });
@@ -68,4 +67,24 @@ describe("press", () => {
 
     await virtual.stop();
   });
+
+  it("should support custom advanceTimers implementations", async () => {
+    const advanceTimers = jest.fn();
+    const container = document.body;
+
+    await virtual.start({ container, advanceTimers });
+
+    await virtual.next();
+    await virtual.next();
+
+    expect(await virtual.itemText()).toEqual("Input Some Text");
+
+    await virtual.press("Shift+a+b+c");
+    // TODO: FAIL Testing Library user-event doesn't support modification yet, this should be "ABC"
+    expect(getByRole(container, "textbox")).toHaveValue("abc");
+    expect(await virtual.itemText()).toEqual("Input Some Text, abc");
+    expect(advanceTimers).toHaveBeenCalled();
+
+    await virtual.stop();
+  });
 });

test/int/type.int.test.ts

@@ -37,7 +37,6 @@ describe("type", () => {
   });
 
   it("should handle requests to type on hidden container gracefully", async () => {
-     
     const container = document.querySelector("#hidden")!;
 
     await virtual.start({ container });
@@ -49,4 +48,23 @@ describe("type", () => {
 
     await virtual.stop();
   });
+
+  it("should support custom advanceTimers implementations", async () => {
+    const advanceTimers = jest.fn();
+    const container = document.body;
+
+    await virtual.start({ container, advanceTimers });
+
+    await virtual.next();
+    await virtual.next();
+
+    expect(await virtual.itemText()).toEqual("Input Some Text");
+
+    await virtual.type("Hello World!");
+    expect(getByRole(container, "textbox")).toHaveValue("Hello World!");
+    expect(await virtual.itemText()).toEqual("Input Some Text, Hello World!");
+    expect(advanceTimers).toHaveBeenCalled();
+
+    await virtual.stop();
+  });
 });