README
¶
Unimock - Universal HTTP Mock Server
Mock any HTTP service for testing. Works with REST, GraphQL, XML, or any HTTP API.
Quick Start
# 1. Run with Docker
docker run -p 8080:8080 ghcr.io/bmcszk/unimock:latest
# 2. Test it
curl -X POST http://localhost:8080/api/users \
-H "Content-Type: application/json" \
-d '{"id": "123", "name": "John Doe"}'
curl http://localhost:8080/api/users/123
Configuration
Create config.yaml with the unified format:
sections:
users:
path_pattern: "/api/users/*"
body_id_paths: ["/id"]
header_id_names: ["X-User-ID", "Authorization"] # Multiple headers supported
return_body: true
orders:
path_pattern: "/api/orders/*"
body_id_paths: ["/order_id"]
header_id_names: ["X-Order-ID"]
➜ Copy-paste examples | Full config guide
Scenarios
Pre-define responses for testing:
sections:
users:
path_pattern: "/api/users/*"
body_id_paths: ["/id"]
scenarios:
- uuid: "user-not-found"
method: "GET"
path: "/api/users/999"
status_code: 404
content_type: "application/json"
data: '{"error": "User not found"}'
Installation
| Method | Command | Use Case |
|---|---|---|
| Docker | docker run -p 8080:8080 ghcr.io/bmcszk/unimock |
Quick testing |
| Helm (Registry) | helm install unimock oci://ghcr.io/bmcszk/charts/unimock |
Production |
| Local Build | make build && ./unimock |
Development |
| Go Library | import "github.com/bmcszk/unimock/pkg" |
Embed in apps |
Key Features
✅ Universal - Works with any HTTP service (REST, XML, GraphQL)
✅ Smart ID extraction - From URLs, JSON, XML, or multiple headers
✅ Scenarios - Fixed responses for testing edge cases
✅ Thread-safe - Handles concurrent requests
✅ Simple config - Single YAML file
Quick Reference
| Task | Command/Config |
|---|---|
| Run | docker run -p 8080:8080 ghcr.io/bmcszk/unimock |
| Configure | Edit config.yaml with sections and scenarios |
| Health | GET /_uni/health |
| Metrics | GET /_uni/metrics |
| POST test | curl -X POST :8080/api/users -d '{"id":"1"}' |
| GET test | curl :8080/api/users/1 |
Examples
- Simple Examples - Copy-paste configurations
- Unified Format - Sections + scenarios in one file
- Library Usage - Go library integration example
- Legacy Format - Traditional format (still supported)
Environment Variables
UNIMOCK_PORT- Server port (default: 8080)UNIMOCK_LOG_LEVEL- Log level (default: info)UNIMOCK_CONFIG- Config file path (default: config.yaml)
Common Use Cases
- API Testing - Mock external services in integration tests
- Development - Work offline without real API dependencies
- Error Testing - Simulate API failures and edge cases
- Load Testing - Fast, predictable responses
Documentation
📖 Configuration Guide - Complete config reference
📖 Scenarios Guide - Pre-defined responses
📖 Examples - Usage examples
📖 Go Library - Embed in applications
📖 Deployment - Production deployment
Development
git clone https://github.com/bmcszk/unimock.git
cd unimock
make build # Build binary
make test # Run tests
make check # Full validation
License
MIT License - see LICENSE
Documentation
¶
Overview ¶
Unimock is a universal HTTP mock server for end-to-end testing. It can mock any HTTP-based service with flexible configuration.
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
examples
|
|
|
library
command
|
|
|
internal
|
|
|
client
Package client provides an HTTP client for interacting with Unimock APIs and mock endpoints.
|
Package client provides an HTTP client for interacting with Unimock APIs and mock endpoints. |
|
config
Package config provides configuration structures for the Unimock server.
|
Package config provides configuration structures for the Unimock server. |
|
model
Package model provides data structures for Unimock's HTTP mocking and scenarios.
|
Package model provides data structures for Unimock's HTTP mocking and scenarios. |