Automating API Mocks in Your CI Pipeline with proxymock

When running tests in a CI/CD pipeline, relying on external APIs can introduce instability, slow down execution, and even lead to failed builds due to rate limits or API downtime. Fortunately proxymock provides a solution by capturing API interactions and running a local mock server, enabling fully isolated and repeatable tests.

In this blog, we’ll demonstrate how to integrate proxymock into a GitHub Actions CI pipeline using a demo app called outerspace-go. This app makes calls to the Numbers API and SpaceX API, and we’ll show how proxymock can capture these calls and replay them locally during automated tests.

You can watch the video version of this tutorial:

Overview of the outerspace-go App

outerspace-go is a Go-based application that fetches data from external APIs:

• The Numbers API provides fun facts about numbers.
• The SpaceX API delivers the latest SpaceX launch data.

By default, running the app will query these APIs directly, but we will configure proxymock to capture and replay these requests for testing purposes.

Why Use proxymock in CI Pipelines?

When running tests in CI/CD, external API dependencies can be problematic:

• Unreliable availability: The API might be down or rate-limited.
• Slow performance: API calls introduce latency into test runs.
• Inconsistent data: Live APIs may return different responses over time.

Using proxymock in CI allows us to:

• Capture real API responses once and replay them consistently.
• Run tests quickly without waiting for network requests.
• Ensure our tests are independent of external services.

Setting Up proxymock Locally

To start using proxymock, install it and record API calls:

Installation

For your MacOS environment it’s as simple as using brew.

brew install speedscale/tap/proxymock

Or download it manually.

Initialize

If this is the first time you’re running you can initialize from your command line:

proxymock init
                         _               _
 ___ _ __   ___  ___  __| |___  ___ __ _| | ___
/ __| '_ \ / _ \/ _ \/ _` / __|/ __/ _` | |/ _ \
\__ \ |_) |  __/  __/ (_| \__ \ (_| (_| | |  __/
|___/ .__/ \___|\___|\__,_|___/\___\__,_|_|\___|
    |_|
Welcome to Speedscale! Preparing your installation...
Choose one:
 [1] Need to sign up
 [2] Have an API key
 [3] Have an account but no API key
 [q] Quit
▸ How do you want to initialize the cli? [q]: 1
▸ Enter your email to sign up:

Recording API Calls

1. Start proxymock in record mode, and make a note of the ID for the snapshot recording that is created.

   proxymock record

2. Run the outerspace-go application while proxymock captures the outgoing API requests:

   export http_proxy=http://localhost:4140
   export https_proxy=http://localhost:4140
   go run main.go

3. Now run some test transactions against the application and you’ll see some traffic recorded:

   curl http://localhost:4143/
   curl http://localhost:4143/api/numbers
   curl http://localhost:4143/api/latest-launch

4. Once you’re done hit CTRL-C on your proxymock window to save your data locally. Now you can browse the data in a local web UI with this command

   proxymock web --in .

Replaying API Calls:

To use the recorded API responses instead of making live calls:

proxymock mock --in ./proxymock --no-passthrough

This starts a mock server that returns the recorded responses whenever the app makes requests.

For your go code to talk to the mock server, simply add these environment variables, note that this will configure a forward proxy to the proxymock running locally and listening on port 4140.

export http_proxy=http://localhost:4140
export https_proxy=http://localhost:4140

Now when you invoke your code, it will make downstream calls to the mock APIs, providing consistent, repeatable responses.

Integrating proxymock into GitHub Actions

To use proxymock in GitHub Actions, we:

1. Install proxymock in the pipeline.
2. Use the recorded mocks to serve API responses.
3. Run tests against the mock server.

Example GitHub Actions Workflow:

name: CI Pipeline
on: [push, pull_request]
jobs:
  test-and-build-go:
    runs-on: ubuntu-latest
    permissions:
      contents: read
    steps:
    - name: Check out the application and recordings
      uses: actions/checkout@v4
    - name: Setup proxymock
      env:
        PROXYMOCK_API_KEY: ${{ secrets.PROXYMOCK_API_KEY }}
      run: make proxymock-setup
    - name: Run proxymock
      run: make proxymock-run
    - name: Run tests with proxymock
      run: make test-with-proxymock

You can see the full details in the GitHub Actions overview:

Conclusion

Using proxymock in your CI pipeline ensures that your tests remain stable, fast, and independent of external API availability. By capturing and replaying API interactions, you can create reliable and repeatable test environments that eliminate downtime risks and performance bottlenecks.

By integrating proxymock into your GitHub Actions workflow, you gain:

• Faster test execution by avoiding network latency.
• More reliable builds that aren’t affected by third-party API failures.
• Easier debugging with recorded API interactions.

Try it out with the outerspace-go demo and explore how proxymock can enhance your CI/CD workflow!

Resources:

• outerspace-go GitHub Repo
• proxymock quick start docs
• proxymock website

Frequently asked questions

How do I authenticate proxymock in a headless runner?

Store a Speedscale API key in the CI platform’s secret store and initialize with proxymock init --api-key "$SPEEDSCALE_API_KEY" --yes --no-rcfile-update. Use a runner variable rather than committing the key or an initialized configuration. Check the account’s CI licensing requirements; an LLM provider key and a proxymock API key serve different purposes.

How should a failed replay fail the pipeline?

Make the replay’s exit status part of the job result. Define explicit --fail-if conditions or compare against a saved baseline with --baseline and --fail-on-new-mismatch. Preserve the replay report for diagnosis. Avoid --exit-zero, swallowing failures with shell logic, or rebuilding the baseline from the same candidate that the job is meant to check.

When should I refresh the committed recordings?

Refresh them when an intentional contract change, a new workflow, or a real integration check shows that fixtures are stale. Review the recording diff and baseline changes together. Re-recording merely to make a failing candidate pass can erase a regression. Keep sensitive data out of shared fixtures and resolve environment-specific secrets at runtime.

Sources: proxymock installation, proxymock in CI, Replay verdicts and gates, Regression testing with a baseline, Runtime secret references.