MockyFast is a Python CLI tool for mocking HTTP APIs locally using YAML, JSON, and CSV-backed datasets.
It helps you simulate external services during local development without relying on hosted mock platforms or remote dashboards.
Because sometimes you just need a fast, local, and controllable way to simulate APIs while developing.
No external mock platforms, no unnecessary setup — just local files, a local server, and a workflow you control.
- initialize a sample config file
- validate mock configuration before running
- serve mock HTTP endpoints locally
- support inline JSON responses
- support external JSON response files
- support CSV-backed data-driven mocks
- support response shaping for CSV data sources:
wrapnot_found_statusnot_found_body
- support CSV type coercion and schema mapping
- support path parameters
- support request matching by:
- query params
- headers
- JSON body
- support delayed responses with
delay_ms - automated tests with
pytest
git clone https://github.com/Cartenone/mockyfast.git cd mockyfast pip install .
pip install -e ".[dev]"mockyfast init mockyfast validate mockyfast.yaml mockyfast serve mockyfast.yaml --port 8000
mkf init mkf validate mockyfast.yaml mkf serve mockyfast.yaml --port 8000
Create a sample config:
mkf init
Validate it:
mkf validate mockyfast.yaml
Start the mock server:
mkf serve mockyfast.yaml --port 8000
Then call it:
curl http://127.0.0.1:8000/health
routes: - method: GET path: /health response: status_code: 200 body: ok: true
routes: - method: GET path: /users response: status_code: 200 body_from: ./responses/users.json
{
"users": [
{ "id": 1, "name": "Mario" },
{ "id": 2, "name": "Luigi" }
]
}MockyFast can build responses from local CSV files, making mocks more dynamic and reusable.
routes: - method: GET path: /users response: data_source: type: csv file: ./data/users.csv mode: all wrap: items - method: GET path: /users/{user_id} response: data_source: type: csv file: ./data/users.csv mode: first where: column: id equals_path_param: user_id not_found_status: 404 not_found_body: error: user_not_found
id,name,active,balance 1,Mario,true,12.5 2,Luigi,false,7
curl http://127.0.0.1:8000/users curl http://127.0.0.1:8000/users/1 curl http://127.0.0.1:8000/users/999
{
"items": [
{
"id": "1",
"name": "Mario",
"active": "true",
"balance": "12.5"
},
{
"id": "2",
"name": "Luigi",
"active": "false",
"balance": "7"
}
]
}You can automatically coerce CSV values into Python/JSON primitive types.
routes: - method: GET path: /users/{user_id} response: data_source: type: csv file: ./data/users.csv mode: first where: column: id equals_path_param: user_id coerce_types: true
With coerce_types: true, values such as:
true→truefalse→false12→1212.5→12.5
are returned as properly typed JSON values.
For more control, you can define an explicit schema:
routes: - method: GET path: /users/{user_id} response: data_source: type: csv file: ./data/users.csv mode: first where: column: id equals_path_param: user_id schema: id: int active: bool balance: float
Supported schema types:
strintfloatbool
When schema is present, it takes precedence over coerce_types.
You can use path parameters in the route path and reference them in the response body.
routes: - method: GET path: /users/{user_id} response: status_code: 200 body: id: "{user_id}" name: "User {user_id}"
Example:
curl http://127.0.0.1:8000/users/123
Response:
{
"id": "123",
"name": "User 123"
}mockyfast can return different responses for the same path depending on the request.
routes: - method: GET path: /orders request: query: status: shipped response: status_code: 200 body: items: - id: 1 status: shipped - method: GET path: /orders response: status_code: 200 body: items: []
routes: - method: GET path: /profile request: headers: Authorization: Bearer secret-token response: status_code: 200 body: user: mario - method: GET path: /profile response: status_code: 401 body: error: unauthorized
routes: - method: POST path: /login request: json: username: admin password: secret response: status_code: 200 body: token: fake-jwt-token - method: POST path: /login response: status_code: 401 body: error: invalid_credentials
You can simulate slow APIs using delay_ms.
routes: - method: GET path: /slow response: status_code: 200 delay_ms: 3000 body: ok: true
This is useful when you want to simulate:
- slow services
- network latency
- client-side timeouts
Imagine your application depends on an external service.
Instead of calling the real service during local development, you can point your app to http://127.0.0.1:8000 and let mockyfast simulate the API.
That makes it easier to:
- develop locally
- reproduce edge cases
- test success and error responses
- work without depending on external environments
mocks/
├─ mockyfast.yaml
├─ data/
│ └─ users.csv
└─ responses/
└─ users.json
Then run:
mkf serve ./mocks/mockyfast.yaml --port 8000
Before starting the server, you can validate your configuration:
mkf validate mockyfast.yaml
This helps catch issues like:
- missing
routes - invalid route structure
- missing JSON files
- missing CSV files
- invalid
delay_ms - invalid request matching config
- invalid CSV schema configuration
Run the test suite with:
pytest
Planned improvements:
- better error messages and validation feedback
- JSON-backed data-driven mocks
- HTTP client / probe mode
- capture real API responses into reusable mock files
- more advanced matching rules
- stateful mock scenarios
- extended fault injection beyond
delay_ms
Future exploration:
- OpenAPI-based mock generation
- record & replay mode
- GraphQL support
- WebSocket mocking
- gRPC support
- SOAP/XML support
Created by Cartenone.
MIT