Reality-First Onboarding
Pillars: [Reality]
[Reality] - Everything that makes mocks feel like a real, evolving backend
Keep mocks aligned with your API
Realistic data helps most when a mock still matches the API it represents.
The unreleased verify-mocks --mock-spec comparison reports changed routes and
field-level contract differences between a mock’s OpenAPI definition and its
current source. Add a fresh recorder capture to check observed upstream traffic,
and use --fail-on-drift to make differences visible in CI.
Start with the Mock Fidelity and Drift Detection guide.
Start Here If…
You care about realism. You want mocks that feel indistinguishable from production backends, with realistic data, stateful behavior, and production-like network conditions.
Perfect for:
- Frontend teams needing realistic data that evolves over time
- Testing resilience and failure scenarios
- Simulating production-like network conditions
- Creating believable mock backends before real APIs exist
Quick Start: 5 Minutes
Let’s create a realistic mock API with Smart Personas and Reality Continuum:
# Install MockForge
cargo install mockforge-cli
# Create a simple config with reality features
cat > mockforge.yaml <<EOF
workspaces:
- name: realistic-api
reality:
level: 3 # Moderate Realism
personas:
enabled: true
endpoints:
- path: /api/users/{id}
method: GET
response:
body: |
{
"id": "{{persona.user.id}}",
"name": "{{persona.user.name}}",
"email": "{{persona.user.email}}"
}
EOF
# Start the server
mockforge serve --config mockforge.yaml
Now test it:
# Request the same user ID multiple times - persona ensures consistency
curl http://localhost:3000/api/users/123
curl http://localhost:3000/api/users/123 # Same user data!
Key Reality Features
1. Reality Continuum
Blend mock and real data seamlessly:
reality:
continuum:
enabled: true
blend_ratio: 0.5 # 50% mock, 50% real
upstream_url: https://api.example.com
Why it matters: Develop against a backend that’s still under construction by gradually transitioning from mock to real.
Learn more: Reality Continuum Guide
2. Smart Personas
Generate consistent, relationship-aware data across endpoints:
reality:
personas:
enabled: true
entities:
- type: user
fields:
- name: id
generator: uuid
- name: email
generator: email
- type: order
relationships:
- field: user_id
links_to: user.id
Why it matters: Maintain data consistency across your entire mock API. When you request a user and their orders, the relationships are preserved.
Learn more: Smart Personas Guide
3. Reality Slider
Adjust realism levels on the fly:
reality:
level: 3 # 1=Static, 2=Light, 3=Moderate, 4=High, 5=Production Chaos
Why it matters: Instantly transform your mock environment to match different testing scenarios without manual configuration.
Learn more: Reality Slider Guide
4. Chaos Lab
Simulate network conditions and failures:
chaos:
enabled: true
latency:
mean_ms: 200
std_dev_ms: 50
failures:
error_rate: 0.05 # 5% of requests fail
status_codes: [500, 502, 503]
Why it matters: Test how your application handles real-world network conditions and failures.
Learn more: Chaos Lab Guide
5. Temporal Simulation
Time travel and time-based data mutations:
time_travel:
enabled: true
virtual_clock: true
scheduled_responses:
- time: "2025-01-01T00:00:00Z"
endpoint: /api/events
response: {...}
Why it matters: Test time-dependent features, scheduled events, and data evolution over time.
Learn more: Time Travel Guide
Next Steps
Explore Reality Features
-
Reality Continuum: Complete Guide
- Learn about blend ratios and merge strategies
- Configure time-based progression
- Set up fallback handling
-
Smart Personas: Complete Guide
- Create persona graphs with relationships
- Configure lifecycle states
- Understand fidelity scores
-
Reality Slider: Complete Guide
- Understand reality levels
- Configure hot-reload
- Coordinate chaos, latency, and AI
-
Chaos Lab: Complete Guide
- Configure latency profiles
- Set up failure injection
- Simulate network conditions
-
Temporal Simulation: Complete Guide
- Use virtual clocks
- Schedule time-based responses
- Test time-dependent features
Related Pillars
Once you’ve mastered Reality, explore these complementary pillars:
-
[Contracts] - Add validation and drift detection to ensure your realistic mocks stay in sync with real APIs
-
[DevX] - Improve your workflow with SDKs, generators, and developer tools
-
[AI] - Enhance realism with AI-powered data generation
Examples
Example 1: Realistic E-Commerce API
workspaces:
- name: ecommerce
reality:
level: 4 # High Realism
personas:
enabled: true
entities:
- type: user
- type: product
- type: order
relationships:
- field: user_id
links_to: user.id
- field: product_id
links_to: product.id
endpoints:
- path: /api/users/{id}
method: GET
response:
body: |
{
"id": "{{persona.user.id}}",
"name": "{{persona.user.name}}",
"orders": "{{persona.user.orders}}"
}
Example 2: Production-Like Testing
reality:
level: 5 # Production Chaos
chaos:
enabled: true
latency:
distribution: normal
mean_ms: 300
std_dev_ms: 100
failures:
error_rate: 0.02
status_codes: [500, 502, 503, 504]
Troubleshooting
Personas Not Working
Ensure personas are enabled in your config:
reality:
personas:
enabled: true
Reality Continuum Not Blending
Check your upstream URL and blend ratio:
reality:
continuum:
enabled: true
blend_ratio: 0.5
upstream_url: https://api.example.com # Must be accessible
Chaos Not Injecting
Verify chaos is enabled and configured:
chaos:
enabled: true
latency:
mean_ms: 200
Resources
Ready to dive deeper? Continue to the Reality Continuum Guide or explore all Reality features.