Self-host WireMock and Hurl on VPS for API tests
Run WireMock mocks and Hurl API tests on your VPS: keep stubs in git, execute suites in CI, and preserve reports after Docker rebuilds.
Two jobs wey share one repository
Self-hosted API mocking and testing na two different jobs, and if you treat dem as one, you fit waste one week. Mock server dey stand in for dependency wey you no fit call from CI: payment provider, partner API, rate limited upstream, or service wey another team never release. API test runner dey call your own endpoints in fixed order and check the responses, carrying values from one response enter the next request.
Some tools fit do both jobs. Mock server main job na to answer requests. Test runner no get opinion about wetin payment provider go return when card decline. Most teams wey already dey rent one server end up running one of each. Same Docker Compose file go start dem, and dem go review both inside the same pull request.
Why self-host API mocking and testing?
Your fixtures na production-shaped data. Request body for API test fit be real customer record wey person just change the name, or wey nobody change because nobody check am. Recorded stubs worse: proxy recording stores anything wey upstream actually return, so stub directory wey recording build fit hold live tokens and customer email addresses until person read every file. For hosted service, that data go become another person incident and your data disclosure.
The second reason na reachability. Service wey bind to private address need private network connection before hosted runner fit reach am. Every workaround get cost. If you publish the API to internet so you fit test am, you don remove the reason why e dey private. Tunnel or public staging copy na another system wey you must maintain, and staging copy go drift from production between releases. GitHub-hosted runners still support private access through WireGuard overlay or Azure Virtual Network. Runner wey dey the same private network fit call the service directly and no need any of those things. Na this practical reason dey behind self-hosted GitHub Actions runner.
Which self-hosted mock server you suppose run?
Each one dey run as a container for server wey you own. The important question be wetin each one dey treat as the source of truth. This one decide whether rebuilding the container go cost you nothing or take your whole afternoon.
- WireMock dey keep every stub as JSON file for
mappings/directory, while e dey keep large response bodies for__files/. The image nawiremock/wiremock, and the root directory inside the container na/home/wiremock. E fit also run as recording proxy. When files dey disk, the mock fit live for git like any other code. - Mockoon CLI dey keep one complete mock API for one JSON data file. Install am with
npm install -g @mockoon/cliand start am withmockoon-cli start --data ./data-file.json, or run themockoon/cliimage with that file bind mounted. The desktop app dey edit the same file, so you fit design for UI and commit the result without compatibility wahala. - MockServer dey run from the
mockserver/mockserverimage and dey listen on port 1080. Expectations dey enter through its own REST API, wey useful from test code but risky for deployment. By default, any expectation wey HTTP call create go disappear when the container restart. Use its JSON initialization file for stubs wey suppose permanent. To keep runtime changes, enablepersistExpectations, save the output file outside the container, and load am throughinitializationJsonPathwhen startup happen. - Prism dey build the mock from your OpenAPI document instead of separate stub files. Install am with
npm install -g @stoplight/prism-cli, then runprism mock openapi.yaml. Inside container, add-h 0.0.0.0, because Prism dey bind to localhost by default and otherwise e no go reachable from outside the container. - Microcks na the big option: e get web UI wey dey import OpenAPI documents and Postman collections, then serve dem as mocks and run contract tests. Full installation need MongoDB and Keycloak, plus Kafka for async features. The all in one
microcks-uberimage bundle an in-memory MongoDB, and the project document say e suit ephemeral use. So treat anything wey you create for that UI as disposable, and keep the source artifacts for git.
Which self-hosted API test runner you suppose run?
The work here na sequence: authenticate, create an order, read am back, assert say the state don change. E need one value wey you capture from one response and use for the next request. Tool wey no fit carry state between calls na health check, no be API test.
- Hurl dey run plain text files of HTTP requests from one binary. One
[Captures]section dey pull values from response, one[Asserts]section dey check dem, and--testturn am into test runner with summary and exit code. Version 8.0.1 na current as of August 2026. - Bruno CLI dey run folder of
.brufiles. Install am withnpm install -g @usebruno/cli, then runbru run folder --env Local --reporter-junit results.xml. The collection format na text files inside directory by design, so the diffs dey easy to read during review. - Newman dey run Postman collections outside Postman:
npm install -g newman, thennewman run collection.json -r cli,junit --reporter-junit-export results.xml. The issue na the format. Newman dey run exported collections for v2.1 JSON format. Postman now support v3 collection format and Native Git workflows through Postman CLI too. Postman docs talk say Newman no go get any more updates or fixes, and dem advise make you migrate scripts and CI pipelines go Postman CLI. - Schemathesis na different kind check. E dey read OpenAPI schema and generate cases wey try produce responses wey your schema talk say no suppose happen:
uvx schemathesis run https://your.api/openapi.json. E dey find crashes and contract violations, but e no know anything about your business rules, so e suppose sit beside scripted suite instead of replacing am. - Hoppscotch self hosted na the web UI option, and e require Postgres instance. Understand this tradeoff before you install am: collections dey live for database, no be for your repository.
One wey you suppose avoid. Step CI still dey show for tool roundups and the YAML workflow format dey read well, but the repository last receive commit for August 2024. Program wey dey between your CI and your API no be good place for code wey dem no dey maintain.
Firewall dey protect mock server
The setup below dey run WireMock as replacement for payment provider. If compose file format new to you, Docker Compose for VPS explain the lifecycle commands wey this section assume.
services:
mock-payments:
image: wiremock/wiremock:3.13.2
command: ["--verbose"]
volumes:
- ./mocks/payments:/home/wiremock
ports:
- "127.0.0.1:8080:8080"
restart: unless-stoppedThe 127.0.0.1: prefix for the port na the important part. Plain 8080:8080 go publish the mock for every interface, including your public IP. E go still remain reachable even when ufw dey deny that port, because Docker dey route published traffic through nat table before e reach ufw INPUT rules. Bind am to loopback address so only the host fit access the published port with Docker default bridge networking for Engine 28.0.0 or later. Older releases allow hosts for the same layer 2 network to reach ports published to localhost. Binding to private interface address still allow access from networks wey fit route to that address.
Your service wey you dey test go then point to the mock. When the service dey run for the same compose project, the mock base URL na http://mock-payments:8080, because compose dey resolve service names for its own network. When the service dey run on the host, na http://127.0.0.1:8080. Set am through environment variable, never put am for code, otherwise the test URL fit ship to production.
Put stubs for ./mocks/payments/mappings/, one JSON file for each stub.
{
"request": {
"method": "POST",
"urlPath": "/v1/charges",
"bodyPatterns": [{ "matchesJsonPath": "$.amount" }]
},
"response": {
"status": 201,
"headers": { "Content-Type": "application/json" },
"jsonBody": { "id": "ch_test_001", "status": "succeeded", "amount": 4200 }
}
}Start am, then check wetin actually load.
docker compose up -d --wait mock-payments
curl -fsS http://127.0.0.1:8080/__admin/mappings--wait dey wait until the container report say e healthy. E work because the WireMock image ships with HEALTHCHECK against its /__admin/health endpoint. The mappings call list every stub wey the server read. If stub wey you write no dey that list, the server never load am: check say the file dey under mappings/, not inside the mounted root, and check say the JSON parse correctly.
When request arrive and no stub match am, WireMock answer 404. If e find near match, the body start with Request was not matched, then e show diff against the closest stub. If no stub mappings dey, the body na No response could be served as there are no stub mappings in this WireMock instance.. Read the diff when e dey before you change anything, because e name the exact field wey differ. Most times, na path with /v1/charge where the stub talk say /v1/charges.
Write the test as a sequence with state carried between calls
Hurl files na plain text. Install the deb from the project's releases.
VERSION=8.0.1
curl --location --remote-name https://github.com/Orange-OpenSource/hurl/releases/download/$VERSION/hurl_${VERSION}_amd64.deb
sudo apt update && sudo apt install ./hurl_${VERSION}_amd64.debA suite wey dey test your own API against the mock dey inside tests/checkout.hurl.
POST {{base_url}}/orders
Content-Type: application/json
{
"sku": "ssd-1tb",
"amount": 4200
}
HTTP 201
[Captures]
order_id: jsonpath "$['id']"
GET {{base_url}}/orders/{{order_id}}
HTTP 200
[Asserts]
jsonpath "$.status" == "paid"
jsonpath "$.charge_id" == "ch_test_001"The [Captures] block na wetin make this an API test instead of two unrelated requests. order_id dey read from the first response and interpolate into the URL of the second one. The assertion on charge_id na the main purpose of the whole exercise: e prove say your service call the payment provider and store wetin come back, and the value e compare against na the one you write inside the WireMock stub. One file now cover both sides of the flow.
hurl --test --variable base_url=http://127.0.0.1:3000 \
--report-junit reports/junit.xml \
--report-json reports/json \
tests/When the run pass, e print one line for each file and one summary.
tests/checkout.hurl: Success (2 request(s) in 61 ms)
Executed files: 1
Executed requests: 2 (30.1/s)
Succeeded files: 1 (100.0%)
Failed files: 0 (0.0%)
Duration: 64 msWhen e fail, e print error: Assert failure with the file and line number, then the value wey e get against the value wey e expect, and hurl exit non zero so CI go stop. If status read pending where you expect paid, your service no process the mock response. The next thing to check na the WireMock request journal for /__admin/requests, wey show whether the call reach the mock at all.
Run the suite from your own CI runner
If runner dey registered for the same box, the workflow short. Runner na ordinary process for the host, so docker and hurl must dey installed for that host. E no inherit anything from hosted image.
name: api-tests
on: [push]
jobs:
hurl:
runs-on: self-hosted
steps:
- uses: actions/checkout@v4
- name: Start the mock
run: docker compose up -d --wait mock-payments
- name: Run the suite
run: hurl --test --variable base_url=http://127.0.0.1:3000 --report-junit reports/junit.xml tests/
- name: Archive the reports
if: always()
run: install -d /srv/api-tests/reports/$GITHUB_SHA && cp -r reports/. /srv/api-tests/reports/$GITHUB_SHA/
- name: Stop the mock
if: always()
run: docker compose downif: always() for the archive step dey important. If you no add am, failed test run go skip the copy, so you go lose the exact report wey you wan read. The copy must also enter outside the workspace, because actions/checkout@v4 dey run git clean -ffdx by default before e fetch, and this removes untracked reports from the repository directory for the next checkout.
Keep the results, no be only the last run
One JUnit XML file for each commit fit answer one question: e pass? E no answer when endpoint start slowing down, because nothing dey read those files after you stop opening dem. For trend, append one row for each run to small database for the same box. One table wey hold the commit SHA, file name, pass count, fail count, and duration dey enough. SQLite for production on a VPS na reasonable place to keep am: na one file, e no need server process, and the complete history go dey inside the backup wey you already dey take. Parse Hurl --report-json output to get detailed run data; both JSON and JUnit XML dey machine readable.
Wetin suppose survive container rebuild
Mock definitions and test suites na source code. Dem suppose dey inside repository beside the service wey dem describe, and na the same pull request wey change endpoint suppose change dem. If you edit stub for web UI, or push expectation go MockServer through REST API during runtime, you need export or persistence setup make dem survive rebuild. Run docker compose down and container memory plus writable layers go loss; data wey dey inside bind mounts or named volumes go survive. If una dey run repositories for una own hardware too, a self-hosted git server go keep fixtures and service inside one trust boundary.
Now, make we look practical rules. Pin image tags, because latest fit change how your mock dey match requests without any change for your repository, and e hard well-well to connect that failure back to the cause. Mount stub directories as read only when the tool no need write to dem. Never put mock stubs inside named Docker volume, because the volume go become source of truth and the copy for git go silently become wrong.
One more thing fit catch people. If you build stubs by recording real traffic through proxy, read every generated file before you commit am. Recording contains exactly wetin upstream send back, including bearer tokens and customer email addresses. If you commit am, e go remain permanently for your repository, because git dey keep deleted content for history.
FAQ
API mock server and API test runner get what difference?
Mock server dey answer requests. E dey stand in for dependency wey you no fit call from CI; some tools still dey run contract tests and report their results. API test runner dey send requests go your own service, check whether responses match wetin you expect, carry values from one call enter the next one, and exit with non zero when assertion fail. Dem solve different problems, and normal setup dey run both together: runner dey call your service while your service dey call the mock.
I fit test internal API from hosted CI runner?
Yes, if private networking dey available. GitHub-hosted runners support WireGuard overlay or Azure Virtual Network to reach private resources without publishing the API. Publishing the API, running a tunnel, or maintaining public staging copy na other options, and each one add another system wey fit fail or leak data. Runner wey dey the same private network fit call the service directly. Na this be the main practical reason teams dey self host this work.
Where mock stubs and API test suites suppose dey?
For git, beside the service wey dem describe. Tools wey store definitions as files, like WireMock's mappings/ directory, Mockoon's data file, Hurl files, and Bruno's .bru folder, give you code review and container rebuild wey no cost anything. Tools wey store definitions for database or web UI need backup plan and export step. Na the export people dey forget until container don already disappear.
Why my mock dey return 404 when the stub look correct?
WireMock go serve stub only when request satisfy the matchers wey you configure. Request wey no match go get 404; when near match dey, body go start with Request was not matched, then follow with diff against the closest stub. That diff go name the field wey differ. If no stub mappings dey, body go instead explain say the instance get none. Common causes include trailing slash for the path, Content-Type header wey stub require but your client no send, urlPath used where stub need urlPathPattern for variable segment, and body matcher wey no fit the payload. Check /__admin/requests first to confirm say request reach the mock at all.
I still need mocks if I get staging environment?
Yes, for two reasons. Staging copy of upstream wey you no control fit still go down and still rate limit you, so your suite fit fail for reasons wey no relate to your code. E still no fit produce the responses wey you most need to test, like declined card or gateway timeout. Mock fit return those responses whenever you request am, at local network speed. This one turn suite wey dey take minutes against sandbox into one wey dey take seconds. Keep staging for final check before release, and use mocks for CI.