@noma.to/qwik-testing-library 1.0.2 → 1.0.4

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,13 @@ src="https://raw.githubusercontent.com/ianlet/qwik-testing-library/main/high-vol
 - [Installation](#installation)
 - [Setup](#setup)
 - [Examples](#examples)
-  - [Qwikstart](#qwikstart)
+    - [Qwikstart](#qwikstart)
+    - [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,8 +132,19 @@ 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
-use [the custom jest matchers][jest-dom].
+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
+npm install --save-dev @testing-library/jest-dom @testing-library/user-event
+```
+
+Finally, we need a DOM environment to run the tests in.
+This library was tested (for now) only with `jsdom` so we recommend using it:
+
+```shell
+npm install --save-dev jsdom
+```
 
 [npm]: https://www.npmjs.com/
 
@@ -140,22 +152,67 @@ use [the custom jest matchers][jest-dom].
 
 [jest-dom]: https://github.com/testing-library/jest-dom
 
+[user-event]: https://github.com/testing-library/user-event
+
 ## Setup
 
 We recommend using `@noma.to/qwik-testing-library` with [Vitest][] as your test
-runner. To get started, configure how Vite will run your tests.
+runner.
 
-```diff
-  // vite.config.js
-
-  export default defineConfig({
-    plugins: [qwikVite(), tsconfigPaths()],
-+   test: {
-+     environment: "jsdom",
-+     setupFiles: ["./vitest.setup.ts"],
-+     globals: true,
-+   },
-  });
+If you haven't done so already, add vitest to your project using Qwik CLI:
+
+```shell
+npm qwik add vitest
+```
+
+After that, we need to configure Vitest so it can run your tests.
+For this, create a _separate_ `vitest.config.ts` so you don't have to modify your project's `vite.config.ts`:
+
+```ts
+// vitest.config.ts
+
+import {defineConfig, mergeConfig} from "vitest/config";
+import viteConfig from "./vite.config";
+
+export default defineConfig((configEnv) =>
+  mergeConfig(
+    viteConfig(configEnv),
+    defineConfig({
+      // qwik-testing-library needs to consider your project as a Qwik lib
+      // if it's already a Qwik lib, you can remove this section
+      build: {
+        target: "es2020",
+        lib: {
+          entry: "./src/index.ts",
+          formats: ["es", "cjs"],
+          fileName: (format, entryName) =>
+            `${entryName}.qwik.${format === "es" ? "mjs" : "cjs"}`,
+        },
+      },
+      // configure your test environment
+      test: {
+        environment: "jsdom",
+        setupFiles: ["./vitest.setup.ts"],
+        globals: true,
+      },
+    }),
+  ),
+);
+```
+
+For now, `qwik-testing-library` needs to consider your project as a lib ([PR welcomed][prs] to simplify this).
+Hence, the `build.lib` section in the config above.
+
+As the build will try to use `./src/index.ts` as the entry point, we need to create it:
+
+```ts
+// ./src/index.ts
+
+/**
+ * DO NOT DELETE THIS FILE
+ *
+ * This entrypoint is needed by @noma.to/qwik-testing-library to run your tests
+ */
 ```
 
 Then, create the `vitest.setup.ts` file:
@@ -238,12 +295,63 @@ 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());
   });
 })
 ```
 
+### 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/package.json

@@ -1,9 +1,10 @@
 {
   "name": "@noma.to/qwik-testing-library",
-  "version": "1.0.2",
+  "version": "1.0.4",
   "description": "Simple and complete Qwik testing utilities that encourage good testing practices.",
   "repository": "https://github.com/ianlet/qwik-testing-library",
   "homepage": "https://github.com/ianlet/qwik-testing-library",
+  "license": "MIT",
   "main": "./lib/index.qwik.mjs",
   "qwik": "./lib/index.qwik.mjs",
   "types": "./lib-types/index.d.ts",
@@ -36,15 +37,15 @@
     "@builder.io/qwik": "1.9.0",
     "@testing-library/dom": "^10.4.0",
     "@types/eslint": "8.56.10",
-    "@types/node": "20.14.11",
-    "@typescript-eslint/eslint-plugin": "7.16.1",
-    "@typescript-eslint/parser": "7.16.1",
-    "eslint": "8.57.0",
+    "@types/node": "22.7.4",
+    "@typescript-eslint/eslint-plugin": "8.7.0",
+    "@typescript-eslint/parser": "8.7.0",
+    "eslint": "8.57.1",
     "eslint-plugin-qwik": "1.9.0",
     "prettier": "3.3.3",
-    "typescript": "5.4.5",
+    "typescript": "5.6.2",
     "undici": "*",
-    "vite": "5.3.5",
-    "vite-tsconfig-paths": "^4.2.1"
+    "vite": "5.4.8",
+    "vite-tsconfig-paths": "^5.0.1"
   }
 }