Build a Fixture CLI for API Smoke Tests

API smoke tests get messy when every repo script invents fixture data in a slightly different way. A small fixture CLI gives your team one place to create ids, inboxes, trace tokens, and cleanup hints, which is way more useful then another pile of shell snippets.

Why smoke tests become noisy faster than unit tests

Unit tests usually fail close to the code that broke. Smoke tests fail across boundaries: the app, the queue, the inbox, the auth token, and whatever little wrapper script someone wrote three months ago and forgot about. That is why they feel random even when the root cause is not random at all.

I started treating fixture creation as a product surface, not just setup glue. Once I did that, the failure reports got easier to read and the repair loop got shorter. Teams that improve developer experience see a real delivery payoff too. In the 2024 GitHub Octoverse report, developer productivity and faster feedback loops stayed near the center of software team priorities GitHub Octoverse. A fixture CLI is a tiny move, but it supports that same goal.

The usual smells are pretty familiar:

• one script creates user-test-1 while another script expects a UUID
• CI retries create new resources but logs only the old identifier
• inbox polling code knows too much about the test runner
• cleanup is "best effort", which often means it is skipped

That is also where weird words like tempail and temp mailid end up in docs or commit messages. Not a disaster, but it shows the system is leaking details in a sloppy way.

The jobs a fixture CLI should own

My rule is simple: if a value must be unique, traceable, and reusable during the run, the CLI should generate it. Not the test file, not the workflow yaml, and not a random helper hidden in scripts/old/.

A good first version only needs a few commands:

fixtures scope create --suite smoke --env staging
fixtures inbox reserve --scope "$SCOPE"
fixtures trace print --scope "$SCOPE"
fixtures cleanup note --scope "$SCOPE"

That does not sound fancy, but it gives every run a stable contract. The CLI becomes the one boring place where naming rules live. Boring is great here, honestly.

I also like making the CLI print JSON so app tests, curl scripts, and GitHub Actions can all consume the same shape:

fixture_json="$(fixtures scope create --suite smoke --env staging --json)"
export FIXTURE_SCOPE="$(jq -r '.scope' <<<"$fixture_json")"
export TRACE_ID="$(jq -r '.trace_id' <<<"$fixture_json")"
export TEST_EMAIL="$(jq -r '.email' <<<"$fixture_json")"

Now the workflow, the API test, and the debug log all share one vocabulary. That saves time later when someone is diffing a failed run at 5:47 PM and just wants the answer, not a detective novel.

A tiny contract that keeps APIs debuggable

The contract I keep pushing is:

1. every smoke run gets one scope id
2. every externally visible resource includes that scope id
3. every failure message prints the scope id first

Here is the smallest useful shape:

{
  "scope": "smoke-184552-api",
  "trace_id": "trace-smoke-184552-api",
  "email": "[e-mail]",
  "cleanup_key": "cleanup-smoke-184552-api"
}

From there, your API checks can stay pretty lean:

curl -X POST "$API_BASE_URL/signup" \
  -H "x-trace-id: $TRACE_ID" \
  -H "content-type: application/json" \
  -d "{\"email\":\"$TEST_EMAIL\"}"

This also pairs nicely with email CI isolation tokens. The pattern is the same: make the run identity explicit, then pass it through everything that could get confused later.

One more thing that helps a lot: write the scope manifest to the job summary or artifact bundle. If a coworker can open the run and instantly see the scope, inbox, and trace id, debugging gets way less squishy. It sounds small, but it makes the whole system feel more intentional.

Where temporary email fits without taking over the stack

I would not build the whole fixture CLI around inbox handling. That is too narrow, and it tends to couple your test harness to one provider. But temporary email still belongs in the contract when the smoke test checks a real signup, password reset, or invite flow.

The trick is to keep mailbox handling as one subcommand, not the center of gravity:

fixtures inbox reserve --scope "$SCOPE" --provider sandbox

That keeps the architecture clean. The broader CLI still serves APIs and Automation use cases, even when a specific suite does not need an inbox at all.

If your team is already doing browser checks, the same manifest can support wrong-message email assertions without duplicating mailbox logic in Playwright helpers. I think that split ages better, because the inbox code stays replaceable and the scope contract stays stable.

Quick Q&A for teams adding this to CI

Do we need this for small services?

If the service has one smoke test and no async side effects, maybe not yet. But as soon as email, queues, or retries show up, the CLI starts paying rent pretty quick.

Should the CLI create fixtures and clean them too?

Usually yes, but do not block test output on perfect cleanup. Record cleanup metadata first, then let a later job or cron sweep leftovers. That model is more robust when a run crashes half way through.

What if our scripts already work?

That is fine, keep them. Just move the naming and manifest logic behind one command surface so every future script stops drifting. This sounds a bit pedantic, I know, but it saves a surprsing amount of energy.

The biggest win is not elegance. It is that when a smoke test fails, your team can answer "what resources did this run touch?" in about ten seconds. For a tool that takes maybe an afternoon to sketch, that is a pretty good trade.