Istanbul Middleware for Connect/Express
raw JSON → 0.2.2 verified Thu Apr 23 auth: no javascript abandoned
istanbul-middleware is a Connect/Express middleware package designed to integrate Istanbul code coverage into Node.js applications, supporting both server-side and browser-side code coverage during functional tests. It allows developers to hook `require()` for server-side instrumentation, expose dynamic HTML coverage reports, reset coverage data, and download reports via special HTTP endpoints (e.g., `/coverage`). It also provides mechanisms to instrument JavaScript files delivered to the browser and aggregate client-side coverage data posted back to the server. The package's current stable version is 0.2.2, with the last update approximately 10 years ago (as of 2024). It was explicitly labeled as 'experimental' and suitable for 'narrow use-cases' like Express 3. Its key differentiator was providing a server-integrated solution for coverage, aggregating data from various sources. Due to its age and lack of updates, the project is considered abandoned, and newer alternatives for code coverage (like the `istanbuljs` ecosystem) should be preferred.
Common errors
error TypeError: app.use is not a function ↓
cause The `app` object is not a valid Express or Connect application instance, or you are trying to use an older `express3` instance with a newer API or vice-versa.
fix
Ensure
app is a correctly initialized Express application (e.g., const app = express();) and that your Express version is compatible with this middleware (targeting Express 3). error Error: Cannot find module 'istanbul-middleware' ↓
cause The package `istanbul-middleware` is not installed or not resolvable in the current Node.js environment.
fix
Run
npm install istanbul-middleware to add the package to your project dependencies. error SyntaxError: Cannot use import statement outside a module ↓
cause You are attempting to use ES Module `import` syntax (`import im from 'istanbul-middleware'`) in a CommonJS environment, or vice-versa, for a package that only supports CommonJS.
fix
Replace
import im from 'istanbul-middleware'; with const im = require('istanbul-middleware');. Warnings
breaking The package is explicitly labeled as 'experimental' and known to work only for 'narrow use-cases' such as Express 3. It has not been updated in approximately 10 years and is considered abandoned. Compatibility with newer Node.js versions (e.g., Node.js 14+), Express 4+, or other modern web frameworks is highly unlikely, and significant breakage is expected. ↓
fix Do not use this package in new projects. For existing projects, consider migrating to modern alternatives within the `istanbuljs` ecosystem (e.g., `@istanbuljs/nyc-config-base`, `nyc`) which are actively maintained and support current JavaScript features and Node.js environments.
gotcha Using `im.hookLoader()` globally modifies Node.js's `require()` function to instrument code on the fly. The README explicitly warns: 'ensure this is not production!'. This can have performance implications and introduce unexpected behavior in a production environment. ↓
fix Only enable `istanbul-middleware` in development or test environments. Guard its usage with environment checks (e.g., `process.env.COVERAGE == "true"`) to prevent accidental deployment to production.
gotcha The `hookLoader` call must occur very early in your application's lifecycle, *before* any other application code that needs to be covered is `require()`-d. If not, those modules will load uninstrumented, and their coverage will not be tracked. ↓
fix Place `im.hookLoader()` at the absolute entry point of your server application, typically the first lines of your main server file, conditioned on your `isCoverageEnabled` flag.
deprecated This package exclusively uses CommonJS `require()` syntax and does not support ES Modules (`import`/`export`). Attempts to `import` it will result in errors in an ESM context. ↓
fix Ensure your project is configured for CommonJS if you absolutely must use this package. For new projects, migrate to modern coverage tools that natively support ESM.
Install
npm install istanbul-middleware yarn add istanbul-middleware pnpm add istanbul-middleware Imports
- im wrong
import im from 'istanbul-middleware';correctconst im = require('istanbul-middleware'); - hookLoader
im.hookLoader(__dirname); - createHandler
app.use('/coverage', im.createHandler()); - createClientHandler
app.use(im.createClientHandler(__dirname));
Quickstart
const im = require('istanbul-middleware'),
express = require('express'),
app = express();
// Determine if coverage is enabled, e.g., via environment variable
const isCoverageEnabled = (process.env.COVERAGE === "true");
// Hook the Node.js loader for server-side coverage instrumentation.
// This MUST happen before your application's code is 'require()'-d.
if (isCoverageEnabled) {
console.log('Hook loader for coverage - ensure this is not production!');
im.hookLoader(__dirname); // Instruments all files under __dirname except node_modules
}
// Require your main application code AFTER the loader is hooked
const appRoutes = require('./lib/routes'); // Example application code
// Set up basic Express middleware (e.g., body parsers, static files)
app.use(express.json());
app.use(express.static('public'));
// Add the coverage handler if enabled
if (isCoverageEnabled) {
// Enable coverage endpoints under /coverage
// This will expose /coverage, /coverage/reset, /coverage/download, /coverage/client
app.use('/coverage', im.createHandler());
}
// Add your application's router and other endpoints
app.use('/', appRoutes);
// For client-side coverage, serve instrumented JS files.
// Place this middleware before your static file handler for JavaScript assets.
if (isCoverageEnabled) {
// All JS files under the root will be sent instrumented to the browser
app.use(im.createClientHandler(__dirname));
}
app.listen(3000, () => {
console.log('App listening on port 3000');
if (isCoverageEnabled) {
console.log('Coverage enabled via /coverage endpoints.');
}
});