Parrot Middleware for Express

Common errors

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

  cause 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

  cause 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

  cause 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.

Warnings

• breaking Version 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.
• gotcha The `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.
• gotcha To 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.
• gotcha When 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.

Install

• npm install parrot-middleware npm
• yarn add parrot-middleware yarn
• pnpm add parrot-middleware pnpm

Imports

• parrot
  wrong:

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

  correct:

  import parrot from '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
  wrong:

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

  correct:

  import scenarios from './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.

Quickstart

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');
});