API mocks that agree with each other.

• A world behind the spec

  Every record is a pure function of (seed, entity, id). The same customer shows up in the customer, order and payment endpoints, and /orders?customerId=3 equals /customers/3/orders.

• Seeded and stateless

  Same seed, same data. Nothing is stored, so there is no state to leak between tests. Opt into stateful for create, update and delete.

• Scenarios are first-class

  429, 500, 503, timeouts, network errors, empty pages, schema boundaries and slow responses, selected per call, per header or per forge.

• Plugs into MSW

  m2mockforge decides what the response is. MSW, or the built-in Node server, decides how requests are caught.

• Specs are data

  No eval, no external $refs, capped YAML aliases and screened patterns. Generated data is synthetic: example.com, mock tokens, 555-01xx phones.

• Browser-safe core, Node extras

  The core has no Node built-ins and a test enforces it. The Node server and the CLI sit behind separate entry points. One runtime dependency, yaml.

Read what it doesn't support →

1. 1

   Call it directly

   Hand it a request, get a response and an explanation of why it looks that way.

   ts

   import { readFileSync } from "node:fs";
   import { createMockForge } from "m2mockforge";
   
   const forge = createMockForge({
     spec: readFileSync("openapi.yaml", "utf8"), // or an already-parsed object
     seed: "my-test-suite",                      // same seed => same data, every run
   });
   
   const res = await forge.handle({ method: "GET", url: "/customers/7", headers: { authorization: "Bearer x" } });
   res.status; // 200
   res.body;   // a Customer that satisfies your schema; customer 7 is the same everywhere
   console.log(forge.explain(res)); // why the response looks the way it does

2. 2

   Plug it into MSW

   Works in the browser and in Node. Faults map to MSW's own error and delay.

   ts

   import { setupServer } from "msw/node";
   import { createMockForge } from "m2mockforge";
   import { createMswHandlers } from "m2mockforge/msw";
   
   declare const spec: string;
   
   const forge = createMockForge({ spec, seed: 1 });
   const server = setupServer(...createMswHandlers(forge, { baseUrl: "https://api.example.com" }));
   server.listen();
   
   forge.useScenario("rate-limit"); // every call now returns 429 + Retry-After
   forge.useScenario("network-error"); // fetch() rejects
   forge.clearScenario();

3. 3

   Or run it as a server

   Binds to 127.0.0.1 by default. Clients pick a scenario per request with a header.

   sh

   npx m2mockforge validate openapi.yaml
   npx m2mockforge routes openapi.yaml
   npx m2mockforge generate openapi.yaml GET /customers/7 --header "Authorization: Bearer x" --seed 42
   npx m2mockforge serve openapi.yaml --port 4010 --scenario rate-limit

   ts

   import { createMockForge } from "m2mockforge";
   
   declare const spec: string;
   
   createMockForge({
     spec,
     overrides: { Customer: { currency: "EUR" } }, // always-on entity data
     scenarios: [
       { name: "vip", overrides: { Customer: { tier: "pro" } } }, // data scenario
       { name: "payments-down", match: ["getPayment", "POST /orders"], status: 502,
         body: { error: { code: "GATEWAY", message: "down" } } }, // operation scenario
       { name: "flaky", base: "server-error", after: 1, times: 2 }, // OK, fail, fail, OK, OK...
     ],
   });

• seedNumber or string. Drives all generation: same seed, same data.
• scenarioNamed behaviour, active by default or chosen per call or per x-m2mockforge-scenario header.
• overridesAlways-on entity data by component name: an object, or a function of the record.
• handlersCustom behaviour by operationId or METHOD /path. Return undefined to fall through.
• statefulPersist POST, PUT, PATCH and DELETE in memory for one forge instance.
• limitsBounds on spec size, operations, schema nodes, depth and collection size. Exceeding one throws.

See every option →