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"}'

➜ Scenario examples

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