Frequently Asked Questions (FAQ)

Quick answers to common questions about MockForge.

MockForge is a comprehensive multi-protocol mocking framework for APIs. It allows you to create realistic mock servers for HTTP/REST, gRPC, WebSocket, and GraphQL without writing code. Perfect for frontend development, integration testing, and parallel team development.

Is MockForge free?

Yes, MockForge is completely free and open-source under MIT/Apache-2.0 licenses. There are no premium tiers, paid features, or usage limits.

What protocols does MockForge support?

MockForge supports:

HTTP/REST: OpenAPI/Swagger-based mocking with full validation
gRPC: Dynamic service discovery from .proto files with HTTP Bridge
WebSocket: Replay mode, interactive mode, and AI event generation
GraphQL: Schema-based mocking with automatic resolver generation

How does MockForge compare to WireMock, Mockoon, or MockServer?

See our detailed comparison table in the README. Key differentiators:

Multi-protocol in a single binary
AI-powered mock generation and data drift
WASM plugin system for extensibility
gRPC HTTP Bridge for REST access to gRPC services
Built-in encryption for sensitive data
Rust performance with native compilation
Multi-language SDKs - Native support for 6 languages vs WireMock’s Java-first approach

For detailed ecosystem comparison, see Ecosystem Comparison Guide.

Can I use MockForge in production?

Yes! MockForge is production-ready with:

Comprehensive test coverage
Security audits
Performance benchmarks
Docker deployment support
Observability (Prometheus metrics, tracing)

However, it’s primarily designed for development and testing. For production API mocking, ensure proper security configurations.

Getting Started

How do I install MockForge?

Three options:

# 1. From crates.io (requires Rust)
cargo install mockforge-cli

# 2. From source
git clone https://github.com/SaaSy-Solutions/mockforge
cd mockforge && make setup && make install

# 3. Using Docker
docker pull ghcr.io/saasy-solutions/mockforge:latest

See the Installation Guide for details.

What’s the fastest way to get started?

Follow our 5-Minute Tutorial:

cargo install mockforge-cli
mockforge init my-project
mockforge serve --config mockforge.yaml
Test with curl

Do I need to know Rust to use MockForge?

No. MockForge is a CLI tool you can use without Rust knowledge. You only need Rust if:

Building from source
Developing custom plugins
Embedding MockForge as a library

What programming languages are supported?

MockForge provides native SDKs for 6 languages:

Rust - Native SDK with zero-overhead embedding
Node.js/TypeScript - Full TypeScript support
Python - Context manager support with type hints
Go - Idiomatic Go API
Java - Maven/Gradle integration
.NET/C# - NuGet package

All SDKs support embedded mock servers in your test suites. See SDK Documentation for examples.

Can I use MockForge from Python/Node.js/Go/etc.?

Yes! MockForge provides native SDKs for multiple languages. You can embed mock servers directly in your test code:

Python:

from mockforge_sdk import MockServer

with MockServer(port=3000) as server:
    server.stub_response('GET', '/api/users/123', {'id': 123})
    # Your test code here

Node.js:

import { MockServer } from '@mockforge-dev/sdk';

const server = await MockServer.start({ port: 3000 });
await server.stubResponse('GET', '/api/users/123', { id: 123 });

Go:

server := mockforge.NewMockServer(mockforge.MockServerConfig{Port: 3000})
server.Start()
defer server.Stop()

See Ecosystem & Use Cases Guide for complete examples in all languages.

How do I create my first mock API?

# 1. Initialize a project
mockforge init my-api

# 2. Edit the generated mockforge.yaml
vim mockforge.yaml

# 3. Start the server
mockforge serve --config mockforge.yaml

# 4. Test it
curl http://localhost:3000/your-endpoint

Or use an existing OpenAPI spec:

mockforge serve --spec your-api.json

Configuration & Setup

How do I configure MockForge?

Three ways (in order of priority):

CLI flags: mockforge serve --http-port 3000
Environment variables: export MOCKFORGE_HTTP_PORT=3000
Config file: mockforge serve --config config.yaml

See the Configuration Guide and Complete Config Template.

Where should I put my configuration file?

MockForge looks for config files in this order:

Path specified with --config
MOCKFORGE_CONFIG_FILE environment variable
./mockforge.yaml or ./mockforge.yml in current directory
Auto-discovered in parent directories

Can I use environment variables for all settings?

Yes! Every config option can be set via environment variables using the MOCKFORGE_ prefix:

