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"
    }
  }
}
KeyWhat it is for
commandThe command that starts the mocks. Here it starts three of them in one process, on one port each.
cwdThe directory the command runs in.
endpointsThe 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.

TargetWhat it does
makeList the targets.
make testThe local tests.
make pre-ciThe local tests — the step the CI depends on.
make ciThe local tests, then the CI gate.
make mocksStart the mocks, for a project to point at. The set is MOCKS, which defaults to stripe resend xero cloudflare paystack.
make composeStart the mocks as containers. make PROFILE=payments starts one group.
make dockerBuild 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.

← Architecture Offline testing →