Stand in for a third-party API your app calls
Set your app's base URL for the outside API to http://127.0.0.1:8000/mock and add one Buggregator mock rule per call: method and path in, status, headers and body out. Your app then gets your answers instead of the vendor's sandbox. Every call is stored with what the app sent and what came back, so you also see the request your code builds.
Steps
1. Write the rules in buggregator.yaml
Rule paths have no /mock prefix. {id} matches one path segment. This file is for Buggregator, not for your app.
# buggregator.yaml
mocks:
- name: create charge
method: POST
path: /v1/charges
status: 201
headers: { Content-Type: application/json }
body: '{"id": "ch_1", "status": "succeeded"}'
- name: get charge
method: GET
path: /v1/charges/{id}
headers: { Content-Type: application/json }
body: '{"id": "ch_1", "status": "succeeded"}'2. Start Buggregator with the file
Buggregator reads buggregator.yaml from the folder it starts in. In the image that is /.
docker run --pull always \
-p 127.0.0.1:8000:8000 \
-v ./buggregator.yaml:/buggregator.yaml \
ghcr.io/buggregator/server:latest3. Change the base URL in your app
Use whatever setting your API client reads for its base URL. In Docker Compose, replace 127.0.0.1 with the Buggregator service name, for example buggregator.
# your app's .env
PAYMENTS_API_URL=http://127.0.0.1:8000/mockCheck one rule by hand:
curl -X POST http://127.0.0.1:8000/mock/v1/charges
# {"id": "ch_1", "status": "succeeded"}4. Add failures and slow answers
Make a rule that answers 500 or 429 to see how your app handles errors. delay (up to 30s) tests timeouts. Add rules from a script or a test through the REST API:
curl -X POST http://127.0.0.1:8000/api/mocks \
-H 'Content-Type: application/json' \
-d '{"method": "POST", "path": "/v1/refunds", "status": 429, "body": "{\"error\": \"rate limited\"}", "delay_ms": 2000}'5. Read what your app sent
Open http://127.0.0.1:8000, then Mock server. On the left are the rules in match order, on the right the calls, live. Click a call to see the request and the response that was sent. A call with no rule gets 404 with {"error": "no mock rule matched ..."}, and its details list the rules that almost matched and why.
Why it works
Buggregator answers every request under /mock/ with the first enabled rule that matches its method and path. Rules from buggregator.yaml come first and stay the same on every start, which suits CI. Each call is also stored as an HTTP dump, so the request your code built sits next to your logs and exceptions.
Docs: docs.buggregator.dev/config/mock-server.html#use-cases
Requires Buggregator v2.6.0+
Related tips
- Mock server
A working mock API from your OpenAPI spec
Import an OpenAPI 3 spec into Buggregator. Every operation becomes a mock rule with the spec's example or fake data, served under /mock.
- Mock server
A mock API that returns new fake users on every call
Turn on template for a Buggregator mock rule and fill the body with fake names and emails. New data on each call, or the same data with a seed.
- HTTP
See every API call your Laravel app sends
Set global proxy options for Laravel's HTTP client in AppServiceProvider. Every Http:: request and response shows up in Buggregator. Local only.
- HTTP
Test the webhooks your app sends, on your machine
Point your app's webhook URL at Buggregator with http-dump as the user name. See each webhook's headers, signature and body, and send it again with cURL.
Checked on with Buggregator v2.13.0