Read The Docs | Edit the docs

Table of Contents

• The Problem
• This Solution
• Installation
• Setup
• Examples
  • Qwikstart
  • 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.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 was tested (for now) only with jsdom so we recommend using it:

npm install --save-dev jsdom

Setup

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

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
    await waitFor(() => expect(screen.findByText(/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:

// 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 () => {
      // 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),
      );
    });
  });
})

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

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.