FAQ
Frequently asked questions about moclojer. Find quick answers to common installation, configuration, and usage questions.
Getting Started
What is moclojer?
moclojer is a simple and efficient HTTP mock server that helps you simulate APIs for development, testing, and prototyping. It uses YAML, EDN, or OpenAPI configuration files to define mock endpoints and their responses.
How is moclojer different from other mock servers?
Simple configuration - Uses familiar YAML syntax
Dynamic responses - Powerful template system for realistic mocks
Multiple formats - Supports YAML, EDN, and OpenAPI
WebSocket support - Real-time communication mocking
No programming required - Just configuration files
Clojure integration - Can be used as a library in Clojure applications
Do I need to know Clojure to use moclojer?
No! While moclojer is written in Clojure, you can use it entirely through YAML configuration files. Clojure knowledge is only needed if you want to use moclojer as a library in your own applications.
Installation
Which installation method should I choose?
Docker - Best for trying moclojer or containerized environments
JAR file - Good for CI/CD, scripts, or when you have Java installed
Native binary - Fastest startup, Linux only, no Java required
From source - For Clojure developers or contributors
I'm getting "Java not found" errors
moclojer requires Java 11 or higher. Install Java and ensure it's in your PATH:
Can I run moclojer without installing anything?
Yes! Use Docker:
The installation script fails with permission errors
On Linux/macOS, you might need sudo
:
Configuration
Where should I put my configuration file?
moclojer looks for configuration files in this order:
File specified with
--config
option./moclojer.yml
(current directory)~/.config/moclojer.yml
(user config directory)/etc/moclojer.yml
(system config)
Can I use JSON instead of YAML?
Currently, moclojer supports YAML, EDN, and OpenAPI formats. JSON support might be added in future versions. You can easily convert JSON to YAML using online tools.
How do I organize large configuration files?
Break your configuration into logical sections using YAML comments:
Can I include other files in my configuration?
Currently, moclojer doesn't support file includes, but you can:
Use external bodies to load response data from files
Combine multiple YAML files using tools like
yq
Use environment variables for dynamic configuration
Template Variables
My template variables show as empty strings
This usually happens when:
Parameter name doesn't match (check spelling and case)
Parameter isn't present in the request
JSON body is malformed
Debug by checking:
How do I access nested JSON properties?
Use dot notation:
Can I use template variables in headers?
Yes! Template variables work in response headers:
How do I handle array data?
Access array elements by index:
Why are my numbers showing as strings?
Make sure you don't put quotes around numeric template variables:
HTTP Methods and Status Codes
Can I use custom HTTP methods?
moclojer supports all standard HTTP methods (GET, POST, PUT, PATCH, DELETE, OPTIONS, HEAD). Custom methods might work, but aren't officially supported.
How do I return different status codes?
Use the status
field in your response:
Can I return the same endpoint with different status codes?
Create separate endpoint configurations for different scenarios:
Performance
How many requests can moclojer handle?
Performance depends on your system, but moclojer can typically handle hundreds of concurrent requests. For high-load testing, monitor CPU and memory usage.
Can I run multiple moclojer instances?
Yes! Run multiple instances on different ports:
Does moclojer cache responses?
moclojer doesn't cache responses by default - each request is processed fresh. This ensures template variables are always current.
How do I optimize for better performance?
Use simpler response bodies for high-volume endpoints
Minimize complex nested template variables
Consider using external bodies for large static responses
Monitor system resources during load testing
Advanced Features
How do I simulate slow APIs?
Currently, moclojer doesn't have built-in delay functionality. You can:
Use external tools like
tc
(traffic control) on LinuxAdd delays in your client code
Use a proxy with delay capabilities
Can I simulate authentication?
Yes! Use headers and conditional responses:
How do I mock file uploads?
moclojer receives file upload data, but currently doesn't provide special template variables for file content. You can access form data through the request body.
Can I use moclojer with HTTPS?
moclojer runs HTTP by default. For HTTPS:
Use a reverse proxy like nginx with SSL termination
Run moclojer behind a load balancer with SSL
Use Docker with SSL proxy containers
WebSockets
Do WebSockets work the same as HTTP endpoints?
WebSockets have their own configuration format:
Can I use template variables in WebSocket responses?
Yes! WebSocket responses support the same template variables as HTTP responses, plus the special {{message}}
variable for the received message.
How do I test WebSocket endpoints?
Use tools like:
websocat
command line toolBrowser developer tools
WebSocket testing applications like Postman
Troubleshooting
Moclojer starts, but I get "connection refused"
Check that:
moclojer is actually running (check terminal output)
You're using the correct port (default is 8000)
No firewall is blocking the connection
Another service isn't using the same port
My configuration file isn't being loaded
Verify:
File exists and is readable
YAML syntax is correct (use a YAML validator)
File path is correct when using
--config
No permission issues accessing the file
"Port already in use" error
Another service is using port 8000. Either:
Stop the other service
Use a different port:
PORT=3000 moclojer
Find what's using the port:
lsof -i :8000
(macOS/Linux)
Template variables aren't working
Common issues:
Typos in variable names
Using wrong parameter type (path-params vs query-params)
Malformed JSON in request body
Missing parameters in the request
Debug by adding a debug endpoint:
Configuration changes aren't reflected
moclojer loads configuration at startup. Restart the server after making changes:
Stop with Ctrl+C
Start again with the same command
Integration
Can I use moclojer in my test suite?
Yes! moclojer is excellent for testing:
How do I integrate with CI/CD pipelines?
Use Docker for consistent environments:
Can I generate OpenAPI specs from moclojer configs?
Currently, moclojer consumes OpenAPI specs but doesn't generate them. You can:
Write OpenAPI specs manually
Use tools to convert YAML to OpenAPI format
Generate documentation from your moclojer configurations using custom scripts
Getting Help
Where can I get more help?
How do I report a bug?
Create a minimal reproduction case
Include moclojer version, OS, and configuration details
Provide error messages and logs
How do I request a feature?
Start a discussion explaining your use case
Provide examples of how the feature would work
Explain why existing features don't meet your needs
Can I contribute to moclojer?
Setting up development environment
Code style guidelines
Pull request process
Ways to contribute beyond code
Last updated
Was this helpful?