A lightweight mock REST server for frontend developers and API designers. Define endpoints, match rules, and responses in YAML or via the built-in browser UI. Single binary. No runtime dependencies.
mockery is a standalone mock HTTP server that lets you define REST API endpoints and their responses declaratively. You can configure it in two ways:
- Browser UI (
mockery ui) — a visual editor to build endpoints, cases, and responses - YAML config (
mockery serve --config mockery.yaml) — version-controlled, CI-friendly configuration
Each endpoint can have multiple cases with priority-ordered match rules (auth token, query params, headers, JSON body fields). The first matching case wins, making it easy to simulate different API behaviors for different request scenarios.
- Visual Configuration — Browser-based UI to create and manage endpoints without writing YAML
- YAML-First — Store config in version control, share across teams, deploy to CI
- Request Matching — Match by auth token, query parameters, request headers, and JSON body fields (gjson paths)
- Priority-Ordered Cases — Lower priority number = evaluated first; perfect for catch-all fallbacks
- Response Latency Simulation — Simulate real-world network delay per case
- CORS Support — Built-in CORS configuration for frontend development
- Import / Export YAML — Round-trip between UI and config files
- Single Static Binary — No runtime dependencies; just download and run
- Cross-Platform — Pre-built binaries for macOS (Intel & Apple Silicon), Linux, and Windows
Grab the latest binary for your platform from the GitHub Releases page.
# macOS (Apple Silicon)
curl -L -o mockery https://github.com/prabhatdotdev/mockery/releases/latest/download/mockery-darwin-arm64
chmod +x mockery
# Linux
wget https://github.com/prabhatdotdev/mockery/releases/latest/download/mockery-linux-amd64 -O mockery
chmod +x mockerygo install github.com/prabhatdotdev/mockery@latest./mockery --version
# mockery version v0.1.0Launch the browser-based configuration UI and mock server manager.
./mockery uiThen open http://localhost:4000 in your browser.
Workflow:
- Set the server port and API prefix
- Add endpoints with path, method, and description
- For each endpoint, add cases with match rules and responses
- Click Start Server to run the mock API
- Test with
curlor your frontend app - Export YAML to save your configuration
Run the mock server directly from a YAML configuration file.
./mockery serve --config mockery.example.yamlOverride the server port from the command line:
./mockery serve --config mockery.example.yaml --port 9090
version: "0.1.0" # config format version
server:
port: 8080 # port the mock server listens on (1-65535)
prefix: /api # path prefix prepended to all endpoint routes
cors:
enabled: true # enable CORS headers
origins: # allowed origins; ["*"] allows everything
- "http://localhost:3000"
- "http://localhost:5173"
latency:
min: 50 # minimum artificial delay in milliseconds
max: 200 # maximum artificial delay in milliseconds
auth:
enabled: true # enable bearer-token authentication
header: Authorization # request header to inspect
scheme: Bearer # token prefix (e.g. "Bearer")
tokens:
- value: admin-secret-token # raw token string
label: admin # logical name used in case match rules
- value: readonly-secret-token
label: readonly
endpoints:
- id: get-users # unique endpoint identifier
path: /users # route path (appended to server.prefix)
method: GET # HTTP method: GET, POST, PUT, PATCH, DELETE, OPTIONS, HEAD
description: List all users # human-readable summary
cases: # ordered list of match/response rules
- id: admin-users # unique case identifier
name: Admin user list # human-readable case name
priority: 1 # lower number = evaluated first
match:
auth: admin # require token labelled "admin"
query: # regex match against URL query params
role: "^admin$"
response:
status: 200 # HTTP response status code
headers: # response headers
Content-Type: application/json
body: # JSON response body
users:
- id: 1
name: Alice
role: admin
- id: 2
name: Bob
role: admin
- id: catch-all-users # fallback case (no match rules)
name: Catch-all
priority: 99
match: {}
response:
status: 401
headers:
Content-Type: application/json
body:
error: unauthorized
- id: create-user
path: /users
method: POST
description: Create a new user
cases:
- id: admin-create
name: Admin create user
priority: 1
match:
auth: admin
body: # gjson path -> regex match on JSON body
'$.role': "admin"
response:
status: 201
headers:
Content-Type: application/json
body:
id: 3
name: Charlie
role: admin| Field | Type | Example | Notes |
|---|---|---|---|
| auth | token label | admin |
matches Auth.Tokens[].label |
| query | key: regex | role: "^admin$" |
URL query param |
| headers | key: regex | X-Trace: ".*" |
request header |
| body | gjson path: regex | $.user.role: "admin" |
JSON body, uses tidwall/gjson paths |
Cases are evaluated in ascending priority order. The first matching case wins. Use an empty match: {} with a high priority number as a catch-all fallback.
| Command | Description | Flags |
|---|---|---|
serve |
Run the mock server from a YAML file | --config, -c (required), --port, -p |
ui |
Launch the browser-based config UI | --port, -p (default: 4000), --config |
Use --help on any command for full flag details:
./mockery serve --help
./mockery ui --help# Clone the repository
git clone https://github.com/prabhatdotdev/mockery.git
cd mockery
# Build everything (frontend + Go binary)
make build
# Run tests
go test ./...
# Run locally
./bin/mockery ui- Pull requests are welcome
- Run
go test ./...before submitting - Frontend development:
cd web && npm run dev - Full build:
make build