Skip to content
Imposters

Overview

Imposters is a service virtualization tool. It runs mock servers, called imposters, that stand in for the services your code talks to: HTTP APIs, and an in-memory AWS S3. You program them while they run, over a REST API or from a JSON config file. It is inspired by Mountebank and built with TypeScript and Effect. It runs on Node.js or Bun.

How a request flows

Section titled “How a request flows”
  1. One admin server listens on port 2525. Its REST API creates imposters, adds stubs and reads back what each imposter received. It also serves a dashboard at /_ui and the OpenAPI document.
  2. Each imposter listens on its own port. Starting one binds that port; stopping it releases the port.
  3. Stubs are matched in order. A stub is a list of predicates (all must pass) and one or more responses. The first stub whose predicates all match the request answers it. A response can first call other services, and notify them after: see Callbacks.
  4. No stub matched? An imposter with an extension protocol, such as the S3 emulator, answers the request itself. Otherwise, an imposter with a proxy forwards it to the real service. Otherwise the answer is a 404:
{"error":"No matching stub found","method":"GET","path":"/refunds"}

Stubs are read on every request, so adding, changing or deleting one takes effect on the next request, without restarting the imposter.

Where to go next

Section titled “Where to go next”