Qwik Testing Library

Simple and complete Qwik testing utilities that encourage good testing practices.

Read The Docs | Edit the docs

---

Table of Contents

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

The Problem

You want to write maintainable tests for your Qwik components.

This Solution

@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.

Installation

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.12.0 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

Setup

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

If you haven't done so already, install vitest:

npm install --save-dev vitest

After that, we need to configure Vitest so it can run your tests. Add the test section to your vite.config.ts:

// vite.config.ts

test: {
  environment: "jsdom", // or "happy-dom"
  setupFiles: [
    "@noma.to/qwik-testing-library/setup",
    "@testing-library/jest-dom/vitest", // optional, for DOM matchers
  ],
  globals: true,
},

The @noma.to/qwik-testing-library/setup module configures Qwik globals (qTest, qRuntimeQrl, qDev, qInspector) for testing. It must run before any Qwik code loads, which is why it's added to setupFiles.

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"]
}

Examples

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.

Qwikstart

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
    expect(await screen.findByText(/count:2/)).toBeInTheDocument();
  });
})

Testing Hooks (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.

renderHook lets you test custom hooks in isolation, without building a wrapper component by hand. This is especially useful for library authors who need to battle-test the hooks they provide to their users.

// use-counter.tsx

import { $, useSignal } from "@builder.io/qwik";

export function useCounter(initial = 0) {
  const count = useSignal(initial);
  const increment$ = $(() => count.value++);

  return { count, increment$ };
}

// use-counter.spec.tsx

import { renderHook } from "@noma.to/qwik-testing-library";
import { useCounter } from "./use-counter";

describe("useCounter", () => {
  it("should start at 0", async () => {
    const { result } = await renderHook(useCounter);

    expect(result.count.value).toBe(0);
  });

  it("should increment", async () => {
    const { result } = await renderHook(useCounter);

    await result.increment$();

    expect(result.count.value).toBe(1);
  });
});

The result is the direct return value of your hook callback. Because Qwik signals are stable reactive references, you can read and mutate them directly — no .current wrapper needed.

ESLint qwik/use-method-usage

The Qwik ESLint plugin only allows use* calls inside component$ or use*-named functions. This is a known limitation — a discussion is in progress with the Qwik team to relax their ESLint rule. In the meantime, when you need to pass arguments to your hook, wrap it in a use*-named function to stay lint-clean:

// passing the hook by reference — lint-clean
const { result } = await renderHook(useCounter);

// passing arguments — extract a use*-named function
function useCounterFrom10() {
  return useCounter(10);
}
const { result } = await renderHook(useCounterFrom10);

Providing Context

If your hook depends on context, use the wrapper option to provide it:

import { renderHook } from "@noma.to/qwik-testing-library";
import { component$, createContextId, useContextProvider, useStore, Slot } from "@builder.io/qwik";
import { useTheme } from "./use-theme";

const ThemeContext = createContextId<{ mode: string }>("theme");

const ThemeProvider = component$(() => {
  useContextProvider(ThemeContext, useStore({ mode: "dark" }));
  return <Slot />;
});

it("should read theme from context", async () => {
  const { result } = await renderHook(useTheme, {
    wrapper: ThemeProvider,
  });

  expect(result.mode).toBe("dark");
});

Cleanup

renderHook integrates with automatic cleanup, just like render. You can also call unmount() manually if needed:

const { result, unmount } = await renderHook(useCounter);

// ... assertions ...

unmount();

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.

Setup

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.

Usage

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 {clearAllMocks, mock$} 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
  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
      await waitFor(() =>
        expect(onChangeMock).toHaveBeenCalledWith(-1),
      );
    });
  });
})

You can also provide a default implementation to mock$:

const onSubmitMock = mock$(() => "success");

await render(<SubmitForm onSubmit$={onSubmitMock} />);
await user.click(screen.getByRole("button", { name: "Submit" }));

expect(await screen.findByText("success")).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, 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.

Gotchas

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

Issues

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

🐛 Bugs

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

See Bugs

💡 Feature Requests

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

❓ Questions

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

• Discord
• Stack Overflow

Contributors

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!

Acknowledgements

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.