Registry / testing / qunit-retry

qunit-retry

JSON →
library3.0.1jsnpmunverified

qunit-retry is a utility package for QUnit that provides a drop-in replacement for the standard `QUnit.test` function, enabling automatic retries for failing tests. This is particularly useful for handling intermittent failures in test environments, such as those caused by unreliable third-party services or network flakiness, rather than masking legitimate bugs. The current stable version is `3.0.1`. The library is actively maintained, with recent major and patch releases indicating ongoing development. Key features include the ability to configure the maximum number of retries globally or per test, support for `QUnit.test`'s full API (including `test.each` and `test.only`), and a `beforeRetry` hook to reset the testing environment between retry attempts. It distinguishes itself by seamlessly integrating into existing QUnit setups with minimal code changes, making it an efficient solution for improving test suite stability against non-deterministic external factors.

npm install qunit-retry
INSTALL
IMPORT
SIG · QUNIT-RETRY
Q
qunit-retry
testingjavascriptv3.0.1
Install
Import
Disk
Pass rate
0/ 6
Env Coverage0 / 6
glibc
1822
musl
1822
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
node 18226 runs
build_error
glibc
node 18226 runs
build_error
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

setup
import setup from 'qunit-retry';
const setup = require('qunit-retry');
The package transitioned to ESM-only starting with v3.0.0. CommonJS `require` statements will fail.
setup
import setup from 'https://unpkg.com/qunit-retry/main.js';
For direct usage in a browser without a bundler, import from the unpkg CDN path to get the ES Module version.
SetupOptions
import type { SetupOptions } from 'qunit-retry';
Type import for configuring global retry options, useful in TypeScript projects for enhanced type safety.

This quickstart demonstrates how to set up `qunit-retry` with QUnit, including global `maxRuns` configuration and a `beforeRetry` hook for resetting test state between retries. It uses a mock service to show a test failing initially but succeeding on retry.

import setup from "qunit-retry"; import QUnit from "qunit"; // QUnit is expected to be installed and configured // Simulate an occasionally failing asynchronous service let internalAttemptCount = 0; async function occasionallyFailingServiceTestResult() { internalAttemptCount++; // Simulate failure on the first attempt only if (internalAttemptCount <= 1) { console.log(`Service attempt ${internalAttemptCount}: Simulating failure.`); throw new Error("Simulated transient service error."); } console.log(`Service attempt ${internalAttemptCount}: Succeeding.`); return 42; } // Configure qunit-retry with QUnit's test function // The 'retry' function replaces QUnit.test, adding retry logic const retry = setup(QUnit.test, { // Global maxRuns: allow 1 initial attempt + 2 retries maxRuns: 3, beforeRetry: (details) => { // Reset any state needed for the test to run clean again console.log(`Retrying test "${details.name}" (attempt ${details.runNumber}/${details.maxRuns})...`); internalAttemptCount = 0; // Reset our mock service's internal state } }); // Define a test that uses the 'retry' function retry("a test relying on 3rd party service that occasionally fails", async function(assert) { assert.expect(1); // Indicate one assertion is expected const result = await occasionallyFailingServiceTestResult(); assert.equal(result, 42, "The service should eventually return 42 after retries."); }); // Example of a test that should pass without retries retry("a stable test", async function(assert) { assert.expect(1); const result = 42; // Directly successful assert.equal(result, 42, "This stable test should pass immediately."); });
Debug
Known issues
breakingVersion 3.0.0 introduced a breaking change, making `qunit-retry` an ESM-only package. CommonJS `require` statements will no longer work.
fix
Update your project to use ES Modules (e.g., `import setup from 'qunit-retry';`) and ensure your environment supports ESM. You might need to configure your `package.json` with `"type": "module"`.
affects: >=3.0.0
gotchaIt is strongly advised to use `qunit-retry` sparingly and only for truly intermittent failures (e.g., flaky external services) rather than masking actual bugs. Overuse can hide issues and increase test execution time unnecessarily.
fix
Evaluate the root cause of test failures. Only apply `qunit-retry` to tests exhibiting non-deterministic behavior due to external factors. Debug and fix deterministic failures.
affects: >=1.0.0
gotchaIf your tests modify global state, DOM, or external resources, you must implement a `beforeRetry` hook to reset the environment between retry attempts. Failure to do so can lead to inconsistent test results or 'pollution' across retries.
fix
Pass a `beforeRetry` function to the `setup` call (e.g., `setup(QUnit.test, { beforeRetry: () => resetMyEnvironment() })`) to ensure a clean slate for each retry attempt.
affects: >=2.3.0
Errors
Common errors & fixes
Error [ERR_REQUIRE_ESM]: require() of ES Module .../node_modules/qunit-retry/main.js from ... not supported.
`qunit-retry` version 3.0.0 and above are ESM-only, and cannot be imported using CommonJS `require()`.
fix
Refactor your imports to use ES Module syntax (`import setup from 'qunit-retry';`) instead of CommonJS (`const setup = require('qunit-retry');`). Ensure your Node.js environment or bundler is configured to handle ESM.
Test passes on retry but fails when run in isolation, or subsequent retries also fail unexpectedly.
The test environment or state is not being properly reset between retry attempts, leading to lingering side effects from previous failures.
fix
Implement the `beforeRetry` hook to clean up any modified global state, DOM elements, or external resource interactions before each retry. For example, `setup(QUnit.test, { beforeRetry: () => { /* reset application state or DOM */ } })`.
Upgrade
Version history
3.0.1latest on npm
Audit
Dependencies
qunitrequiredProvides the testing framework and `QUnit.test` function that `qunit-retry` wraps. It is a peer dependency.
Agent activity
2 hits · last 30 days
node
2
Resources
qunit-retry — npm install qunit-retry · libregistry