Posted on

🚀 HttpPlaygroundServer — A Lightweight Local HTTP Test Server

When you’re developing C# code that calls external HTTP APIs, you quickly run into a familiar problem: testing and debugging these calls locally isn’t as simple as it should be. You can mock HttpMessageHandler, but that won’t show you what your code is actually sending over HTTP. You can spin up a real API or mock server, but that usually means extra frameworks, configuration, or infrastructure.

HttpPlaygroundServer exists to fill that gap. It’s a small, file-driven local HTTP server you can run during development to see real requests and control the responses your code receives.

What HttpPlaygroundServer Does

HttpPlaygroundServer listens on a local port and handles requests in a predictable way:

  • It logs each request into a folder structure based on the URL path.
  • Logs include the full URI, headers, and body in clean JSON format.
  • It returns responses from JSON files you place inside corresponding Responses folders.
  • You can switch to alternate responses by passing ?respFile= in the query string.

That’s the entire model. No routing rules, DSLs, or server configuration files. Everything revolves around folders and JSON.

Who This Is Useful For

  • Developers building client libraries or SDKs
  • Teams consuming external APIs
  • QA/integration testers needing predictable HTTP responses
  • Anyone diagnosing issues involving HTTP formatting or serialization
  • Developers working in environments where the real backend is unavailable or unstable

Why Use It

1. You see the actual HTTP your code sends

Mocks don’t reflect real HTTP behavior. With HttpPlaygroundServer, you inspect the exact request your code produced—method, headers, body, serialization, and path. This makes it easy to diagnose issues caused by incorrect URLs, missing headers, formatting differences, or serialization problems.

2. Request logging is automatic and structured

Each request is stored as a timestamped JSON file. You can review logs after the fact, compare one run to another, or share them when debugging with someone else. This is especially useful when tracking down inconsistencies or unexpected HTTP payloads.

3. Responses are simple JSON files

To change a response, you update a JSON file. To simulate an error condition, you add another JSON file. This approach removes the need for setting up controllers, writing mock rules, or maintaining fake endpoints in code. It keeps test conditions explicit and easy to version.

4. Setup takes only a few lines of code

You can start the server from a console app or test harness with minimal boilerplate. There’s no need to host a full ASP.NET pipeline or use Docker just to return predictable responses.

5. Useful during development

HttpPlaygroundServer is practical when iterating on a new API client, checking model binding, verifying retry behavior, or just understanding what your code is doing over HTTP. It’s meant to be a straightforward tool you can run alongside your application while you work.

6. Simple way to test various scenarios

By adding multiple response files—successful responses, error shapes, malformed JSON, large payloads—you can observe how your client handles different situations. Because everything is file-based, adjusting scenarios is fast.

7. Complements existing approaches

You can still use mocks for unit testing and real APIs or TestServer for full integration tests. HttpPlaygroundServer fits the space in between: when you want real HTTP behavior without the overhead of running an actual backend.

✨ Getting Started ✨

To install the package, visit:
👉 NuGet: https://www.nuget.org/packages/sameerk.HttpPlaygroundServer/1.0.0

To explore the full source code, sample apps, and examples:
👉 GitHub: https://github.com/sameerkapps/HttpPlayground

Final Notes

HttpPlaygroundServer is intentionally simple. It doesn’t aim to replace full mock servers or backend frameworks. Its purpose is to give developers an easy way to observe real HTTP behavior and control responses without extra infrastructure. If you need a lightweight, practical tool for local HTTP testing during development, it may fit well into your workflow.

Leave a comment