QUnit PhantomJS Runner

2.4.2 · abandoned · verified Sun Apr 19

qunit-phantomjs-runner is a command-line utility designed to execute QUnit test suites headlessly using the PhantomJS browser engine. As of version 2.4.2, it provides basic console output for test results. The package's development largely coincided with the active period of PhantomJS, which has since been deprecated. Its primary mode of operation involves invoking a PhantomJS executable with the runner script and a URL to a QUnit test page. This approach offered a lightweight alternative to more complex test setup tools like Grunt in its era, although newer solutions often leverage modern headless browsers like Chrome or Firefox. The project appears to be in an abandoned state, given the general deprecation of PhantomJS and the age of its latest releases (last published to npm 5 years ago, GitHub shows last commit 10 years ago for `node-qunit-phantomjs` which uses this, but no direct releases for `qunit-phantomjs-runner` on GitHub).

Common errors

```
phantomjs: command not found
```
cause The PhantomJS executable is not installed or not available in the system's PATH.

fix Install PhantomJS globally (e.g., `npm install -g phantomjs-prebuilt` or via OS package manager) and ensure its executable path is included in your system's PATH environment variable.
```
ReferenceError: Can't find variable: phantom
```
cause The `runner.js` script is being executed directly with Node.js instead of being invoked by the PhantomJS executable.

fix Ensure you run the script using `phantomjs path/to/runner.js` and not `node path/to/runner.js`.
```
Error: Timeout waiting for QUnit to complete
```
cause Your QUnit test suite took longer than the default 5-second timeout to complete, or a test is hanging indefinitely.

fix Increase the timeout by providing it as an argument: `phantomjs runner.js [url] [new-timeout-in-seconds]`. If tests are genuinely hanging, debug your QUnit tests for infinite loops or asynchronous operations that aren't properly resolved.
```
Can't find variable: QUnit
```
cause The QUnit library is not loaded or available within the context of the HTML page being tested by PhantomJS.

fix Ensure your QUnit test HTML file correctly includes the QUnit JavaScript library (e.g., `<script src="path/to/qunit.js"></script>`) before your test code, and that the path to `qunit.js` is correct and accessible by PhantomJS.

Warnings

breaking In `v2.0`, a default timeout of 5 seconds was introduced for tests. Previously, the timeout was optional. This change can cause existing tests that exceed 5 seconds to fail unexpectedly, requiring explicit adjustment of the timeout parameter.
Fix: Pass an explicit timeout value in seconds as an argument to the runner script, e.g., `phantomjs runner.js [url] [timeout-in-seconds]`.
gotcha This package relies on PhantomJS, a headless browser engine that has been officially abandoned since March 2018. Using PhantomJS-based tools can introduce security vulnerabilities due to unpatched browser engine issues and may become increasingly incompatible with modern web standards and JavaScript features.
Fix: Consider migrating to test runners that utilize modern headless browsers like Headless Chrome, Puppeteer, or Playwright for better compatibility, performance, and security. Alternatives include `node-qunit-puppeteer` or configuring QUnit with Karma for broader browser support.
gotcha The runner specifically requires PhantomJS 1.6+, with 1.7+ recommended. Older or incompatible versions of PhantomJS might lead to unexpected errors, rendering issues, or script failures.
Fix: Ensure you have a compatible version of PhantomJS installed. If using `phantomjs-prebuilt`, check its version corresponds to the recommended PhantomJS versions. Verify PhantomJS is correctly installed and accessible in the system's PATH.

Install

npm install qunit-phantomjs-runner npm
yarn add qunit-phantomjs-runner yarn
pnpm add qunit-phantomjs-runner pnpm

Quickstart

Demonstrates how to install the package and run QUnit tests headlessly using the PhantomJS executable, including options for timeout and viewport size.

# First, ensure PhantomJS is installed and available in your system's PATH.
# You can often install it globally via npm (though it's deprecated):
# npm install -g phantomjs-prebuilt

# Then, install the runner locally:
npm install qunit-phantomjs-runner

# Create a simple QUnit test file, e.g., tests.html
# (Make sure QUnit is included in tests.html)

# To run your QUnit tests headlessly:
phantomjs node_modules/qunit-phantomjs-runner/runner.js http://localhost:8000/tests.html

# Example with a custom timeout (5 seconds) and viewport size:
# phantomjs node_modules/qunit-phantomjs-runner/runner.js http://localhost:8000/tests.html 5 '{"viewportSize":{"width":1000,"height":1000}}'

view raw JSON →