Registry / testing / parrot-middleware

parrot-middleware

library5.3.0jsnpmunverified

parrot-middleware is an Express.js middleware designed for mocking HTTP requests in development and testing environments. It allows developers to define a collection of 'scenarios', each comprising a list of request-response pairs. Based on the active scenario, the middleware intercepts matching incoming requests and serves the predefined mock responses. It provides dedicated control routes (`/parrot/scenario` for setting/getting the active scenario, and `/parrot/scenarios` for inspecting all available scenarios) to manage its behavior dynamically. Currently at stable version 5.3.0, the package sees active maintenance with frequent patch and minor releases, ensuring compatibility and addressing issues. Its key differentiator is the scenario-driven approach, making it easy to simulate complex backend states or error conditions without modifying frontend code or spinning up a full backend.

testing http-networking web-framework

npm install parrot-middleware

github ↗package ↗

INSTALL

IMPORT

SIG · PARROT-MIDDLEWARE

parrot-middleware

testingjavascriptv5.3.0

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

parrot

✓ import parrot from 'parrot-middleware';

✗ const parrot = require('parrot-middleware');

Modern Node.js projects primarily use ESM `import` syntax. While CommonJS `require` is still supported, `import` is the recommended and cleaner approach when `type: module` is set in `package.json`.

scenarios

✓ import scenarios from './scenarios.js';

✗ const scenarios = require('./scenarios.js');

Scenarios are typically defined in a separate file (e.g., `scenarios.js`) and default-exported. Ensure the file extension (`.js`) is included when using ESM imports in Node.js, unless a bundler handles it.

ParrotMiddlewareOptions

✓ import { ParrotMiddlewareOptions } from 'parrot-middleware';

While not directly imported for runtime, type definitions for configuration options are available for TypeScript users.

This example sets up an Express server with `parrot-middleware`, defining two basic scenarios. It demonstrates how to initialize the middleware with scenario definitions and provides instructions on how to activate a scenario via a POST request and then fetch the mocked data.

import express from 'express'; import parrot from 'parrot-middleware'; // scenarios.js const scenarios = { 'has one ship': [ { request: '/ship_log', response: { body: [{ name: 'The Jolly Roger', captain: 'Captain Hook' }], }, }, ], 'has more ships': [ { request: '/ship_log', response: { body: [ { name: 'The Jolly Roger', captain: 'Captain Hook' }, { name: 'The Black Pearl', captain: 'Jack Sparrow' }, ], }, }, ], }; const app = express(); app.use(express.json()); // Required for parsing JSON bodies for scenario POST requests app.use(parrot(scenarios)); app.get('/', (req, res) => res.send('Hello from main app!')); app.listen(3001, () => { console.log('Server running on http://localhost:3001'); console.log('Try: POST http://localhost:3001/parrot/scenario with { "scenario": "has one ship" }'); console.log('Then: GET http://localhost:3001/ship_log'); });

Debug

Known issues

breakingVersion 5.0.0 was a major release, but the changelog provided does not detail specific breaking changes for `parrot-middleware`. Users upgrading from v4.x should review the `parrot` core package changes or test thoroughly for potential API alterations in middleware options or scenario processing, particularly regarding configuration structures or default behaviors.

fix

Consult the main Parrot repository's changelog or migration guides for core breaking changes. Thoroughly test existing mock configurations after upgrading.

affects: >=5.0.0

gotchaThe `parrot-middleware` must be placed before any other routes it is intended to intercept. If another route handler matches a path before `parrot` processes it, the mock will not be served.

fix

Ensure `app.use(parrot(scenarios));` is placed early in your Express application's middleware chain, typically before most `app.get()`, `app.post()` etc., route definitions.

affects: >=3.0.0

gotchaTo allow the `/parrot/scenario` POST endpoint to receive and parse JSON payloads for setting the active scenario, `express.json()` middleware (or an alternative body parser) must be enabled *before* `parrot-middleware`.

fix

Add `app.use(express.json());` (or `app.use(bodyParser.json());` for older Express versions) before `app.use(parrot(scenarios));` in your server setup.

affects: >=3.0.0

gotchaWhen defining scenarios, ensure that your `request` objects specify the `method` if you intend to mock non-GET requests. By default, requests are matched with `GET` if no method is specified in the scenario.

fix

For POST, PUT, DELETE, etc., mocks, explicitly add `{ request: { path: '/your_path', method: 'POST' }, response: ... }` to your scenario definitions.

affects: >=3.0.0

Errors

Common errors & fixes

Error: Can't set headers after they are sent to the client.

This typically occurs in Express when a response is attempted to be sent multiple times, often due to improper `next()` calls or asynchronous operations resolving after a response has already been sent.

fix

Review your middleware chain and scenario response logic. Ensure that once a mock response is served, no subsequent middleware attempts to send another response. Also, verify `next()` is called correctly if `parrot-middleware` doesn't handle a request.

TypeError: parrot is not a function

This error usually indicates that the `parrot` export was not correctly imported, most commonly by attempting a CommonJS `require` call on an ESM default export or vice versa, or a named import instead of a default.

fix

If using Node.js modules (ESM), use `import parrot from 'parrot-middleware';`. If strictly CommonJS, ensure your `package.json` does not have `"type": "module"` and use `const parrot = require('parrot-middleware');`.

No scenario named '...' found

The scenario name provided in the POST request to `/parrot/scenario` does not exactly match any of the keys in your `scenarios` object.

fix

Double-check the scenario name for typos, case sensitivity, and ensure it corresponds precisely to a key in your `scenarios.js` (or equivalent) definition.

Upgrade

Version history

5.3.0latest on npm

Audit

Dependencies

expressrequiredThis package is an Express.js middleware and requires Express to function.

Agent activity

15 hits · last 30 days

node

Resources

githubhttps://github.com/americanexpress/parrot ↗

packagehttps://www.npmjs.com/package/parrot-middleware ↗