@noma.to/qwik-testing-library 1.0.3 → 1.1.0

package/README.md

@@ -37,7 +37,7 @@ src="https://raw.githubusercontent.com/ianlet/qwik-testing-library/main/high-vol
 
 [qtl-docs-repo]: https://github.com/ianlet/qwik-testing-library/blob/main/README.md
 
-[build-badge]: https://img.shields.io/github/actions/workflow/status/ianlet/qwik-testing-library/release.yml?style=flat-square
+[build-badge]: https://img.shields.io/github/actions/workflow/status/ianlet/qwik-testing-library/ci.yml?style=flat-square
 
 [build]: https://github.com/ianlet/qwik-testing-library/actions
 
@@ -91,12 +91,14 @@ src="https://raw.githubusercontent.com/ianlet/qwik-testing-library/main/high-vol
 - [Installation](#installation)
 - [Setup](#setup)
 - [Examples](#examples)
-  - [Qwikstart](#qwikstart)
+    - [Qwikstart](#qwikstart)
+    - [Mocking Component Callbacks (experimental)](#mocking-component-callbacks-experimental)
+    - [Qwik City - `server$` calls](#qwik-city---server-calls)
 - [Gotchas](#gotchas)
 - [Issues](#issues)
-  - [🐛 Bugs](#-bugs)
-  - [💡 Feature Requests](#-feature-requests)
-  - [❓ Questions](#-questions)
+    - [🐛 Bugs](#-bugs)
+    - [💡 Feature Requests](#-feature-requests)
+    - [❓ Questions](#-questions)
 - [Contributors](#contributors)
 - [Acknowledgements](#acknowledgements)
 
@@ -131,7 +133,7 @@ npm install --save-dev @noma.to/qwik-testing-library
 
 This library supports `qwik` versions `1.7.2` and above.
 
-You may also be interested in installing `@testing-library/jest-dom` so you can
+You may also be interested in installing `@testing-library/jest-dom` and `@testing-library/user-event` so you can
 use [the custom jest matchers][jest-dom] and [the user event library][user-event] to test interactions with the DOM.
 
 ```shell
@@ -278,6 +280,8 @@ This is a minimal setup to get you started, with line-by-line explanations.
 
 // import qwik-testing methods
 import {screen, render, 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";
 
@@ -294,12 +298,121 @@ describe("<Counter />", () => {
     await userEvent.click(incrementBtn);
     await userEvent.click(incrementBtn);
 
-    // assert that the counter is now 1
+    // assert that the counter is now 2
     await waitFor(() => expect(screen.getByText(/count:2/)).toBeInTheDocument());
   });
 })
 ```
 
+### 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
+ERROR __vite_ssr_import_0__.myServerFunctionQrl is not a function` or
+`QWIK ERROR Failed to parse URL from ?qfunc=DNpotUma33o`).
+
+We're happy to discuss it on [Discord][discord], but we consider this failure to be a good thing:
+your components should be tested in isolation, so you will be forced to mock your server functions.
+
+Here is an example of how to test a component that uses `server$` calls:
+
+```ts
+// ~/server/blog-posts.ts
+
+import {server$} from "@builder.io/qwik-city";
+import {BlogPost} from "~/lib/blog-post";
+
+export const getLatestPosts$ = server$(function (): Promise<BlogPost> {
+  // get the latest posts
+  return Promise.resolve([]);
+});
+```
+
+```tsx
+// ~/components/latest-post-list.spec.tsx
+
+import {render, screen, waitFor} from "@noma.to/qwik-testing-library";
+import {LatestPostList} from "./latest-post-list";
+
+vi.mock('~/server/blog-posts', () => ({
+  // the mocked function should end with `Qrl` instead of `$`
+  getLatestPostsQrl: () => {
+    return Promise.resolve([{id: 'post-1', title: 'Post 1'}, {id: 'post-2', title: 'Post 2'}]);
+  },
+}));
+
+describe('<LatestPostList />', () => {
+  it('should render the latest posts', async () => {
+    await render(<LatestPostList/>);
+
+    await waitFor(() => expect(screen.queryAllByRole('listitem')).toHaveLength(2));
+  });
+});
+```
+
+Notice how the mocked function is ending with `Qrl` instead of `$`, despite being named as `getLatestPosts$`.
+This is caused by the Qwik optimizer renaming it to `Qrl`.
+So, we need to mock the `Qrl` function instead of the original `$` one.
+
+If your `server$` function doesn't end with `$`, the Qwik optimizer might not rename it to `Qrl`.
+
 ## Gotchas
 
 * Watch mode (at least in Webstorm) doesn't seem to work well: components are not being updated with your latest changes

package/lib/_virtual/_commonjsHelpers.qwik.cjs

@@ -1,6 +1,8 @@
 "use strict";
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+var commonjsGlobal = typeof globalThis !== "undefined" ? globalThis : typeof window !== "undefined" ? window : typeof global !== "undefined" ? global : typeof self !== "undefined" ? self : {};
 function getDefaultExportFromCjs(x) {
   return x && x.__esModule && Object.prototype.hasOwnProperty.call(x, "default") ? x["default"] : x;
 }
+exports.commonjsGlobal = commonjsGlobal;
 exports.getDefaultExportFromCjs = getDefaultExportFromCjs;

package/lib/_virtual/_commonjsHelpers.qwik.mjs

@@ -1,6 +1,8 @@
+var commonjsGlobal = typeof globalThis !== "undefined" ? globalThis : typeof window !== "undefined" ? window : typeof global !== "undefined" ? global : typeof self !== "undefined" ? self : {};
 function getDefaultExportFromCjs(x) {
   return x && x.__esModule && Object.prototype.hasOwnProperty.call(x, "default") ? x["default"] : x;
 }
 export {
+  commonjsGlobal,
   getDefaultExportFromCjs
 };

package/lib/_virtual/sourcemap-codec.umd.qwik.cjs

@@ -0,0 +1,4 @@
+"use strict";
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+var sourcemapCodec_umd = { exports: {} };
+exports.__module = sourcemapCodec_umd;

package/lib/_virtual/sourcemap-codec.umd.qwik.mjs

@@ -0,0 +1,4 @@
+var sourcemapCodec_umd = { exports: {} };
+export {
+  sourcemapCodec_umd as __module
+};

package/lib/index.qwik.cjs

@@ -3,6 +3,7 @@ Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 const qwikTestingLibrary = require("./lib/qwik-testing-library.qwik.cjs");
 const index = require("./node_modules/.pnpm/pretty-format@27.5.1/node_modules/pretty-format/build/index.qwik.cjs");
 const dom_esm = require("./node_modules/.pnpm/@testing-library_dom@10.4.0/node_modules/@testing-library/dom/dist/@testing-library/dom.esm.qwik.cjs");
+const mock = require("./lib/mock.qwik.cjs");
 exports.cleanup = qwikTestingLibrary.cleanup;
 exports.render = qwikTestingLibrary.render;
 exports.prettyFormat = index;
@@ -83,3 +84,6 @@ exports.waitForElementToBeRemoved = dom_esm.waitForElementToBeRemoved;
 exports.within = dom_esm.getQueriesForElement;
 exports.wrapAllByQueryWithSuggestion = dom_esm.wrapAllByQueryWithSuggestion;
 exports.wrapSingleQueryWithSuggestion = dom_esm.wrapSingleQueryWithSuggestion;
+exports.clearAllMocks = mock.clearAllMocks;
+exports.mock$ = mock.mock$;
+exports.mockQrl = mock.mockQrl;

package/lib/index.qwik.mjs

@@ -1,9 +1,11 @@
 import { cleanup, render } from "./lib/qwik-testing-library.qwik.mjs";
 import * as index from "./node_modules/.pnpm/pretty-format@27.5.1/node_modules/pretty-format/build/index.qwik.mjs";
 import { buildQueries, configure, createEvent, findAllByAltText, findAllByDisplayValue, findAllByLabelText, findAllByPlaceholderText, findAllByRole, findAllByTestId, findAllByText, findAllByTitle, findByAltText, findByDisplayValue, findByLabelText, findByPlaceholderText, findByRole, findByTestId, findByText, findByTitle, fireEvent, getAllByAltText, getAllByDisplayValue, getAllByLabelText, getAllByPlaceholderText, getAllByRole, getAllByTestId, getAllByText, getAllByTitle, getByAltText, getByDisplayValue, getByLabelText, getByPlaceholderText, getByRole, getByTestId, getByText, getByTitle, getConfig, getDefaultNormalizer, getElementError, getMultipleElementsFoundError, getNodeText, getQueriesForElement, getRoles, getSuggestedQuery, isInaccessible, logDOM, logRoles, makeFindQuery, makeGetAllQuery, makeSingleQuery, prettyDOM, queries, queryAllByAltText, queryAllByAttribute, queryAllByDisplayValue, queryAllByLabelText, queryAllByPlaceholderText, queryAllByRole, queryAllByTestId, queryAllByText, queryAllByTitle, queryByAltText, queryByAttribute, queryByDisplayValue, queryByLabelText, queryByPlaceholderText, queryByRole, queryByTestId, queryByText, queryByTitle, queryHelpers, screen, waitFor, waitForElementToBeRemoved, getQueriesForElement as getQueriesForElement2, wrapAllByQueryWithSuggestion, wrapSingleQueryWithSuggestion } from "./node_modules/.pnpm/@testing-library_dom@10.4.0/node_modules/@testing-library/dom/dist/@testing-library/dom.esm.qwik.mjs";
+import { clearAllMocks, mock$, mockQrl } from "./lib/mock.qwik.mjs";
 export {
   buildQueries,
   cleanup,
+  clearAllMocks,
   configure,
   createEvent,
   findAllByAltText,
@@ -53,6 +55,8 @@ export {
   makeFindQuery,
   makeGetAllQuery,
   makeSingleQuery,
+  mock$,
+  mockQrl,
   prettyDOM,
   index as prettyFormat,
   queries,

package/lib/lib/mock.qwik.cjs

@@ -0,0 +1,14 @@
+"use strict";
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const qwik = require("@builder.io/qwik");
+const vi_D6IHiKAI = require("../node_modules/.pnpm/vitest@2.1.1_@types_node@22.7.4_@vitest_ui@2.1.1_jsdom@25.0.1/node_modules/vitest/dist/chunks/vi.D6IHiKAI.qwik.cjs");
+const mockQrl = () => {
+  return qwik.$(vi_D6IHiKAI.v.fn());
+};
+const mock$ = qwik.implicit$FirstArg(mockQrl);
+function clearAllMocks() {
+  vi_D6IHiKAI.v.clearAllMocks();
+}
+exports.clearAllMocks = clearAllMocks;
+exports.mock$ = mock$;
+exports.mockQrl = mockQrl;

package/lib/lib/mock.qwik.mjs

@@ -0,0 +1,14 @@
+import { implicit$FirstArg, $ } from "@builder.io/qwik";
+import { v as vi } from "../node_modules/.pnpm/vitest@2.1.1_@types_node@22.7.4_@vitest_ui@2.1.1_jsdom@25.0.1/node_modules/vitest/dist/chunks/vi.D6IHiKAI.qwik.mjs";
+const mockQrl = () => {
+  return $(vi.fn());
+};
+const mock$ = implicit$FirstArg(mockQrl);
+function clearAllMocks() {
+  vi.clearAllMocks();
+}
+export {
+  clearAllMocks,
+  mock$,
+  mockQrl
+};

package/lib/lib/qwik-testing-library.qwik.cjs

@@ -25,6 +25,7 @@ Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 const jsxRuntime = require("@builder.io/qwik/jsx-runtime");
 const dom_esm = require("../node_modules/.pnpm/@testing-library_dom@10.4.0/node_modules/@testing-library/dom/dist/@testing-library/dom.esm.qwik.cjs");
 const qwikloader = require("./qwikloader.qwik.cjs");
+const mock = require("./mock.qwik.cjs");
 const mountedContainers = /* @__PURE__ */ new Set();
 async function render(ui, options = {}) {
   const qwik = await import("@builder.io/qwik");
@@ -155,5 +156,8 @@ exports.waitForElementToBeRemoved = dom_esm.waitForElementToBeRemoved;
 exports.within = dom_esm.getQueriesForElement;
 exports.wrapAllByQueryWithSuggestion = dom_esm.wrapAllByQueryWithSuggestion;
 exports.wrapSingleQueryWithSuggestion = dom_esm.wrapSingleQueryWithSuggestion;
+exports.clearAllMocks = mock.clearAllMocks;
+exports.mock$ = mock.mock$;
+exports.mockQrl = mock.mockQrl;
 exports.cleanup = cleanup;
 exports.render = render;

package/lib/lib/qwik-testing-library.qwik.mjs

@@ -2,6 +2,7 @@ import { jsx } from "@builder.io/qwik/jsx-runtime";
 import { prettyDOM, getQueriesForElement } from "../node_modules/.pnpm/@testing-library_dom@10.4.0/node_modules/@testing-library/dom/dist/@testing-library/dom.esm.qwik.mjs";
 import { buildQueries, configure, createEvent, findAllByAltText, findAllByDisplayValue, findAllByLabelText, findAllByPlaceholderText, findAllByRole, findAllByTestId, findAllByText, findAllByTitle, findByAltText, findByDisplayValue, findByLabelText, findByPlaceholderText, findByRole, findByTestId, findByText, findByTitle, fireEvent, getAllByAltText, getAllByDisplayValue, getAllByLabelText, getAllByPlaceholderText, getAllByRole, getAllByTestId, getAllByText, getAllByTitle, getByAltText, getByDisplayValue, getByLabelText, getByPlaceholderText, getByRole, getByTestId, getByText, getByTitle, getConfig, getDefaultNormalizer, getElementError, getMultipleElementsFoundError, getNodeText, getRoles, getSuggestedQuery, isInaccessible, logDOM, logRoles, makeFindQuery, makeGetAllQuery, makeSingleQuery, queries, queryAllByAltText, queryAllByAttribute, queryAllByDisplayValue, queryAllByLabelText, queryAllByPlaceholderText, queryAllByRole, queryAllByTestId, queryAllByText, queryAllByTitle, queryByAltText, queryByAttribute, queryByDisplayValue, queryByLabelText, queryByPlaceholderText, queryByRole, queryByTestId, queryByText, queryByTitle, queryHelpers, screen, waitFor, waitForElementToBeRemoved, wrapAllByQueryWithSuggestion, wrapSingleQueryWithSuggestion } from "../node_modules/.pnpm/@testing-library_dom@10.4.0/node_modules/@testing-library/dom/dist/@testing-library/dom.esm.qwik.mjs";
 import { qwikLoader } from "./qwikloader.qwik.mjs";
+import { clearAllMocks, mock$, mockQrl } from "./mock.qwik.mjs";
 const mountedContainers = /* @__PURE__ */ new Set();
 async function render(ui, options = {}) {
   const qwik = await import("@builder.io/qwik");
@@ -58,6 +59,7 @@ function cleanup() {
 export {
   buildQueries,
   cleanup,
+  clearAllMocks,
   configure,
   createEvent,
   findAllByAltText,
@@ -107,6 +109,8 @@ export {
   makeFindQuery,
   makeGetAllQuery,
   makeSingleQuery,
+  mock$,
+  mockQrl,
   prettyDOM,
   queries,
   queryAllByAltText,