• The Problem
• This Solution
• Installation
• Setup
• Examples
  • Qwikstart
  • Mocking Component Callbacks (experimental)
  • Qwik City - server$ calls
• Gotchas
• Issues
  • 🐛 Bugs
  • 💡 Feature Requests
  • ❓ Questions
• Contributors
• Acknowledgements

You want to write maintainable tests for your Qwik components.

@noma.to/qwik-testing-library is a lightweight library for testing Qwik components. It provides functions on top of qwik and @testing-library/dom so you can mount Qwik components and query their rendered output in the DOM. Its primary guiding principle is:

The more your tests resemble the way your software is used, the more confidence they can give you.

This module is distributed via npm which is bundled with node and should be installed as one of your project's devDependencies:

npm install --save-dev @noma.to/qwik-testing-library @testing-library/dom

This library supports qwik versions 1.7.2 and above and @testing-library/dom versions 10.1.0 and above.

You may also be interested in installing @testing-library/jest-dom and @testing-library/user-event so you can use the custom jest matchers and the user event library to test interactions with the DOM.

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 is tested with both jsdom and happy-dom:

npm install --save-dev jsdom # or npm install --save-dev happy-dom

We recommend using @noma.to/qwik-testing-library with Vitest as your test runner.

If you haven't done so already, add vitest to your project using Qwik CLI:

npm run 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:

// 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", // or "happy-dom" setupFiles: ["./vitest.setup.ts"], globals: true, }, }), ), );

For now, qwik-testing-library needs to consider your project as a lib (PR welcomed 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:

// ./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:

// vitest.setup.ts // Configure DOM matchers to work in Vitest import "@testing-library/jest-dom/vitest"; // This has to run before qdev.ts loads. `beforeAll` is too late globalThis.qTest = false; // Forces Qwik to run as if it was in a Browser globalThis.qRuntimeQrl = true; globalThis.qDev = true; globalThis.qInspector = false;

This setup will make sure that Qwik is properly configured. It also loads @testing-library/jest-dom/vitest in your test runner so you can use matchers like expect(...).toBeInTheDocument().

By default, Qwik Testing Library cleans everything up automatically for you. You can opt out of this by setting the environment variable QTL_SKIP_AUTO_CLEANUP to true. Then in your tests, you can call the cleanup function when needed. For example:

import {cleanup} from "@noma.to/qwik-testing-library"; import {afterEach} from "vitest"; afterEach(cleanup);

Finally, edit your tsconfig.json to declare the following global types:

// tsconfig.json { "compilerOptions": { "types": [ + "vite/client", + "vitest/globals", + "@testing-library/jest-dom/vitest" ] }, "include": ["src"] }

Below are some examples of how to use @noma.to/qwik-testing-library to tests your Qwik components.

You can also learn more about the queries and user events over at the Testing Library website.

This is a minimal setup to get you started, with line-by-line explanations.

// counter.spec.tsx // 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"; // describe the test suite describe("<Counter />", () => { // describe the test case it("should increment the counter", async () => { // setup user event const user = userEvent.setup(); // render the component into the DOM await render(<Counter/>); // retrieve the 'increment count' button const incrementBtn = screen.getByRole("button", {name: /increment count/}); // click the button twice await user.click(incrementBtn); await user.click(incrementBtn); // assert that the counter is now 2 await waitFor(() => expect(screen.findByText(/count:2/)).toBeInTheDocument()); }); })

Optionally, you can install @noma.to/qwik-mock to mock callbacks of Qwik components. It provides a mock$ function that can be used to create a mock of a QRL and verify interactions on your Qwik components.

npm install --save-dev @noma.to/qwik-mock

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:

// import qwik-testing methods import {render, screen, waitFor} from "@noma.to/qwik-testing-library"; // import qwik-mock methods import {mock$, clearAllMock} from "@noma.to/qwik-mock"; // 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 () => { // setup user event const user = userEvent.setup(); // 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 user.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), ); }); }); })

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, 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:

// ~/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([]); });

// ~/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 function doesn't end with $, the Qwik optimizer will not rename it to Qrl.

• Watch mode (at least in Webstorm) doesn't seem to work well: components are not being updated with your latest changes

Looking to contribute? Look for the Good First Issue label.

Please file an issue for bugs, missing documentation, or unexpected behavior.

See Bugs

Please file an issue to suggest new features. Vote on feature requests by adding a 👍. This helps maintainers prioritize what to work on.

See Feature Requests

For questions related to using the library, please visit a support community instead of filing an issue on GitHub.

• Discord
• Stack Overflow

Thanks goes to these people (emoji key):

Ian Létourneau 💻 ⚠️ 🤔 📖 💡	Brandon Pittman 📖	Jack Shelton 👀
Add your contributions

This project follows the all-contributors specification. Contributions of any kind welcome!

Massive thanks to the Qwik Team and the whole community for their efforts to build Qwik and for the inspiration on how to create a testing library for Qwik.

Thanks to the Testing Library Team for a great set of tools to build better products, confidently, and qwikly.