export MOCKFORGE_HTTP_PORT=3000
export MOCKFORGE_ADMIN_ENABLED=true
export MOCKFORGE_RESPONSE_TEMPLATE_EXPAND=true

How do I validate my configuration?

mockforge config validate
mockforge config validate --config my-config.yaml

See the Configuration Validation Guide.

Why does my hosted mock return 401 when I change it with curl?

Hosted mocks protect MockForge’s management API. Writes to /__mockforge/* and the other MockForge control routes (creating mocks, chaos, time travel, the recorder) need the deployment’s management token. Open the deployment on the Hosted Mocks page, press Reveal next to Management token, and send it as a header:

curl -X POST https://<your-mock>/__mockforge/api/mocks \
  -H 'X-MockForge-Management-Token: mfm_...' \
  -H 'content-type: application/json' \
  -d '{"id":"hello","method":"GET","path":"/hello","response":{"body":{"hi":true}}}'

Reads (the spec, route list, docs, live stream) and your mocked API itself don’t need the token. Self-hosted mockforge serve doesn’t use one.

OpenAPI & HTTP Mocking

Can I use Swagger/OpenAPI specs?

Yes! Both OpenAPI 3.0 and Swagger 2.0 are supported:

mockforge serve --spec openapi.json
mockforge serve --spec swagger.yaml

MockForge automatically generates mock endpoints from your specification.

How does request validation work?

Three modes:

off: No validation (accept all requests)
warn: Log validation errors but accept requests
enforce: Reject invalid requests with 400/422

MOCKFORGE_REQUEST_VALIDATION=enforce mockforge serve --spec api.json

Why aren’t my template variables working?

Template expansion must be explicitly enabled:

# Via environment
export MOCKFORGE_RESPONSE_TEMPLATE_EXPAND=true

# Via config
http:
  response_template_expand: true

This is a security feature to prevent accidental template processing.

What template variables are available?

{{uuid}}          - Random UUID v4
{{now}}           - Current timestamp (ISO 8601)
{{now+2h}}        - Timestamp 2 hours from now
{{now-30m}}       - Timestamp 30 minutes ago
{{randInt 1 100}} - Random integer 1-100
{{rand.float}}    - Random float
{{faker.email}}   - Fake email address
{{faker.name}}    - Fake person name
{{request.body.field}}   - Access request data
{{request.path.id}}      - Path parameters
{{request.header.Auth}}  - Request headers

See the Templating Reference for complete details.

Can I override specific endpoints?

Yes! Define custom routes in your config that override OpenAPI spec:

http:
  openapi_spec: api.json
  routes:
    - path: /custom/endpoint
      method: GET
      response:
        status: 200
        body: '{"custom": "response"}'

gRPC Mocking

Do I need to compile my proto files?

No. MockForge dynamically parses .proto files at runtime. Just:

Put .proto files in ./proto directory
Start MockForge: mockforge serve --grpc-port 50051
Services are automatically discovered and mocked

How do I access gRPC services via HTTP?

Enable the HTTP Bridge:

grpc:
  dynamic:
    enabled: true
    http_bridge:
      enabled: true
      base_path: "/api"

Now access gRPC services as REST APIs:

# gRPC
grpcurl -d '{"id": "123"}' localhost:50051 UserService/GetUser

# HTTP (via bridge)
curl -X POST http://localhost:8080/api/userservice/getuser \
  -d '{"id": "123"}'

Can I use gRPC reflection?

Yes, it’s enabled by default:

# List services
grpcurl -plaintext localhost:50051 list

# Describe a service
grpcurl -plaintext localhost:50051 describe UserService

Does MockForge support gRPC streaming?

Yes, all four streaming modes:

Unary (single request → single response)
Server streaming (single request → stream of responses)
Client streaming (stream of requests → single response)
Bidirectional streaming (stream ↔ stream)

WebSocket Mocking

How do I create WebSocket replay files?

Use JSON Lines (JSONL) format:

{"ts":0,"dir":"out","text":"Welcome!","waitFor":"^CLIENT_READY$"}
{"ts":100,"dir":"out","text":"{{uuid}}"}
{"ts":200,"dir":"in","text":"ACK"}

ts: Milliseconds timestamp
dir: “in” (received) or “out” (sent)
text: Message content (supports templates)
waitFor: Optional regex/JSONPath pattern

See WebSocket Replay Mode.

Can I match JSON messages?

Yes, use JSONPath in waitFor:

{"waitFor": "$.type", "text": "Matched type field"}
{"waitFor": "$.user.id", "text": "Matched user ID"}

See README-websocket-jsonpath.md.

What’s AI event generation?

Generate realistic WebSocket event streams from narrative descriptions (for example, “Simulate 5 minutes of stock trading”). This is currently exposed as a library API (AiEventGenerator and WebSocketAiConfig in the mockforge-ws crate); there are no mockforge serve flags for it yet.

Perfect for testing real-time features without manually scripting events.

AI Features

Do I need an API key for AI features?

Not necessarily. Three options:

Ollama (Free, Local): No API key needed

ollama pull llama2
mockforge serve --ai-enabled --rag-provider ollama

OpenAI (Paid): ~$0.01 per 1,000 requests

export MOCKFORGE_RAG_API_KEY=sk-...
mockforge serve --ai-enabled --rag-provider openai

Anthropic, or OpenAI-compatible APIs: Similar to OpenAI

What are AI features used for?

Intelligent Mock Generation: Generate responses from natural language prompts
Data Drift Simulation: Realistic data evolution (order status, stock levels, etc.)
AI Event Streams: Generate WebSocket event sequences from narratives

See AI_DRIVEN_MOCKING.md.

How much does AI cost?

Ollama: Free (runs locally)
OpenAI GPT-3.5: ~$0.01 per 1,000 requests
OpenAI GPT-4: ~$0.10 per 1,000 requests
Anthropic Claude: Similar to GPT-4

Use Ollama for development, OpenAI for production if needed.

Plugins

How do I install plugins?

# From URL
mockforge plugin install https://example.com/plugin.wasm

# From Git with version
mockforge plugin install https://github.com/user/plugin#v1.0.0

# From local file
mockforge plugin install ./my-plugin.wasm

# List installed
mockforge plugin list

Can I create custom plugins?

Yes! Plugins are written in Rust and compiled to WebAssembly:

Use mockforge-plugin-sdk crate
Implement plugin traits
Compile to WASM target
Install and use

See the Plugin Development Guide and Add a Custom Plugin Tutorial.

Are plugins sandboxed?

Yes. Plugins run in a WebAssembly sandbox with:

Memory isolation
CPU/memory limits
No network access (unless explicitly allowed)
No file system access (unless explicitly allowed)

See Plugin Security Model.

Admin UI

How do I access the Admin UI?

The Admin UI runs on its own port:

mockforge serve --admin --admin-port 9080
# Access: http://localhost:9080

Use mockforge admin to run the Admin UI as a standalone server without starting the mock servers.

Is authentication available?

Yes. The Admin UI uses JWT login with three roles: Admin (full access), Editor (manage mocks and fixtures), and Viewer (read-only). Mutating admin endpoints are permission-checked per role; read-only GET /__mockforge/* endpoints stay open so the TUI can poll them.

Without JWT_SECRET, MockForge seeds local development users (admin / admin123, editor / editor123, viewer / viewer123). Set JWT_SECRET and MOCKFORGE_DISABLE_DEV_SEED_USERS=true for shared deployments. OAuth/SSO login is not available in the local Admin UI; MockForge Cloud supports OIDC and SAML SSO.

What can I do in the Admin UI?

View real-time request logs (via Server-Sent Events)
Monitor performance metrics
Manage fixtures with drag-and-drop
Configure latency and fault injection
Search requests and logs
View server health and statistics

See Admin UI Walkthrough.

Deployment

Can I run MockForge in Docker?

Yes:

# Using Docker Compose
docker-compose up

# Using Docker directly
docker run -p 3000:3000 -p 9080:9080 mockforge

See DOCKER.md for complete documentation.

How do I deploy to Kubernetes?

Use the Helm chart or create Deployment/Service manifests:

# Using Helm (if available)
helm install mockforge ./charts/mockforge

# Or use kubectl
kubectl apply -f k8s/statefulset.yaml

What ports does MockForge use?

Default ports:

3000: HTTP server
3001: WebSocket server
50051: gRPC server
4000: GraphQL server
9080: Admin UI
9090: Prometheus metrics

All ports are configurable.

Performance & Limits

How many requests can MockForge handle?

Typical performance (modern hardware):

HTTP: 10,000+ req/s
WebSocket: 1,000+ concurrent connections
gRPC: 5,000+ req/s

Performance depends on:

Response complexity
Template expansion
Validation enabled
Hardware specs

See our benchmarks.

Does MockForge scale horizontally?

Yes. Run multiple instances behind a load balancer:

# Instance 1
mockforge serve --http-port 3000

# Instance 2
mockforge serve --http-port 3001

# Load balancer distributes traffic

For stateless mocking (no shared state), this works great.

What are the resource requirements?

Minimal:

Memory: ~50MB base + ~10MB per 1,000 concurrent connections
CPU: 1-2 cores sufficient for most workloads
Disk: ~100MB for binary + storage for logs/fixtures

Troubleshooting

Server won’t start - port already in use

# Find what's using the port
lsof -i :3000

# Use a different port
mockforge serve --http-port 3001

Template variables appear literally in responses

Enable template expansion:

MOCKFORGE_RESPONSE_TEMPLATE_EXPAND=true mockforge serve --spec api.json

Validation rejecting valid requests

Adjust validation mode:

MOCKFORGE_REQUEST_VALIDATION=warn mockforge serve --spec api.json  # or 'off'

WebSocket connection fails

Check the WebSocket port and replay file:

# Verify port
netstat -tlnp | grep :3001

# Check replay file exists
ls -la ws-replay.jsonl

Admin UI not loading

Verify the admin UI is enabled and port is correct:

mockforge serve --admin --admin-port 9080
curl http://localhost:9080

For more issues, see the Troubleshooting Guide.

Development & Contributing

Can I embed MockForge in my application?

Yes! Use MockForge crates as libraries:

#![allow(unused)]
fn main() {
use mockforge_http::build_router;
use mockforge_core::{ValidationOptions, Config};

let router = build_router(
    Some("api.json".to_string()),
    Some(ValidationOptions::enforce()),
    None,
).await;
}

See the Rust API Documentation.

How do I contribute to MockForge?

Check CONTRIBUTING.md
Look for “good first issue” labels
Fork, make changes, submit PR
Ensure tests pass: cargo test
Follow code style: cargo fmt && cargo clippy

Where can I report bugs?

GitHub Issues

Please include:

MockForge version
Operating system
Configuration file (if applicable)
Steps to reproduce
Expected vs actual behavior
Error logs

Is there a community forum?

GitHub Discussions: Community Forum
GitHub Issues: Bug Reports & Feature Requests
Discord: Join our community chat

Hosted MockForge instances
Custom plugins
Support services
Training/consulting

Use Cases

What use cases does MockForge support?

MockForge supports a wide range of use cases:

Unit Tests - Embed mock servers directly in test suites across all supported languages
Integration Tests - Test complex multi-service interactions with stateful mocking
Service Virtualization - Replace external dependencies with mocks using proxy mode
Development Environments - Create local development environments without backend dependencies
Isolating from Flaky Dependencies - Simulate network failures and slow responses
Simulating APIs That Don’t Exist Yet - Generate mocks from API specifications before implementation

See Ecosystem & Use Cases Guide for detailed examples and code samples.

Can I use MockForge for unit testing?

Yes! MockForge SDKs allow you to embed mock servers directly in your unit tests:

Rust:

#![allow(unused)]
fn main() {
let mut server = MockServer::new().port(0).start().await?;
server.stub_response("GET", "/api/users/123", json!({"id": 123})).await?;
}

Python:

with MockServer(port=0) as server:
    server.stub_response('GET', '/api/users/123', {'id': 123})

No separate server process required. See SDK Documentation for examples.

How do I replace external APIs in my tests?

Record traffic with the API Flight Recorder, then convert the recordings into replayable fixtures:

# Record interactions into a SQLite database
mockforge serve --spec api.json --recorder --recorder-db ./recordings.db

# Convert recordings into fixtures
mockforge recorder convert --input ./recordings.db --output fixtures/ --format yaml

Or use the SDK to programmatically stub responses. See Service Virtualization for details.

Can I simulate network failures and slow responses?

Yes! MockForge provides built-in latency and fault injection:

# Add latency
mockforge serve --chaos --chaos-latency-ms 500

# Inject failures
mockforge serve --chaos --chaos-http-errors 500,503 --chaos-http-error-probability 0.1

Or configure in your SDK:

const server = await MockServer.start({
  latency: { mode: 'normal', meanMs: 500 },
  failures: { enabled: true, failureRate: 0.1 }
});

See Isolating from Flaky Dependencies for examples.

How do I mock an API that doesn’t exist yet?

Generate mocks from API specifications:

# From OpenAPI spec
mockforge serve --spec api-spec.yaml

# From GraphQL schema
mockforge serve --graphql schema.graphql

# From gRPC proto files (loaded from ./proto in the working directory)
mockforge serve --grpc-port 50051

All endpoints are automatically available with schema-validated responses. See Simulating APIs That Don’t Exist Yet for details.

What’s Next?

Ready to start? Try our 5-Minute Tutorial!

Need more help?

MockForge Documentation