Skip to content

README.md

Latest commit

 

History

History
275 lines (210 loc) · 6.19 KB

README.md

File metadata and controls

275 lines (210 loc) · 6.19 KB
Raw

🔌 mockr — Offline-First API Mock Engine

A single binary that reads your OpenAPI/GraphQL schema and instantly serves a realistic mock API — no internet required.

Why This Exists

Most dev environments assume stable internet. In India and many other countries, that assumption breaks constantly — during travel, power outages, or in areas with poor connectivity.

Frontend and mobile developers constantly need to test against backend APIs that aren't available offline. Existing tools fall short:

Tool Problem
WireMock Heavyweight, Java-based, needs JVM
MSW Browser-only, not CLI-native
Postman Mock Requires cloud + login
json-server No schema support, no GraphQL

mockr fills the gap: a single binary, zero dependencies, starts in under a second, works 100% offline.

Features

  • ✅ OpenAPI 3.x support — reads your openapi.yaml or openapi.json
  • ✅ GraphQL support — reads .graphql schema files
  • ✅ Hand-written YAML — define mocks without a full schema
  • ✅ Auto-generated responses — realistic fake data from schema types
  • ✅ Configurable latency — simulate slow networks
  • ✅ Error injection — randomly return 4xx/5xx to test resilience
  • ✅ Request logging — see every request hit in the terminal
  • ✅ CORS enabled by default — works with any frontend
  • ✅ Hot reload — edit schema, server updates instantly
  • ✅ Single binary — no Node, no Java, no Docker

Installation

Using Go

go install github.com/yourusername/mockr@latest

Pre-built Binary (Linux/macOS/Windows)

# Linux
curl -L https://github.com/yourusername/mockr/releases/latest/download/mockr-linux-amd64 -o mockr
chmod +x mockr
sudo mv mockr /usr/local/bin/

# macOS
brew install yourusername/tap/mockr

Quick Start

With an OpenAPI schema

mockr serve --schema openapi.yaml

With a GraphQL schema

mockr serve --schema schema.graphql --port 4000

With a hand-written YAML mock file

mockr serve --schema mocks.yaml

Your mock server is now live at http://localhost:8080.

Schema Formats

OpenAPI (YAML)

openapi: 3.0.0
info:
  title: Sample API
  version: 1.0.0
paths:
  /users:
    get:
      summary: Get all users
      responses:
        '200':
          description: A list of users
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/User'
components:
  schemas:
    User:
      type: object
      properties:
        id:
          type: integer
        name:
          type: string
        email:
          type: string
          format: email

Hand-written YAML (Simpler)

routes:
  - method: GET
    path: /users
    status: 200
    response:
      - id: 1
        name: Ravi Kumar
        email: ravi@example.com

  - method: POST
    path: /login
    status: 200
    response:
      token: "mock-jwt-token-xyz"

  - method: GET
    path: /orders/:id
    status: 200
    response:
      orderId: "{{params.id}}"
      status: delivered

GraphQL Schema

type Query {
  user(id: ID!): User
  users: [User]
}

type User {
  id: ID!
  name: String!
  email: String!
  createdAt: String!
}

CLI Reference

mockr [command] [flags]

Commands:
  serve       Start the mock server
  validate    Validate a schema file without serving
  generate    Generate a sample mock YAML from a schema

Flags for serve:
  --schema    Path to schema file (required)
  --port      Port to listen on (default: 8080)
  --latency   Add artificial latency in ms (e.g. --latency 300)
  --error-rate  Percentage of requests to fail (e.g. --error-rate 10)
  --watch     Enable hot reload on schema change
  --log       Log all incoming requests (default: true)
  --cors      Enable CORS headers (default: true)

Examples

# Serve with 300ms simulated latency
mockr serve --schema api.yaml --latency 300

# Randomly fail 20% of requests (resilience testing)
mockr serve --schema api.yaml --error-rate 20

# Watch for schema changes (hot reload)
mockr serve --schema api.yaml --watch

# Run on a custom port
mockr serve --schema api.yaml --port 3001

# Validate schema without starting server
mockr validate --schema api.yaml

Response Generation

When no explicit response is defined, mockr auto-generates realistic data from the schema:

Schema Type Generated Value
string Random word
string (email) user@example.com
string (uuid) Valid UUID v4
string (date) 2024-03-15
integer Random int
boolean true or false
array 2–5 generated items

Project Structure

mockr/
├── cmd/
│   └── mockr/
│       └── main.go          # CLI entry point
├── internal/
│   ├── server/              # HTTP/GraphQL server
│   ├── parser/              # OpenAPI + GraphQL + YAML parsers
│   ├── generator/           # Fake data generator
│   ├── middleware/           # Latency, error injection, logging
│   └── config/              # CLI flags and config
├── examples/
│   ├── openapi.yaml
│   ├── schema.graphql
│   └── mocks.yaml
├── go.mod
├── go.sum
└── README.md

Use Cases

  • 🧑‍💻 Hackathons — frontend and backend teams work in parallel without waiting on each other
  • ✈️ Travel — develop and test without airport/train WiFi
  • 🛑 Backend outages — frontend dev continues uninterrupted
  • 📱 Mobile dev in low-connectivity areas — test app behaviour on slow/no networks
  • 🧪 CI pipelines — spin up a mock server without real backend dependencies

Roadmap

  • WebSocket mock support
  • Response templating with Faker.js-style variables
  • UI dashboard to inspect requests
  • gRPC schema support
  • Export recorded real traffic as mock schema

Contributing

git clone https://github.com/yourusername/mockr.git
cd mockr
go mod tidy
go run ./cmd/mockr serve --schema examples/openapi.yaml