phantomas is a modular, headless Chromium-based web performance metrics collector written in JavaScript, released under the BSD-2-Clause licence, and intended for developers and operations teams who need to measure and monitor real page behaviour from Node.js scripts, test suites, or containers.

What it is

phantomas is a web performance metrics collector that drives a headless Chromium instance and reports what a page actually does at runtime. It lives in the Node.js ecosystem, requires NodeJS 16 or newer, and is published on npm. Internally it is modular by design: each metric is generated by a separate module, while the phantomas core acts as an events emitter that every module can hook into. The project is written in JavaScript, carries 2,260 stars and 135 forks on GitHub, and is categorised in this registry under Infrastructure and Operations, Monitoring and Observability.

The concrete problem it solves is the gap between synthetic page checks and the real behaviour of a browser. phantomas reports in-depth metrics that a plain HTTP probe cannot see, such as the number of events bound via jQuery, calls to window.write, and complex or duplicated CSS selectors analysed through analyze-css. It also exposes the request stream itself, emitting a recv event for every response with its method, URL, and content type, so teams can correlate front-end symptoms with network activity. The README does not position phantomas against a named product that it replaces; it stands as a purpose-built collector rather than a drop-in substitute for something else in these facts.

Key capabilities

• Modular metric architecture: every metric comes from its own module, and the core emits events that modules subscribe to.
• DOM and JavaScript introspection, including counts of events bound via jQuery, calls to window.write, and complex or duplicated CSS selectors detected with analyze-css.
• JavaScript API exposed as a CommonJS module through require('phantomas'), returning a promise with results.getMetrics() and results.getAllOffenders().
• Event handling for individual responses via the recv event, which surfaces method, URL, and contentType, and for DOM queries via the domQuery event.
• Page-side metric emission through helper functions available in window.__phantomas, letting the measured page report its own numbers.
• JSON as an output format, plus a device profile system that emulates mobile or tablet by setting an appropriate user agent and viewport.
• Prebuilt container images published as macbre/phantomas:latest on Docker Hub and ghcr.io/macbre/phantomas:latest on GitHub's Containers registry.

Who uses it and how

• Node.js projects that import phantomas as a library and fold performance metrics into existing application code or tooling.
• Continuous integration setups: pull requests filed against the repository have tests run through GitHub Actions, and the same pattern applies to downstream projects.
• Container-based environments that pull macbre/phantomas:latest or ghcr.io/macbre/phantomas:latest instead of installing Node and Chromium on the host.
• Teams testing responsive behaviour, using device profiles to emulate mobile and tablet user agents and viewports.
• Monitoring pipelines that consume the JSON output or subscribe to events such as recv and domQuery for observability tooling.

Getting started

Install with npm install phantomas, which also installs a recent version of Chromium supported by the puppeteer module, and call it from a script such as ./examples/index.js. A Docker image is available as macbre/phantomas:latest or ghcr.io/macbre/phantomas:latest for environments that prefer a container over a local Node.js 16+ toolchain.

How it compares

The supplied facts name no competing or similar tools for phantomas, so it stands alone in this registry rather than being positioned against an alternative. No paid product is listed as something phantomas replaces.

When to use it — and when not to

A self-hoster must run Node.js 16 or newer and carry the Chromium build that puppeteer installs, or accept the Docker image to avoid managing that locally; running the integration test suite additionally requires a local nginx container started with ./test/server-start.sh. Support is not free by default, since it is sold through xs:code, and the README defers troubleshooting to a separate Troubleshooting.md rather than covering failures inline. Teams that need a fully hosted, zero-runtime service with guaranteed vendor support should look elsewhere, and anyone unwilling to operate a browser engine should not adopt it.

npm install phantomas

docker pull macbre/phantomas:latest

docker pull ghcr.io/macbre/phantomas:latest

const phantomas = require('phantomas'),
    promise = phantomas('http://example.com/');

promise.
    then(results => {
        console.log('Metrics', results.getMetrics());
        console.log('Offenders', results.getAllOffenders());
    }).
    catch(res => {
        console.error(res);
    });

// events handling
promise.on('recv', response => {
    console.log('Response: %s %s [%s]', response.method, response.url, response.contentType);
});

// including the custom one emitted by phantomas modules
promise.on('domQuery', (type, query) => {
        console.log('DOM query by %s - "%s"', type, query);
});

git clone git@github.com:macbre/phantomas.git
npm install

./test/server-start.sh
npm t