Setup

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

npm
Yarn

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

yarn add --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
Yarn

npm install --save-dev @testing-library/jest-dom @testing-library/user-event

yarn add --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
Yarn

npm install --save-dev jsdom

yarn add --dev jsdom

Vitest Configuration

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
Yarn

npm run qwik add vitest

yarn 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',
        setupFiles: ['./vitest.setup.ts'],
        globals: true,
      },
    }),
  ),
)

For now, qwik-testing-library needs to consider your project as a lib. 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)

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

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

Finally, you can add test scripts to your package.json to run the tests with Vitest

package.json
{
  "scripts": {
    "test": "vitest run",
    "test:ui": "vitest --ui",
    "test:watch": "vitest"
  }
}

Vitest Configuration​

Vitest Configuration