The mocks in your CI gates.
CI Kit runs a repository's gates locally, before anything reaches a runner. This package is the mock engine those gates can point at, so the same loop works on a laptop and in CI.
How it fits
The kit starts the mocks in the background, waits for them to answer, runs the tests against them, and shuts them down again — so a test run never leaves a container behind, and never needs a cloud runner.
The configuration lives in .ci/ci.json, in the
mocks section. It names the command that starts the
mocks, the directory it runs in, and the address each mock answers
on.
{
"mocks": {
"command": "node bin/api-mock-services.js start stripe paystack",
"endpoints": {
"stripe": "http://127.0.0.1:4001",
"paystack": "http://127.0.0.1:4005"
}
}
}
The configuration
This repository's own .ci/ci.json looks like this:
{
"stack": ["node"],
"act": { "image": "catthehacker/ubuntu:act-latest", "envFile": ".env.act", "secretFile": ".secrets" },
"mocks": {
"command": "node bin/api-mock-services.js start stripe paystack flutterwave",
"cwd": ".",
"endpoints": {
"stripe": "http://127.0.0.1:4001",
"paystack": "http://127.0.0.1:4005",
"flutterwave": "http://127.0.0.1:4010"
}
}
}
| Key | What it is for |
|---|---|
command | The command that starts the mocks. Here it starts three of them in one process, on one port each. |
cwd | The directory the command runs in. |
endpoints | The name of each mock and the address it answers on. The kit waits on these before the tests run. |
A project that uses both gets the same loop in CI and on a laptop. The command and the endpoints are what change from one project to the next.
The three targets
The kit supplies them, so they work here without any extra configuration:
make mocks-up # start the mocks the tests need
make mocks-status # are they answering?
make mocks-down # stop them
make mocks-up runs the command from
.ci/ci.json in the background and waits for each
endpoint to answer. make mocks-status says whether they
are up. make mocks-down stops them, so nothing is left
running.
Waiting for the mocks
Every mock answers /health, so a container can be checked
without knowing which mock it is. That is the check the kit waits on.
curl -s http://127.0.0.1:4001/health
curl -s http://127.0.0.1:4005/health
curl -s http://127.0.0.1:4010/health
If you are driving the mocks yourself, wait for the answer rather than for a fixed delay:
until curl -sf http://127.0.0.1:4001/health >/dev/null; do sleep 0.2; done
The other targets
The Makefile keeps the local test as the gate. make ci
runs it first, so nothing reaches a runner that has not been through
the same tests on this machine.
| Target | What it does |
|---|---|
make | List the targets. |
make test | The local tests. |
make pre-ci | The local tests — the step the CI depends on. |
make ci | The local tests, then the CI gate. |
make mocks | Start the mocks, for a project to point at. The set is MOCKS, which defaults to stripe resend xero cloudflare paystack. |
make compose | Start the mocks as containers. make PROFILE=payments starts one group. |
make docker | Build the container image. |
The commands behind them are the package's own:
npm test # the tests
npm run lint # the house style
npm run check # both
npm run footprint # are the mocks still light?
Each mock is started and asked something, so a broken one is caught here rather than in a project that depends on it. The footprint is a budget, and it is checked in CI: eighteen mocks in one process, about 50MB of memory, under 1% CPU while idle, and answering in under half a second. If a change makes the mocks heavier, the build fails.
The kit itself
The kit is found by the Makefile, in this order: an explicit
CI_KIT path, then $CI_KIT_PATH, then a kit
vendored into .ci/kit, then the usual install
locations. It is installed with:
curl -fsSL https://raw.githubusercontent.com/omeiza-workspace/ci-kit/main/bin/install.sh | sh
A project that uses the mocks and the kit together needs no cloud runner to exercise a third-party flow. The mocks answer on the machine, the tests run against them, and the kit stops them afterwards.