moclojer

Simple and efficient HTTP mock server with specification written in yaml, edn, OpenAPI or Postman Collection.

💾 Download the .jar file with the latest version of moclojer to test on your computer here.

📖 See the complete documentation for moclojer here, if you want to contribute (or complement) the documentation, it is here.

YAML example

# This mock register route: GET /hello/:username
- endpoint:
    # Note: the method could be omitted because GET is the default
    method: GET
    path: /hello/:username
    response:
      # Note: the status could be omitted because 200 is the default
      status: 200
      headers:
        Content-Type: application/json
      # Note: the body will receive the value passed in the url using the
      # :username placeholder
      body: >
        {
          "hello": "{{path-params.username}}!"
        }

Postman Collection Support

Moclojer can directly use Postman Collection v2.1 exports as mock specifications. Simply export your Postman collection and use it:

# Using environment variable
CONFIG=my-collection.json moclojer

# Using CLI parameter
moclojer --config my-collection.json

How to export from Postman:

1. Open your Postman collection
2. Click the three dots menu → Export
3. Select "Collection v2.1" format
4. Save the JSON file
5. Use it directly with moclojer!

The converter automatically:

• Detects Postman Collection format
• Extracts HTTP methods, paths, and response examples
• Processes nested folders
• Converts path variables (:id, :username, etc.)
• Includes headers and status codes from examples

WebSocket Support

Moclojer also supports WebSocket connections with a simple configuration approach:

# WebSocket echo server
- websocket:
    path: /ws/echo
    on-connect:
      # Message sent when client connects
      response: '{"status": "connected", "message": "Welcome to WebSocket Echo!"}'
    on-message:
      # Simple echo for "ping" message
      - pattern: "ping"
        response: "pong"
      # Echo back any JSON content with an "echo" field
      - pattern: '{"echo": "{{json-params.echo}}"}'
        response: '{"echoed": "{{json-params.echo}}"}'

You can test the WebSocket connection using tools like websocat:

websocat "ws://localhost:8000/ws/echo" --text

docker

• image: ghcr.io/moclojer/moclojer:latest
• port (default): 8000, if you want to change the port set the environment variable PORT

docker run -it \
  -p 8000:8000 -v $(pwd)/moclojer.yml:/app/moclojer.yml \
  ghcr.io/moclojer/moclojer:latest

We have two versions available:

• dev: main branch docker image
• latest: latest stable version image

manual installation

We distribute via the .jar file, you need to have Java installed on your operating system.

bash < <(curl -s https://raw.githubusercontent.com/moclojer/moclojer/main/install.sh)

If you are using Linux you maybe need sudo.

CLI Usage

• clj -M:run [OPTIONS]
• java -jar moclojer.jar [OPTIONS]
• moclojer_Linux [OPTIONS]

Options

parameter	description
-c, --config	Config path or the CONFIG environment variable. [default: ~/.config/moclojer.yml]
-m, --mocks	OpenAPI v3 mocks path or the MOCKS environment variable.
-f, --format	Output and logging format. Either println or json.
-h, --help	Show help information
-v, --version	Show version information

sentry: set environment var SENTRY_DSN (sentry doc), automatic send backtrace to <sentry.io>

Config uses XDG_CONFIG_HOME to fetch the default moclojer configuration file, if you want to set a different directory you must use the -c or environment variable CONFIG

💻 dev environment

moclojer is written in Clojure, to run the commands below we assume you have clojure installed on your operating system.

run:

clj -M:run

test:

clj -M:test

if you want to run a specific test: clj -M:test -n com.moclojer.external-body.excel-test

moclojer.jar generate:

clj -A:dev -M --report stderr -m com.moclojer.build

AI-assisted development

This project includes an AGENTS.md file with guidelines for AI coding assistants (Claude Code, Cursor, GitHub Copilot, etc.). It documents architecture decisions, code patterns, extension points, and common pitfalls to help both humans and AI tools understand and contribute to the codebase effectively.

Windows users: This project uses symlinks for AI tool config files. Git on Windows disables symlinks by default. Enable them with git config --global core.symlinks true before cloning (may require Developer Mode or admin privileges).

framework integrations

We distribute the library via Clojars.

Clojure CLI/deps.edn

com.moclojer/moclojer {:mvn/version "0.3.1"}

Leiningen/Boot

[com.moclojer/moclojer "0.3.1"]

git in deps.edn

{:deps
 {com.moclojer/moclojer {:git/url "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/moclojer/moclojer.git"
                         :git/tag "v0.3.1"
                         :git/sha "c4ca0f2cfcfbe47de6eb0c601b26106190e20793"}}}

example of use

(ns my-app.core
  (:require [com.moclojer.adapters :as adapters]
            [com.moclojer.server :as server]))

(def *router
  "create a router from a config map"
  (adapters/generate-routes
   [{:endpoint
     {:method "GET"
      :path "/example"
      :response {:status 200
                 :headers {:Content-Type "application/json"}
                 :body {:id 123}}}}]))

(defn -main
  "start the server"
  [& args]
  (server/start-server! *router))