run-middleware

0.9.10 verified Sat Apr 25 auth: no javascript maintenance

A Node.js module to programmatically execute Express middleware and route handlers without making network requests. It simulates a client calling REST APIs internally, allowing direct invocation of endpoints from code with support for custom query parameters, body, HTTP method, cookies, and response redirect tracking. Current stable version is 0.9.10 (last published in 2018). It has low maintenance activity, with no recent updates. Key differentiator: enables server-side execution of Express routes without requiring a listening server, useful for testing or reuse of logic.

Common errors

error TypeError: app.runMiddleware is not a function ↓

cause Missing call to require('run-middleware')(app) before using app.runMiddleware.

fix

Add require('run-middleware')(app) right after creating the Express app.

error TypeError: Cannot read property 'path' of undefined ↓

cause Passing an options object as the first argument instead of a path string.

fix

Use app.runMiddleware('/path', { query: {}, body: {} }, callback) — path must be first argument.

error Error: listen EADDRINUSE :::3000 after using run-middleware ↓

cause Running server.listen in the same test where runMiddleware is used without specifying port or async handling.

fix

Do not call app.listen if only testing routes; runMiddleware does not require a listening server.

Warnings

deprecated Package has not been updated since 2018; may not be compatible with Express 4.x or newer versions. ↓

fix Consider using supertest or direct function calls instead.

gotcha The module mutates the Express app object by adding methods; this can cause side effects if not accounted for. ↓

fix Be aware that app.runMiddleware is added after require; avoid accidentally overriding it.

gotcha The callback signature is (code, body, headers) where body can be a string, Buffer, or object depending on middleware response. ↓

fix Parse body if needed: const parsed = typeof body === 'string' ? JSON.parse(body) : body;

gotcha Does not support async/await natively; callback pattern only. ↓

fix Wrap in a Promise if needed: new Promise((resolve, reject) => app.runMiddleware(path, (code, body) => resolve({code, body})));

Install

npm install run-middleware

yarn add run-middleware

pnpm add run-middleware

Imports

run-middleware
wrong
```
import runMiddleware from 'run-middleware'
```
correct
```
require('run-middleware')(app)
```
This package is CommonJS-only and mutates the Express app object via a side-effect function call. There is no default or named export; it adds the `runMiddleware` method to the app instance.
app.runMiddleware
wrong
```
app.runMiddleware({path:'/path', ...}, callback)
```
correct
```
app.runMiddleware('/path', options, callback)
```
The method is attached to the Express app instance after calling require('run-middleware')(app). The first argument must be the route path string, not an options object.
res.runMiddleware
wrong
```
res.runMiddleware = app.runMiddleware
```
correct
```
res.runMiddleware('/path', options, callback)
```
`res.runMiddleware` is available inside a middleware to pass cookies and headers from the current request. It is automatically attached by the module.

Quickstart

Demonstrates basic usage: setting up Express, requiring run-middleware to attach the method, then calling app.runMiddleware on a route to get the simulated response.

const express = require('express');
const app = express();

// Define a route
app.get('/api/hello', (req, res) => {
  res.json({ message: 'Hello, world!' });
});

// Initialize run-middleware
require('run-middleware')(app);

// Invoke the route programmatically
app.runMiddleware('/api/hello', (code, body, headers) => {
  console.log('Status:', code);
  console.log('Body:', body);
});