feat(mocking): introduce mock$ to verify interactions with component callbacks (experimental)

Author: ianlet

README.md

@@ -92,6 +92,7 @@ src="https://raw.githubusercontent.com/ianlet/qwik-testing-library/main/high-vol
 - [Setup](#setup)
 - [Examples](#examples)
     - [Qwikstart](#qwikstart)
+    - [Mocking Component Callbacks (experimental)](#mocking-component-callbacks-experimental)
     - [Qwik City - `server$` calls](#qwik-city---server-calls)
 - [Gotchas](#gotchas)
 - [Issues](#issues)
@@ -303,6 +304,64 @@ describe("<Counter />", () => {
 })
 ```
 
+### Mocking Component Callbacks (experimental)
+
+> [!WARNING]
+> This feature is under a testing phase and thus experimental.
+> Its API may change in the future, so use it at your own risk.
+
+The Qwik Testing Library provides a `mock$` function
+that can be used to create a mock of a QRL and verify interactions on your Qwik components.
+
+It is _not_ a replacement of regular mocking functions (such as `vi.fn` and `vi.mock`) as its intended use is only for
+testing callbacks of Qwik components.
+
+Here's an example on how to use the `mock$` function:
+
+```tsx title="counter.spec.tsx"
+// import qwik-testing methods
+import {mock$, clearAllMock, render, screen, waitFor} from "@noma.to/qwik-testing-library";
+// import the userEvent methods to interact with the DOM
+import userEvent from "@testing-library/user-event";
+
+// import the component to be tested
+import {Counter} from "./counter";
+
+// describe the test suite
+describe("<Counter />", () => {
+  // initialize a mock
+  // note: the empty callback is required but currently unused
+  const onChangeMock = mock$(() => {
+  });
+
+  // setup beforeEach block to run before each test
+  beforeEach(() => {
+    // remember to always clear all mocks before each test
+    clearAllMocks();
+  });
+
+  // describe the 'on increment' test cases
+  describe("on increment", () => {
+    // describe the test case
+    it("should call onChange$", async () => {
+      // render the component into the DOM
+      await render(<Counter value={0} onChange$={onChangeMock}/>);
+
+      // retrieve the 'decrement' button
+      const decrementBtn = screen.getByRole("button", {name: "Decrement"});
+      // click the button
+      await userEvent.click(decrementBtn);
+
+      // assert that the onChange$ callback was called with the right value
+      // note: QRLs are async in Qwik, so we need to resolve them to verify interactions
+      await waitFor(() =>
+        expect(onChangeMock.resolve()).resolves.toHaveBeenCalledWith(-1),
+      );
+    });
+  });
+})
+```
+
 ### Qwik City - `server$` calls
 
 If one of your Qwik components uses `server$` calls, your tests might fail with a rather cryptic message (e.g. `QWIK

apps/qwik-testing-library-e2e-tests/src/components/counter.spec.tsx

@@ -0,0 +1,71 @@
+import {
+  clearAllMocks,
+  mock$,
+  render,
+  screen,
+  waitFor,
+} from "@noma.to/qwik-testing-library";
+import { Counter } from "./counter";
+import userEvent from "@testing-library/user-event";
+
+describe("<Counter />", () => {
+  const onChangeMock = mock$(() => {});
+
+  beforeEach(() => {
+    clearAllMocks();
+  });
+
+  it("should start at 0 by default", async () => {
+    await render(<Counter onChange$={onChangeMock} />);
+
+    expect(screen.getByText("Counter: 0")).toBeInTheDocument();
+  });
+
+  describe("on increment", () => {
+    it("should increase by 1", async () => {
+      await render(<Counter onChange$={onChangeMock} />);
+
+      const incrementBtn = screen.getByRole("button", { name: "Increment" });
+      await userEvent.click(incrementBtn);
+
+      await waitFor(() =>
+        expect(screen.getByText("Counter: 1")).toBeInTheDocument(),
+      );
+    });
+
+    it("should call onChange$", async () => {
+      await render(<Counter onChange$={onChangeMock} />);
+
+      const incrementBtn = screen.getByRole("button", { name: "Increment" });
+      await userEvent.click(incrementBtn);
+
+      await waitFor(() =>
+        expect(onChangeMock.resolve()).resolves.toHaveBeenCalledWith(1),
+      );
+    });
+  });
+
+  describe("on decrement", () => {
+    it("should decrease by 1", async () => {
+      await render(<Counter onChange$={onChangeMock} />);
+
+      const decrementBtn = screen.getByRole("button", { name: "Decrement" });
+      await userEvent.click(decrementBtn);
+
+      await waitFor(() =>
+        expect(screen.getByText("Counter: -1")).toBeInTheDocument(),
+      );
+    });
+
+    it("should call onChange$", async () => {
+      await render(<Counter onChange$={onChangeMock} />);
+
+      const decrementBtn = screen.getByRole("button", { name: "Decrement" });
+      await userEvent.click(decrementBtn);
+
+      await waitFor(() =>
+        expect(onChangeMock.resolve()).resolves.toHaveBeenCalledWith(-1),
+      );
+    });
+  });
+});

apps/qwik-testing-library-e2e-tests/src/components/counter.tsx

@@ -0,0 +1,27 @@
+import { $, component$, QRL, useSignal } from "@builder.io/qwik";
+
+interface CounterProps {
+  onChange$: QRL<(value: number) => void>;
+}
+
+export const Counter = component$<CounterProps>(({ onChange$ }) => {
+  const count = useSignal(0);
+
+  const handleIncrement = $(() => {
+    count.value++;
+    return onChange$(count.value);
+  });
+
+  const handleDecrement = $(() => {
+    count.value--;
+    return onChange$(count.value);
+  });
+
+  return (
+    <div>
+      <h1>Counter: {count}</h1>
+      <button onClick$={handleIncrement}>Increment</button>
+      <button onClick$={handleDecrement}>Decrement</button>
+    </div>
+  );
+});

apps/qwik-testing-library-e2e-tests/src/components/qwik-component.spec.tsx

@@ -1,7 +1,6 @@
 import { QwikComponent } from "./qwik-component";
 import { render, screen, waitFor } from "@noma.to/qwik-testing-library";
 import userEvent from "@testing-library/user-event";
-import { Mock } from "vitest";
 
 describe("<QwikComponent />", () => {
   const aProp = "my-prop";
@@ -209,31 +208,6 @@ describe("<QwikComponent />", () => {
     });
   });
 
-  describe("Events", () => {
-    let firstEvent: Mock;
-    let secondEvent: Mock;
-
-    beforeEach(() => {
-      firstEvent = vi.fn();
-      secondEvent = vi.fn();
-    });
-
-    it("should handle multiple events", async () => {
-      await render(
-        // eslint-disable-next-line qwik/valid-lexical-scope
-        <QwikComponent onFirst$={firstEvent} onSecond$={secondEvent} />,
-      );
-
-      const eventsBtn = screen.getByRole("button", {
-        name: /fire events/,
-      });
-      await userEvent.click(eventsBtn);
-
-      expect(firstEvent).toHaveBeenCalledTimes(1);
-      expect(secondEvent).toHaveBeenCalledTimes(1);
-    });
-  });
-
   describe("Tasks", () => {
     const trackedTaskValue = "tracked-task-value";
 

packages/qwik-testing-library/package.json

@@ -46,6 +46,7 @@
     "typescript": "5.6.2",
     "undici": "*",
     "vite": "5.4.8",
-    "vite-tsconfig-paths": "^5.0.1"
+    "vite-tsconfig-paths": "^5.0.1",
+    "vitest": "^2.1.1"
   }
 }

packages/qwik-testing-library/src/lib/mock.ts

@@ -0,0 +1,43 @@
+import { $, implicit$FirstArg } from "@builder.io/qwik";
+import { vi } from "vitest";
+
+export const mockQrl = () => {
+  return $(vi.fn());
+};
+
+/**
+ * @experimental
+ *
+ * Create a QRL mock that can be used in tests to verify interactions
+ *
+ * As Qwik is an async framework, you need to `resolve()` the mock before making your verifications.
+ * And remember to clear the mocks before each test to start with a clean slate!
+ *
+ * @example
+ * ```tsx
+ * describe('<MyButton />', () => {
+ *   const onClickMock = mock$(() => {});
+ *
+ *   beforeEach(() => {
+ *     clearAllMocks();
+ *   });
+ *
+ *   it('should call onClick$', async () => {
+ *     await render(<MyButton onClick$={onClickMock} />);
+ *
+ *     await userEvent.click(screen.getByRole('button'));
+ *
+ *     await waitFor(() => expect(onClickMock.resolve()).resolves.toHaveBeenCalled());
+ *   });
+ * });
+ * ```
+ */
+export const mock$ = implicit$FirstArg(mockQrl);
+
+/**
+ * Will call `.mockClear()` on all spies. This will clear mock history, but not reset its implementation to the
+ * default one.
+ */
+export function clearAllMocks() {
+  vi.clearAllMocks();
+}

packages/qwik-testing-library/src/lib/qwik-testing-library.tsx

@@ -2,6 +2,7 @@ import { getQueriesForElement, prettyDOM } from "@testing-library/dom";
 import { JSXOutput } from "@builder.io/qwik";
 import type { ComponentRef, Options, Result } from "./types";
 import { qwikLoader } from "./qwikloader";
+import { clearAllMocks, mock$, mockQrl } from "./mock";
 
 const mountedContainers = new Set<ComponentRef>();
 
@@ -74,4 +75,4 @@ function cleanup() {
 }
 
 export * from "@testing-library/dom";
-export { cleanup, render };
+export { cleanup, render, mock$, mockQrl, clearAllMocks };