karma-qunit

karma-qunit is a Karma plugin that provides an adapter for the QUnit testing framework. It enables seamless integration between Karma test runner and QUnit test suites by automatically configuring QUnit files, providing configuration options, and establishing the bridge between QUnit test execution and Karma's reporting system.

Package Information

• Package Name: karma-qunit
• Package Type: npm
• Language: JavaScript
• Installation: npm install karma-qunit --save-dev

Core Imports

karma-qunit is not imported directly in your code. Instead, it's configured as a Karma plugin:

// karma.conf.js
module.exports = function (config) {
  config.set({
    frameworks: ['qunit'],
    plugins: ['karma-qunit']
  });
};

If requiring the plugin programmatically:

const karmaQunit = require('karma-qunit');

Basic Usage

// karma.conf.js
module.exports = function (config) {
  config.set({
    frameworks: ['qunit'],
    plugins: ['karma-qunit'],
    files: [
      'src/**/*.js',
      'test/**/*.js'
    ],
    browsers: ['Chrome']
  });
};

With QUnit configuration options:

// karma.conf.js  
module.exports = function (config) {
  config.set({
    frameworks: ['qunit'],
    plugins: ['karma-qunit'],
    files: ['test/**/*.js'],
    client: {
      clearContext: false,
      qunit: {
        showUI: true,
        testTimeout: 5000,
        autostart: true
      }
    }
  });
};

Capabilities

Karma Framework Registration

karma-qunit registers itself as a Karma framework plugin that can be activated by including 'qunit' in the frameworks array.

/**
 * Main module export providing Karma framework factory
 */
module.exports = {
  'framework:qunit': ['factory', initQUnit]
};

QUnit Framework Initialization

Initializes the QUnit framework by adding necessary files to Karma's file list.

/**
 * Initializes QUnit framework for Karma
 * Automatically adds QUnit CSS, JavaScript library, and adapter files
 * @param {Array} files - Karma files array to modify
 */
function initQUnit(files);

/**
 * Dependency injection annotation for Karma framework
 * Specifies that initQUnit function requires config.files parameter
 */
initQUnit.$inject = ['config.files'];

File Pattern Creation

Internal utility for creating Karma file pattern objects.

/**
 * Creates a Karma file pattern object with default settings
 * @param {string} pattern - File path pattern
 * @returns {FilePattern} File pattern object with properties: pattern, included, served, watched
 */
function createPattern(pattern);

/** File pattern object returned by createPattern */
interface FilePattern {
  pattern: string;
  included: boolean;
  served: boolean;
  watched: boolean;
}

Configuration Options

QUnit Configuration (client.qunit)

All QUnit configuration options can be passed through Karma's client configuration:

interface QUnitClientConfig {
  /** Display QUnit UI in browser (requires clearContext: false) */
  showUI?: boolean;
  /** Control automatic test execution start */
  autostart?: boolean;
  /** Test timeout in milliseconds */
  testTimeout?: number;
  /** Any other QUnit.config option */
  [key: string]: any;
}

Common Configuration Options:

• showUI (boolean): Shows QUnit UI in the browser. Requires clearContext: false in Karma config.
• autostart (boolean): Controls whether QUnit starts automatically. Default: true.
• testTimeout (number): Test timeout in milliseconds.
• Any QUnit.config option: All options from QUnit.config are supported.

Usage Example:

// karma.conf.js
module.exports = function (config) {
  config.set({
    frameworks: ['qunit'],
    plugins: ['karma-qunit'],
    client: {
      clearContext: false, // Required for showUI
      qunit: {
        showUI: true,
        testTimeout: 10000,
        autostart: false, // Manual start control
        reorder: false,   // QUnit config option
        altertitle: false // QUnit config option
      }
    }
  });
};

Architecture

karma-qunit consists of several key components:

• Plugin Registration: Registers as a Karma framework plugin via factory pattern
• File Management: Automatically includes QUnit CSS, JavaScript, and adapter files
• Configuration Bridge: Passes Karma client configuration to QUnit
• Test Adapter: Bridges QUnit test execution with Karma reporting system
• DOM Integration: Manages QUnit fixture elements and optional UI display

The adapter creates a wrapper around QUnit that:

• Intercepts QUnit test lifecycle events (begin, testStart, log, testDone, done)
• Translates QUnit test results to Karma's expected format
• Handles test timing, error collection, and coverage reporting
• Manages DOM fixtures and UI elements

Browser Integration

The adapter establishes the following browser-level integrations:

QUnit Configuration Setup

/**
 * Creates QUnit configuration from Karma config
 * @param {Object} karma - Karma instance with config property
 * @returns {Object} QUnit configuration object with autostart: false and merged options
 */
function createQUnitConfig(karma);

Test Execution Control

/**
 * Creates QUnit start function for Karma integration
 * @param {Object} tc - Karma test context
 * @param {Object} runnerPassedIn - Optional QUnit runner instance (defaults to window.QUnit)
 * @returns {Function} Function that initializes QUnit test execution within Karma
 */
function createQUnitStartFn(tc, runnerPassedIn);

Automatic File Inclusion

karma-qunit automatically includes these files in your Karma configuration:

1. qunit/qunit/qunit.css - QUnit CSS styles
2. qunit - QUnit JavaScript library (resolved via require.resolve('qunit'))
3. lib/adapter.js - karma-qunit adapter for browser integration

Dependencies

Peer Dependencies

{
  "karma": "^4.0.0 || ^5.0.0 || ^6.0.0",
  "qunit": ">=2.1.1"
}

Runtime Dependencies

karma-qunit has zero runtime dependencies, making it lightweight and avoiding version conflicts.

Error Handling

The adapter captures and formats QUnit test failures:

• Test Assertions: Failed assertions are captured with expected/actual values
• Error Messages: Detailed error messages including source location when available
• Exception Handling: JavaScript exceptions in tests are properly reported
• Global Failures: Global failures are filtered out to avoid duplicate reporting

Test results include:

• Test description and module/suite information
• Success/failure status and skip indicators
• Detailed error logs with expected vs actual comparisons
• Execution timing information

Coverage Integration

karma-qunit automatically collects code coverage data when available:

// Coverage data is automatically included in test completion
tc.complete({
  coverage: window.__coverage__
});

This integrates with coverage tools like Istanbul/nyc when configured in your Karma setup.