MockSmith

Zero-config stateful mock server and network chaos sandbox that turns OpenAPI specs into live relational REST backends with real-time browser telemetry.

Comment

MockSmith — Instant Stateful Mock Backend & Network Chaos Sandbox

Inspiration

Every frontend and mobile developer has experienced the "backend blocker" dilemma: building a feature against an API that is still under development, unstable in staging, or restricted by rate limits.

Existing solutions often fall into two extremes:

  • Static Mock Servers (e.g., Prism and generic JSON mocks) return rigid, stateless payloads. Updates do not persist, deletions do not affect related lists, and creating an order does not establish relationships with users.
  • Heavyweight Emulators and Mock Handlers (e.g., MSW and LocalStack) often require extensive boilerplate, manual lifecycle management, or resource-intensive Docker environments.

Real-world networks introduce another challenge. Flaky mobile connections, microservice timeouts, and API rate limits can break applications in ways that developers rarely encounter during local development.

We asked ourselves:

Why can't developers simply drop an OpenAPI YAML/JSON file into their terminal and instantly get a live, relational, stateful REST backend with a built-in network chaos sandbox?

That question led us to build MockSmith.

What It Does

MockSmith is a zero-configuration, local-first stateful mock server and network chaos sandbox designed to eliminate backend dependencies during development.

1. Instant API Ingestion

  • Supports OpenAPI 3.0, OpenAPI 3.1, Swagger 2.0, and raw JSON collections.
  • Resolves nested $ref components.
  • Handles polymorphic oneOf and anyOf schemas with discriminator mappings.
  • Automatically generates RESTful CRUD routes (GET, POST, PUT, PATCH, DELETE).
  • Schema parsing and route generation complete in under 20 milliseconds.

2. Relational In-Memory Database

MockSmith provides an in-memory relational store without native dependencies.

  • Automatically infers primary keys and foreign key relationships (e.g., userId → users.id).
  • Supports relational queries such as /users/1/posts.
  • Maintains persistent state throughout the server session.
  • Supports cascade deletions.
  • Provides advanced URL filtering operators: _gte, _lte, _gt, _lt, _ne, and _like.

3. Network Chaos Sandbox

Simulate unreliable production environments directly from your development machine.

  • Dynamically configure request latency.
  • Inject Gaussian-distributed network jitter.
  • Configure randomized HTTP fault injection, including 400, 401, 403, 404, 429, 500, and 503 responses.
  • Configure custom authentication headers on the fly.

4. Zero-Dependency Web Studio

MockSmith includes an embedded, responsive dashboard accessible at /_mocksmith.

Features include:

  • Live HTTP traffic monitoring through Server-Sent Events (SSE).
  • Visual database table inspectors.
  • Interactive record editors.
  • Real-time network chaos configuration sliders.

No additional frontend framework or separate dashboard installation is required.

5. Contract Diff Diagnostics

When client applications send request bodies that violate the API contract, MockSmith returns detailed 400 Bad Request diagnostics.

Instead of receiving a generic validation error, developers can identify exactly which properties are missing or have incorrect types.

How We Built It

MockSmith is engineered from the ground up in TypeScript with strict mode enabled, following an event-driven, zero-native-dependency architecture.

SchemaParser Engine

A custom TypeScript parser traverses complex OpenAPI document trees, infers schema types, resolves polymorphic discriminators, and synthesizes complete CRUD route tables.

FakerLite Heuristic Generator

We implemented a deterministic, semantic mock data generator.

Using field-name heuristics such as email, avatar, timestamp, currency, and uuid, it generates realistic contextual data without relying on bloated external dependencies.

RelationalStore Memory Core

An index-driven relational store enables O(1) record lookups.

Cascade deletion is implemented through foreign-key dependency graphs:

Cascade(T, id) = { r ∈ T | r.fk_id = id }

This allows related records to be automatically removed when their parent record is deleted.

Chaos Interceptor Middleware

Network latency and jitter are modeled using normal distribution approximations:

L = μ_delay + N(0, σ_jitter²)

Fault injection is controlled probabilistically:

P(Fault) = p_chaos

This allows developers to reproduce different network conditions without modifying their application code.

Interactive Web Studio

The dashboard is implemented using vanilla HTML5, CSS Grid, and EventSource SSE listeners.

Its frontend assets are embedded directly into the application, with a standalone browser-based demo also available through GitHub Pages.

Challenges We Ran Into

Polymorphic Discriminator Resolution

Real-world OpenAPI 3.1 schemas, including those found in large APIs such as Stripe and GitHub, frequently use oneOf, anyOf, and discriminator mappings.

Generating valid mock payloads that satisfy the correct variant schemas without entering infinite recursion was challenging.

We addressed this with a circular-reference-guarded schema traversal algorithm.

Maintaining a True Zero-Dependency Architecture

Many mock servers rely on large npm packages or native binary bindings.

We deliberately avoided heavy native extensions to ensure cross-platform portability across macOS, Linux, and Windows, while maintaining sub-20ms cold-start performance.

Cross-Platform Demo Recording

Automating our video demonstration using edge-tts and Playwright exposed upstream WebSocket handshake changes, including 403 Sec-MS-GEC errors.

We resolved these issues by investigating protocol headers and pinning compatible runtime dependencies.

Accomplishments That We're Proud Of

Performance

  • Achieved 0.8 ms P99 response latency across relational CRUD operations.
  • API schema parsing and route generation complete in under 20 ms.
  • Designed for near-instant startup without heavyweight dependencies.

Testing

Built and successfully passed:

  • 43 automated Vitest unit tests.
  • 21 real-world benchmark integration tests.
  • 14 Playwright headless Firefox end-to-end tests.

All 78 automated tests passed.

Ready-to-Run Industry Templates

MockSmith includes four pre-packaged scenarios:

  1. E-Commerce Multi-Vendor
  2. Petstore Swagger 3.0
  3. Social Network & Geo
  4. Chaos Resilience Sandbox

Templates can be loaded through the --template CLI option or directly from the Web Studio.

Browser-Based Sandbox

We also built a fully client-side GitHub Pages demo that runs the MockSmith engine directly in the browser, without requiring users to deploy or configure a backend server.

What We Learned

  • OpenAPI 3.1 introduces significant JSON Schema differences compared with OpenAPI 3.0, particularly around type arrays and discriminator property mappings.
  • Developer tools need to prioritize simplicity. Developers should not need to configure a 50-line YAML file just to test how their application handles an error response.
  • Immediate visual feedback through sliders, live database tables, and one-click snapshots can significantly accelerate development workflows.
  • A useful mock backend needs to simulate application state and relationships, not just return predefined JSON responses.

What's Next for MockSmith

We plan to extend MockSmith beyond REST API development:

GraphQL & gRPC Gateway Emulation

Expand schema ingestion to support GraphQL SDL and Protocol Buffers definitions.

WebSocket & Webhook Chaos Simulation

Introduce scheduled and event-driven webhook callbacks, alongside simulated network packet loss and connection failures.

IDE Integration

Develop VS Code and JetBrains extensions to embed the MockSmith Web Studio and network chaos controls directly into developers' workflows.

Our long-term goal is to make realistic backend simulation as easy as running a local development server.

Built With

Share this project:

Updates

Submission history