Scenario Mock Server

Common errors

• Error: listen EADDRINUSE: address already in use :::3000

  cause The default port (3000) for the mock server is already occupied by another process.
  fix Specify a different port in the `options` object when calling `run()` or `createExpressApp()`, e.g., `{ options: { port: 3001 } }`.

• ReferenceError: require is not defined

  cause Attempting to use `require()` in an ECMAScript Module (ESM) context without proper configuration (e.g., `"type": "module"` in `package.json` but using `require`).
  fix Switch to `import { run } from 'scenario-mock-server';` syntax, or ensure your environment is configured for CommonJS modules, or use a build tool to transpile.

• Scenario 'my-missing-scenario-id' not found or active for path '/api/data'

  cause The requested scenario ID does not exist in your defined scenarios, or the server is not configured to select it.
  fix Verify the scenario ID spelling. Ensure the scenario is correctly defined in the `scenarios` object. If using the UI, select the correct scenario. If using `sms-scenario-id` header, confirm the header value matches an existing scenario group key.

Warnings

• breaking The package was renamed from `data-mocks-server` to `scenario-mock-server`. Projects upgrading or migrating from the old package name must update their `package.json` and all import/require statements.
  Fix: Update `npm install data-mocks-server` to `npm install scenario-mock-server` and change all code references from `data-mocks-server` to `scenario-mock-server`.
• gotcha Custom headers `sms-scenario-id` and `sms-context-id` for parallel testing are explicitly NOT supported when `cookieMode` is enabled. If you need per-request scenario selection, ensure `cookieMode` is set to `false` (default) or not configured.
  Fix: If parallel testing with headers is required, do not enable `cookieMode`. If `cookieMode` is necessary, manage scenarios and contexts via the UI or programmatically for individual users/sessions.
• breaking Version 1.0.0 marked the first major release of the `scenario-mock-server` under its new name. While specific breaking changes from any pre-1.0.0 versions of `data-mocks-server` are not detailed in the release notes, users migrating from unversioned or pre-1.0.0 iterations of the original project should expect potential API shifts.
  Fix: Refer to the `scenario-mock-server` documentation for the latest API if migrating from older `data-mocks-server` versions. Review your mock definitions and server setup.

Install

• npm install scenario-mock-server npm
• yarn add scenario-mock-server yarn
• pnpm add scenario-mock-server pnpm

Imports

• run
  wrong:

  const { run } = require('scenario-mock-server');

  correct:

  import { run } from 'scenario-mock-server';

  While CommonJS `require` is supported, TypeScript projects and modern JavaScript environments should use ES Modules `import`.
• createExpressApp
  wrong:

  const { createExpressApp } = require('scenario-mock-server').createExpressApp;

  correct:

  import { createExpressApp } from 'scenario-mock-server';

  Used for integrating the mock server into an existing Express application.
• HttpMock
  wrong:

  import { HttpMock } from 'scenario-mock-server';

  correct:

  import type { HttpMock } from 'scenario-mock-server';

  This is a TypeScript type definition. Always use `import type` for types to avoid bundling issues and clarify intent.

Quickstart

This example initializes the mock server with two distinct scenarios, 'item' and 'cheese', for the '/api/test-me' endpoint, demonstrating basic setup and scenario definition.

import { run } from 'scenario-mock-server';

run({
	scenarios: {
		item: [
			{
				path: '/api/test-me',
				method: 'GET',
				response: { data: { blue: 'yoyo' } },
			},
		],
		cheese: [
			{
				path: '/api/test-me',
				method: 'GET',
				response: { data: { blue: 'cheese' } },
			},
		],
	},
	options: {
		port: process.env.MOCK_SERVER_PORT ? parseInt(process.env.MOCK_SERVER_PORT) : 3000,
		cookieMode: false
	}
});

console.log('Scenario Mock Server running. Visit http://localhost:3000 to manage scenarios.');