Case study 02
Four containers, 250 MB, and a proxy that never settled.
How one dependency-free Node process replaced four mock containers — and turned the footprint into a build gate instead of a paragraph
In plain terms
To test a payment, the team needed a real payment account and a network connection, so the riskiest part of the product was the part that got tested least. The stand-in they had was four programs taking a quarter of a gigabyte of memory and never settling down. This is one program with no dependencies, fifty megabytes, and no idle CPU.
- Before: 4 programs, 250 MB, 7.9% idle CPU, 20 seconds before the first request was answered
- After: 1 program, 50 MB, no idle CPU, 1.4 seconds
- 18 providers covered, including Paystack, Interswitch, Flutterwave and Smile ID
- The size is enforced on every build, so it cannot quietly grow
The mock environment was a docker compose file with four services. It was slow to start, it idled at nearly 8% CPU, and one of its containers existed to translate OpenAPI specs — and never finished doing it.
01
The problem
The mock environment cost more than the code it was mocking
Every project that talks to a payment gateway, an email provider, an accounting service, a DNS provider, a messaging service or an identity check needs something to talk to in a test. The arrangement in the workspace was four containers: the mock service, an OpenAPI proxy that served the provider specs, and two supporting services.
Measured on one machine with every mock running, that arrangement cost four processes, 250 MB of resident memory, 7.9% idle CPU, and 20 seconds and rising before the first request was answered. 214 MB of the memory and almost all of the CPU belonged to the OpenAPI proxy — the component whose job was translating a spec, and which did not settle.
And the arithmetic was brutal. On a developer laptop, where memory is the scarcest resource, a test setup that permanently occupies a quarter of a gigabyte and never idles is not a tool that gets used often. It is a tool people queue for, postpone, and eventually bypass — which puts the test back to manual, and the manual version back to one senior person who knows how to run it.
The containers were not the problem. The container count was the problem, and the runtimes each one dragged in behind it.
A mock environment that costs a quarter of a gigabyte and never idles is not a tool people use often. It is a tool people postpone.
What it looked like day to day
- Four processes to start, stop and clean up for every test run
- 250 MB resident with every mock running, of which 214 MB was the OpenAPI proxy alone
- 7.9% idle CPU while doing nothing, almost all of it in the proxy
- 20 seconds and rising before the first request was answered
- The proxy never settled — it kept translating specs that were already translated
02
The approach
Delete the runtimes until there is nothing left to delete
The rewrite did not add features. It removed everything that could be removed, and then made the result a rule rather than a preference.
The rules are published at the top of the README, because a contributor who breaks one of them breaks the promise in the first line of the file:
No dependencies. Not 'few' — none. The engine runs on Node's own HTTP server. A dependency is a package to install, audit and keep out of the advisories.
No runtime that costs memory to start. A JVM, a compiled Go binary or a Python environment all add to the footprint before a single request is served. Node is already on the machine, because the project under test runs on it.
One process for every mock. Nine mocks in one process cost 50 MB. Nine containers cost nine runtimes.
In the test, not beside it. A test that needs a mock starts it in the test process, with startMock(). Nothing listens on a port, no container starts, and the mock stops when the test ends. This is the cheapest way to mock anything, and it is why the engine is a library first and a service second.
Idle means idle. A mock answers a request and then stops computing. Polling, watching and retrying are how a mock turns into a battery drain.
The last rule is the one most engines get wrong, and it is the reason this one measures 0.0% idle CPU while the stack it replaces sits at 7.9%.
The last rule is the one most engines get wrong: a mock answers a request and then stops computing.
03
The architecture
Five layers, zero dependencies
test process one process, 50 MB
┌──────────────┐ ┌──────────────────────┐
│ startMock() │ │ Node http server │
│ │────────────────▶│ no dependencies │
│ no ports │ │ │
│ no cleanup │ │ /stripe /paystack │
└──────────────┘ │ /interswitch │
│ │ /flutterwave │
│ nothing to stop │ /monnify │
▼ │ /smileid /twilio │
test ends │ /resend /xero ... │
└──────────┬───────────┘
│
OpenAPI spec contracts
The HTTP core
Node's own http module, no framework. Every mock is a route table and a handler, mounted onto one server. This is where the memory floor comes from: there is nothing to load.
The provider mocks
Eighteen providers — Stripe, Paystack, Interswitch, Flutterwave and Monnify for payments; YouVerify, Smile ID and IdentityPass for identity; Twilio, Termii, OneSignal, WhatsApp and FCM for messaging; Resend, Xero, Cloudflare, OpenAI and S3 for everything else. Every mock answers /health, so a container can be checked without knowing which mock it is.
The spec layer
Provider contracts are held as OpenAPI documents, with a download script that keeps them current. The spec is the source of truth for a mock's shape, so the mock and the published contract cannot quietly diverge.
The control surface
A control endpoint and a panel for listing and driving the mocks, so a run can be inspected and reset without restarting the process. This is what makes the engine usable as a service as well as a library.
The test integration
startMock() runs the mock inside the test process, so nothing listens on a port and nothing needs cleaning up afterwards. The engine is a library first and a service second — that ordering is what makes the footprint claim true in a test run, which is where it matters most.
04
The results
The same work, one fifth of the memory and no idle CPU
Before
- 4Processes
- 250 MBMemory
- 214 MB, and it does not settleOf which the OpenAPI proxy
- 7.9%, almost all of it the proxyIdle CPU
- 20 s and risingTime to first request answered
- 4Things to start, stop and clean up
After
- 1Processes
- 50–51 MBMemory
- — the specs are loaded in-processOf which the OpenAPI proxy
- 0–0.5%Idle CPU
- 0.4–1.4 sTime to first request answered
- 1Things to start, stop and clean up
- The measurement was taken with the project's own
npm run footprintscript, which starts the engine with every mock it carries, waits for the first request to be answered, samples the resident size withps, and samples the CPU with twops -o time=reads ten seconds apart. The container figures come fromdocker compose up -dsampled withdocker stats --no-stream, once immediately and once after the containers had settled. - The engine's own figures are published as a range rather than a single number, and that is deliberate. The first version of this case study quoted 1.4 s for the first request while the mock engine's evidence document quoted 465 ms for the same measurement. Both were real samples of the same thing on different machines, and the measurement moves by a factor of three depending on what the machine is doing. A single sample presented as the figure is not a measurement — it is a number that happened to be true once. Both documents now quote the range and name the script that produces it.
- The footprint figures are a build gate, and the gate was repaired rather than merely widened. Its idle budget was 1% over a three-second sampling window, which made it fail two runs in three on an idle machine. A gate that fails sometimes is worse than no gate, because it teaches people to retry it instead of reading it. The window is now ten seconds and the budget 2% — four times above what the engine uses, four times below the 7.9% it exists to catch.
- This is a lighter mock, not a faithful sandbox. It answers the calls a test makes. It does not model a provider's business rules, and it is not a staging environment. The documentation says so, in a section of its own.
- The footprint was measured when the engine carried nine mocks. It now carries eighteen, and the gate is what keeps the figure honest as that number grows.
05
The public record
The public record is designed so it cannot be inflated
The project publishes a community page with a rule that is unusual and worth stating plainly: the adopter list is a file in the repository, and it grows by pull request. It is public, reviewable, and cannot be inflated — because adding a name requires a commit that anyone can see and revert. The same page invites press mentions to be submitted as an issue, and states that the list is optional for people who would rather not be named. That is a more credible structure than a testimonials widget, and it is one a reviewer can audit in a minute.
Adopters live in ADOPTERS.md
A row is added by pull request. The file is the list. There is no form, no email, no account, and nothing that can be quietly edited.
Mentions are links, not logos
Press and mentions are submitted as an issue with a URL. A link can be checked in one click; a logo cannot.
Listing is optional
The documentation says outright that being listed is not required, and that the list exists for people who want to be found. Honesty about the absence of a number is worth more than a number nobody can verify.
06
Lessons
What I would tell my past self
Footprint decides adoption, not features
The feature set barely moved between the two versions. The footprint moved from 250 MB to 50 MB, and the number of teams that could run it at all moved with it. If the tool will not fit on a laptop, it will not be in the inner loop, and it will not change anyone's behaviour.
'No dependencies' is a policy, not a preference
Every dependency is a package to install, audit and keep out of the advisories — and this project was already reporting 93 advisories in a different repository. Choosing zero is not asceticism; it is a way of not adding to a problem you are publicly documenting elsewhere.
The rules belong in the README, at the top
The rules are published before the feature list, because the first line of the README is a promise about weight and the rules are what keep it true. A contributor who breaks a rule breaks the promise, and they can see that before they start.
Make the claim a gate
The footprint test fails the build at 100 MB. A number in a README is a claim; a number in a test is a constraint. The difference between the two is the difference between a promise and an enforced property, and it is the same reason the mock engine's 0.0% idle CPU is believable when a competitor's 7.9% is not.
Keep reading
The controller was the problem, not the automation.
- api-mock-services repository
- The footprint build gate
- Related article: Local Sandboxes for Interswitch and Paystack
Documentation in the repository
- Overviewwhat the engine is
- Architecturethe layers
- CI gatesusing the mocks in a pipeline
- Offline testingthe guide
- Communitythe public record
- READMEthe rules, and the numbers
Indexed rather than copied, so the repository stays the single source of truth.