Recipes

Validate Mocks in CI

When a team shares mocks, a broken HCL file or a duplicated route should never reach the running server. This recipe keeps the mocks in a dedicated repository, validates every pull request with mocko validate, and packages the approved mocks as a Docker image ready to deploy.

The mocks repository

The whole repository is a mocks folder, a Dockerfile, and a workflow:

my-team-mocks/
├── mocks/
│   ├── users.hcl
│   ├── orders.hcl
│   └── payments/
│       └── refunds.hcl
├── Dockerfile
└── .github/
    └── workflows/
        └── validate.yaml

Validating pull requests

mocko validate checks the folder without starting a server and exits non-zero when a mock is broken, so wiring it into CI is one step:

name: Validate mocks
on:
  pull_request:

jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 22
      - run: npx --yes @mocko/cli@latest validate mocks --strict

The report groups problems by file and explains how to fix each one, so a failing check reads like a code review comment. The workflow runs with --strict, so warnings also fail the check, like paths that look like Express-style :param parameters; drop the flag if you only want hard errors to block a merge. The full list of checks is in the CLI reference.

You can run the same command locally before pushing:

$npx @mocko/cli@latest validate mocks

Shipping the mocks as an image

With validation gating merges, the main branch is always deployable. Bake the mocks into an image on top of the official ones. For a Kubernetes deployment with Helm, build on the core image:

FROM ghcr.io/mocko-app/core:2
COPY mocks/ /var/mocks/

For Docker Compose, the standalone image also bundles the control panel UI:

FROM ghcr.io/mocko-app/standalone:2
COPY mocks/ /var/mocks/

Pin the base image to the :2 tag and install the CLI with @latest. Both track the current major version, so the validator in CI always matches the server the mocks will run on.

Why not validate at startup?

The running server is deliberately forgiving: a broken file is skipped with a warning so one bad mock never takes down the rest. That is the right behavior in development, but in a shared repository it hides mistakes. mocko validate applies the strict interpretation of the same rules:

HCL files that fail to parse fail validation instead of being ignored
Mocks with invalid definitions or duplicated routes fail instead of being skipped
Template bodies that fail to compile fail instead of responding 500 at runtime