https://github.com/pokatomnik/mockers
Blazingly 🤡 fast HTTP mocking server written in Rust
https://github.com/pokatomnik/mockers
clap hyper mock reqwest rust server tokio
Last synced: 5 months ago
JSON representation
Blazingly 🤡 fast HTTP mocking server written in Rust
- Host: GitHub
- URL: https://github.com/pokatomnik/mockers
- Owner: pokatomnik
- License: mit
- Created: 2025-11-12T14:54:38.000Z (7 months ago)
- Default Branch: dungeon-master
- Last Pushed: 2026-01-11T15:31:47.000Z (5 months ago)
- Last Synced: 2026-01-11T18:45:34.763Z (5 months ago)
- Topics: clap, hyper, mock, reqwest, rust, server, tokio
- Language: Rust
- Homepage: https://github.com/pokatomnik/mockers
- Size: 616 KB
- Stars: 1
- Watchers: 1
- Forks: 0
- Open Issues: 7
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# Mockers - Simple HTTP Mock Server in Rust 🎯
[](https://github.com/pokatomnik/mockers/actions/workflows/rust.yml)
`Mockers` is a lightweight HTTP server written in Rust for serving mock responses from files. It is designed for
testing, prototyping, or any scenario where you need a quick mock backend.
---
## Installation 🚀
Build from source using Cargo:
```bash
cargo build --release
```
## Usage 🚀
Run the server using the `serve` command:
```sh
mockers serve [OPTIONS]
```
## Command-line Options 🚀
| Flag | Default | Description |
| ------------------ | ----------- | ------------------------------------------------------------------------ |
| `--host` | `127.0.0.1` | Host to listen on |
| `--port`, `-p` | `8080` | Port to listen on |
| `--verbose`, `-v` | `false` | Enable verbose logging |
| `--mocks`, `-m` | `mocks` | Path to the directory containing mock files |
| `--cors` | `false` | Enable CORS headers (`Access-Control-Allow-Origin: *`) |
| `--delay-ms` | `0` | Delay (in milliseconds) for serving mock responses |
| `--origin` | [unset] | Forward requests to another server when mock is missing by requested URL |
| `--admin-base-url` | [unset] | Enable admin API (see admin unit) |
## Mock File Structure 🚀
- 💡 All files inside the mocks directory are used as responses.
- 💡 File names determine the HTTP method:
```
user.get -> responds to GET /user
login.post -> responds to POST /login
```
- 💡 The path inside the file name (before the dot) corresponds to the URL path.
- 💡 Both relative and absolute paths are supported for the `--mocks` flag.
Example:
```
mocks/
├─ user.get
├─ login.post
└─ config.put
```
This will create the following endpoints:
- 💡 `GET /user`
- 💡 `POST /login`
- 💡 `PUT /config`
## Examples 🚀
Run the server on default settings:
```sh
mockers serve
```
Run on a custom host and port with verbose logging:
```sh
mockers serve --host 0.0.0.0 --port 3000 --verbose
```
Serve mocks from a custom directory with CORS enabled and 500ms response delay:
```sh
mockers serve --mocks ./api_mocks --cors --delay_ms 500
```
## Per-Directory Mock Configuration 🚀
Some endpoints may require custom behavior — a delayed response, a non-200 status code, or custom headers.
To support this, any mock directory may optionally contain a mock-config.json file describing additional response
parameters.
### Example 🔧
```json
{
"test.get": {
"delayMs": 5000,
"statusCode": 201,
"headers": {
"X-Server": "Mockers"
},
"cacheMode": "Overwrite"
}
}
```
Given the file above, a request to:
```
GET http://localhost:8080/test
```
will produce:
- 💡 **5000 ms delay**
- 💡 **HTTP 201 status**
- 💡 **Header** `X-Server: Mockers`
- 💡 **Body** — the content of `test.get` (or any corresponding mock file)
- 💡 The response body will be cached into `test.get` if file `test.get` is missing (asynchronously).
### Rules 🔧
- 💡 The config file is optional.
- 💡 If it doesn't exist, default behavior applies (status 200, no delay, no custom headers).
- 💡 Keys in the config file must match mock filenames in the same directory.
- 💡 For example, test.get configures the file test.get.
- 💡 All fields inside each entry are optional:
| Field | Type | Description |
| ------------ | ------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `delayMs` | `number` | Artificial response delay in milliseconds |
| `statusCode` | `number` (u16) | HTTP status code |
| `headers` | `Record` | Additional headers to append to the response |
| `cacheMode` | `Overwrite` or `NoCache` | If you specify the Overwrite parameter, if the mock file is missing, the request will be sent to the origin url and the body of the origin server response will be written to the missing mock file |
### Example Behavior 🔧
If only some fields are provided, the server fills in the rest with defaults.
For example:
```json
{
"user.get": {
"statusCode": 404
}
}
```
This results in:
- 💡 404 status
- 💡 no delay
- 💡 no custom headers
- 💡 body loaded from `user.get`
# Admin pages and API
It is also possible to manage moks in runtime. This is implemented using the REST API, which can be enabled using the
launch flag `--admin-base-url`. Here you need to pass the absolute URL path, which cannot be used as a mock path, and in
which the REST-endpoints and Swagger UI are located.
Example:
```sh
mockers serve --admin-base-url /__admin
```
All endpoints will start from the specified admin base url. There are endpoints for creating mocks in runtime, deleting
and modifying, as well as endpoints for saving mocks from RAM to a file.
To open the Swagger UI (let's assume that we have launched `mockers` as mentioned above) you need to open the
address http://localhost:8080/\_\_admin/swagger
## Notes 🚀
- 💡 The server automatically resolves relative paths for mocks based on the current working directory.
- 💡 If the specified mocks directory does not exist or is not a directory, the server will return an error.
- 💡 Response delay can be used to simulate slow network responses.
## Shout-out 🚀
Huge thanks to [@Caik](https://github.com/Caik)
, whose [Go version](https://github.com/Caik/go-mock-server) sparked the idea for this project.
I rewrote the whole thing in Rust because apparently I enjoy suffering — and because I wanted features the original
never asked for.
Big thanks to [bloodvez](https://github.com/bloodvez) for helping me find problems and to [silentroach](https://github.com/silentroach) for pointing out a bug and showing me mind-blowing AI experiments with Rust.
## License 🚀
MIT License