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-retryVerified import paths — ran on the pinned version, not inferred.
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.
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"`.
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.
Pass a `beforeRetry` function to the `setup` call (e.g., `setup(QUnit.test, { beforeRetry: () => resetMyEnvironment() })`) to ensure a clean slate for each retry attempt.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.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 */ } })`.