Skip to main content

Setup

The easiest way to get started with Qwik Testing Library is to use the Qwik CLI that comes with your Qwik project to automatically set it up for you:

npm run qwik add testing-library

If you prefer to set it up manually or want to understand what the setup script does, read along...

Manual Setup​

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

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