jimjam

Crates.iojimjam
lib.rsjimjam
version0.0.2
created_at2026-01-20 13:18:40.270613+00
updated_at2026-01-20 13:30:29.86496+00
descriptionA configurable HTTP mock server with YAML-defined responses
homepagehttps://github.com/michaelmccabe/jimjam
repositoryhttps://github.com/michaelmccabe/jimjam
max_upload_size
id2056532
size108,919
Michael McCabe (michaelmccabe)

documentation

https://docs.rs/jimjam

README

jimjam 🎭

A configurable HTTP mock server that serves responses based on YAML-defined rules. Perfect for API mocking, testing, and development.

Features

  • YAML-based configuration - Define mock responses in simple YAML files
  • Multiple response scenarios - Define different responses for the same endpoint based on conditions
  • Path parameters - Support for dynamic URL segments like /users/{id}
  • Response delays - Simulate slow APIs with configurable delays
  • File-based bodies - Load large response bodies from external files

Quick Start

Build

cargo build --release

Run

cargo run

The server starts on http://127.0.0.1:8080 by default.

Test

curl http://127.0.0.1:8080/api/health
# → {"status": "ok", "service": "jimjam"}

Configuration

Main Config (config/config.yaml)

# jimjam main configuration

server:
  host: "127.0.0.1"
  port: 8080

# Location of mock response definition files
mock_files:
  directory: "./mocks"
  patterns:
    - "**/*.yaml"
    - "**/*.yml"
  hot_reload: true

mocks:

  • path: "/api/users/{id}" id: "1" status: 200 {"id": 1, "name": "Alice"}

    Fallback response (no conditions)

Condition Description Example
path_params Match URL path parameters id: "123"
query_params Exact query parameter match sort: "asc"
query_contains Query string substring "category=books"
headers Exact header match Authorization: "Bearer token"
header_contains Header substring Authorization: "Bearer"
body_contains Body substring '"role": "admin"'
body_json JSON field match name: "test"
body_regex Regex pattern '"email":\\s*".*@test\\.com"'

Response Options

- status: 201                    # HTTP status code
  headers:                       # Response headers
    Content-Type: "application/json"
    X-Custom-Header: "value"
  body: |                        # Inline response body
    {"created": true}
  body: "@./data/large.json"     # Or use @ prefix to load from file
  body_file: "./data/large.json" # Alternative: explicit file reference
  delay_ms: 2000                 # Simulate slow response

Body Content Options

  1. Inline body - Write content directly in YAML

    body: '{"name": "example"}'

  2. File reference with @ - Prefix path with @ (recommended)

    body: "@./mocks/data/users.json"

  3. Explicit body_file - Use separate field

    body_file: "./mocks/data/users.json"

Directory Structure

jimjam/
├── config/
│   └── config.yaml       # Server configuration
├── mocks/
│   ├── users.yaml        # User API mocks
│   ├── products.yaml     # Product API mocks
│   └── data/
│       └── products.json # Large response bodies
└── src/
    └── ...

Running Tests

cargo test

How jimjam works

See how-jimjam-works.md for schema, matching, and advanced usage.

Commit count: 12

cargo fmt