Karma QUnit Adapter

4.2.1 · active · verified Sun Apr 19

karma-qunit is a plugin for the Karma test runner that provides an adapter for integrating QUnit, a popular JavaScript unit testing framework. This package allows developers to run their QUnit tests within the Karma environment, facilitating automated testing across various browsers and environments. The current stable version is 4.2.1. Releases appear to be driven by bug fixes and compatibility updates with new Karma or QUnit versions, rather than a fixed cadence, often with several minor releases and occasional major updates. Key differentiators include its tight integration with Karma's robust browser launching and reporting capabilities, offering a more flexible and powerful testing setup compared to running QUnit tests directly in a browser without a test runner. It handles the setup and teardown required for QUnit tests within Karma's lifecycle. While many modern projects lean towards frameworks like Jest or Vitest, karma-qunit remains relevant for projects using QUnit, particularly those with existing Karma test setups or legacy codebases.

Common errors

```
Error: Cannot find module 'karma-qunit'
```
cause The `karma-qunit` package was not installed or is not correctly resolved by Node.js/Karma.

fix Run `npm install --save-dev karma-qunit` to install the package.
```
TypeError: Cannot read properties of undefined (reading 'qunit') OR Unknown plugin: 'karma-qunit'
```
cause The `karma-qunit` plugin is not correctly listed in the `plugins` array of `karma.conf.js`.

fix Add `plugins: ['karma-qunit']` to your `karma.conf.js`.
```
Error: Unknown framework: 'qunit'
```
cause The `qunit` framework is not correctly listed in the `frameworks` array of `karma.conf.js`.

fix Add `frameworks: ['qunit']` to your `karma.conf.js`.

Warnings

gotcha When enabling `showUI: true` for QUnit, the `clearContext: false` option in the Karma client configuration must also be set. Failing to do so will prevent the QUnit UI from displaying correctly in non-debug mode within the browser.
Fix: Ensure your `karma.conf.js` includes `client: { clearContext: false, qunit: { showUI: true } }`.
breaking Major versions of `karma-qunit` may introduce breaking changes related to compatibility with new `karma` or `qunit` versions. Always check the release notes when upgrading peer dependencies or `karma-qunit` itself.
Fix: Consult the `karma-qunit` GitHub release notes or changelog for specific migration steps when upgrading across major versions. Update `karma` and `qunit` peer dependencies to compatible versions as specified.
gotcha The `karma-qunit` package is primarily a Karma plugin, not a direct JavaScript library for import. You configure it within your `karma.conf.js` file rather than importing symbols into your test files or application code.
Fix: Ensure `karma-qunit` is installed as a dev dependency (`npm install --save-dev karma-qunit`) and configured in `karma.conf.js` using `frameworks: ['qunit']` and `plugins: ['karma-qunit']`.

Install

npm install karma-qunit npm
yarn add karma-qunit yarn
pnpm add karma-qunit pnpm

Imports

frameworks
wrong:
```
frameworks: ['karma-qunit']
```
correct:
```
frameworks: ['qunit']
```
The 'qunit' string is used in the `frameworks` array in `karma.conf.js` to enable the plugin.
plugins
wrong:
```
plugins: [require('karma-qunit')]
```
correct:
```
plugins: ['karma-qunit']
```
The string identifier 'karma-qunit' is used directly in the `plugins` array for Karma to load the plugin.
client.qunit options
wrong:
```
qunit: { showUI: true }
```
correct:
```
client: { qunit: { showUI: true } }
```
QUnit configuration options are passed via the `client` object in `karma.conf.js` under the `qunit` key, not directly at the root.

Quickstart

This quickstart demonstrates a basic Karma configuration (`karma.conf.js`) for running QUnit tests, including how to enable the `karma-qunit` plugin, specify test files, and pass custom QUnit configuration options via the `client` property. It also includes the crucial `clearContext: false` for proper UI display.

const path = require('path');

module.exports = function (config) {
  config.set({
    basePath: '',
    frameworks: ['qunit'],
    plugins: ['karma-qunit'],
    files: [
      // Your QUnit test files
      'test/**/*.js',
      // Optional: QUnit library itself if not globally available, though karma-qunit often handles it
      // path.resolve(__dirname, 'node_modules/qunit/qunit/qunit.js')
    ],
    exclude: [],
    preprocessors: {},
    reporters: ['progress'],
    port: 9876,
    colors: true,
    logLevel: config.LOG_INFO,
    autoWatch: true,
    browsers: ['Chrome'],
    singleRun: false,
    concurrency: Infinity,
    client: {
      clearContext: false, // Recommended for showUI: true
      qunit: {
        showUI: true,
        testTimeout: 5000, // Example QUnit config option
        filter: 'my-module:*' // Another example
      }
    }
  })
}

view raw JSON →