# FastAPI Mock Service
[](https://badge.fury.io/py/fastapi-mock-service)
[](https://www.python.org/downloads/)
[](https://opensource.org/licenses/MIT)
Professional mock service library with load testing infrastructure for FastAPI. Create powerful mock APIs with built-in
monitoring, metrics collection, and interactive dashboard.
## 🚀 Features
- **Easy Mock Creation**: Simple decorators to create mock endpoints
- **Built-in Dashboard**: Real-time monitoring with interactive web interface
- **Prometheus Metrics**: Comprehensive metrics collection for performance analysis
- **Load Testing Support**: Built-in infrastructure for load testing mock services
- **Database Integration**: SQLite database for test results storage
- **Flexible Response Configuration**: Support for complex response scenarios
- **CLI Tool**: Command-line interface for quick setup and management
- **Auto Validation**: Automatic parameter validation with error handling
## 📦 Installation
```bash
pip install fastapi-mock-service
```
## 🎯 Quick Start
### 1. Basic Usage
```python
from fastapi_mock_service import MockService
from pydantic import BaseModel
# Create mock service
mock = MockService()
class User(BaseModel):
id: int
name: str
email: str
# Create mock endpoints
@mock.get("/api/users/{user_id}")
def get_user(user_id: int):
return User(
id=user_id,
name=f"User {user_id}",
email=f"user{user_id}@example.com"
)
@mock.post("/api/users")
def create_user(user: User):
return {"message": "User created", "user": user}
if __name__ == "__main__":
mock.run()
```
### 2. Using CLI
```bash
# Create example file
fastapi-mock init my_mock.py
# Create advanced example with error codes
fastapi-mock init advanced_mock.py --advanced
# Run mock service
fastapi-mock run my_mock.py
# Run on custom port
fastapi-mock run my_mock.py --port 9000
```
### 3. Advanced Usage with Error Codes
```python
from fastapi_mock_service import MockService
from pydantic import BaseModel
from typing import Optional
from datetime import datetime, timezone
mock = MockService()
# Define error codes
API_ERRORS = {
"validation": {"code": "API.01000", "message": "Validation error"},
"not_found": {"code": "API.01001", "message": "Resource not found"},
"server_error": {"code": "API.01003", "message": "Internal server error"},
}
class StandardResult(BaseModel):
timestamp: str
status: int
code: str
message: str
class UserResponse(BaseModel):
result: StandardResult
data: Optional[dict] = None
def make_result(success: bool = True, error_key: Optional[str] = None) -> StandardResult:
dt = datetime.now(timezone.utc).isoformat()
if success:
return StandardResult(
timestamp=dt, status=200, code="API.00000", message="OK"
)
else:
error_info = API_ERRORS.get(error_key, API_ERRORS["server_error"])
return StandardResult(
timestamp=dt, status=200,
code=error_info["code"], message=error_info["message"]
)
@mock.get("/api/v1/users/{user_id}")
def get_user_advanced(user_id: int):
if user_id <= 0:
return UserResponse(result=make_result(False, "validation"))
if user_id > 1000:
return UserResponse(result=make_result(False, "not_found"))
# Success response
user_data = {"id": user_id, "name": f"User {user_id}"}
return UserResponse(result=make_result(True), data=user_data)
if __name__ == "__main__":
mock.run()
```
## 🌐 Dashboard & Monitoring
Once your mock service is running, access:
- **📊 Dashboard**: `http://localhost:8000` - Interactive monitoring interface
- **📈 Metrics**: `http://localhost:8000/metrics` - Prometheus metrics endpoint
- **📚 API Docs**: `http://localhost:8000/docs` - Auto-generated API documentation
### Dashboard Features
- **Real-time Logs**: View incoming requests and responses
- **Metrics Visualization**: Charts for request counts, response times, and error rates
- **Test Management**: Start/stop load testing sessions
- **Endpoint Overview**: List of all registered mock endpoints
- **Test Results History**: Historical test results with detailed summaries
## 🧪 Load Testing
The service includes built-in load testing capabilities:
```python
# Your mock service automatically includes testing endpoints
# POST /api/start-test - Start a new test session
# POST /api/stop-test - Stop test and generate summary
# POST /api/reset-metrics - Reset all metrics
# Example: Start test via HTTP
import httpx
# Start test
response = httpx.post("http://localhost:8000/api/start-test",
json={"test_name": "Performance Test"})
# Your load testing tool hits the mock endpoints
# ... run your load tests ...
# Stop test and get results
results = httpx.post("http://localhost:8000/api/stop-test").json()
print(results["summary"])
```
## 📊 Metrics Collection
Automatic metrics collection includes:
- **Request Count**: Total requests per endpoint
- **Response Time**: Histogram of response times
- **Status Codes**: Distribution of response codes
- **Error Rates**: Success/failure ratios
- **Custom Result Codes**: Application-specific result codes
## 🛠️ API Reference
### MockService Class
```python
class MockService:
def __init__(self, db_url: str = "sqlite://test_results.db"):
"""Initialize mock service with optional database URL"""
def get(self, path: str = None, responses: list = None, tags: list = None):
"""GET endpoint decorator"""
def post(self, path: str = None, responses: list = None, tags: list = None):
"""POST endpoint decorator"""
def put(self, path: str = None, responses: list = None, tags: list = None):
"""PUT endpoint decorator"""
def delete(self, path: str = None, responses: list = None, tags: list = None):
"""DELETE endpoint decorator"""
def run(self, host: str = "0.0.0.0", port: int = 8000, **kwargs):
"""Run the mock service"""
```
### Decorator Parameters
- **path**: URL path for the endpoint (defaults to function name)
- **responses**: List of possible responses for documentation
- **tags**: Tags for grouping endpoints in UI
- **validation_error_handler**: Custom validation error handler
## 📝 Examples
### Example 1: REST API Mock
```python
from fastapi_mock_service import MockService
mock = MockService()
@mock.get("/api/products/{product_id}")
def get_product(product_id: int, include_details: bool = False):
product = {"id": product_id, "name": f"Product {product_id}"}
if include_details:
product["description"] = f"Description for product {product_id}"
return product
@mock.get("/api/products")
def list_products(category: str = "all", limit: int = 10):
return {
"products": [{"id": i, "name": f"Product {i}"} for i in range(1, limit + 1)],
"category": category,
"total": limit
}
mock.run()
```
### Example 2: With Custom Headers
```python
from fastapi_mock_service import MockService
from fastapi import Header
mock = MockService()
@mock.get("/api/secure/data")
def get_secure_data(authorization: str = Header(...)):
if not authorization.startswith("Bearer "):
return {"error": "Invalid authorization header"}
return {"data": "sensitive information", "user": "authenticated"}
mock.run()
```
## 🤝 Contributing
Contributions are welcome! Please feel free to submit a Pull Request.
## 📄 License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
## 📞 Support
- **Issues**: [GitHub Issues](https://github.com/username/fastapi-mock-service/issues)
- **Email**: Sviridov.DS@bk.ru
## Acknowledgments
Built with:
- FastAPI - Modern, fast web framework
- Prometheus Client - Metrics collection
- Tortoise ORM - Async ORM for test results
- Chart.js - Interactive charts in dashboard
------------------------------------------
##### Made with ❤️ for the API development and testing community
Raw data
{
"_id": null,
"home_page": "https://github.com/username/fastapi-mock-service",
"name": "fastapi-mock-service",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "fastapi, mock, testing, api, load-testing, prometheus, dashboard",
"author": "Denis Sviridov",
"author_email": "Denis Sviridov <Sviridov.DS@bk.ru>",
"download_url": "https://files.pythonhosted.org/packages/83/d6/1bd1128cd283211417e16ded695c0cc36c1ad5c4555f9d345d84dea23a11/fastapi_mock_service-1.0.5.tar.gz",
"platform": null,
"description": "# FastAPI Mock Service\n\n[](https://badge.fury.io/py/fastapi-mock-service)\n[](https://www.python.org/downloads/)\n[](https://opensource.org/licenses/MIT)\n\nProfessional mock service library with load testing infrastructure for FastAPI. Create powerful mock APIs with built-in\nmonitoring, metrics collection, and interactive dashboard.\n\n## \ud83d\ude80 Features\n\n- **Easy Mock Creation**: Simple decorators to create mock endpoints\n- **Built-in Dashboard**: Real-time monitoring with interactive web interface\n- **Prometheus Metrics**: Comprehensive metrics collection for performance analysis\n- **Load Testing Support**: Built-in infrastructure for load testing mock services\n- **Database Integration**: SQLite database for test results storage\n- **Flexible Response Configuration**: Support for complex response scenarios\n- **CLI Tool**: Command-line interface for quick setup and management\n- **Auto Validation**: Automatic parameter validation with error handling\n\n## \ud83d\udce6 Installation\n\n```bash\npip install fastapi-mock-service\n```\n\n## \ud83c\udfaf Quick Start\n\n### 1. Basic Usage\n\n```python\nfrom fastapi_mock_service import MockService\nfrom pydantic import BaseModel\n\n# Create mock service\nmock = MockService()\n\nclass User(BaseModel):\n id: int\n name: str\n email: str\n\n# Create mock endpoints\n@mock.get(\"/api/users/{user_id}\")\ndef get_user(user_id: int):\n return User(\n id=user_id,\n name=f\"User {user_id}\",\n email=f\"user{user_id}@example.com\"\n )\n\n@mock.post(\"/api/users\")\ndef create_user(user: User):\n return {\"message\": \"User created\", \"user\": user}\n\nif __name__ == \"__main__\":\n mock.run()\n```\n\n### 2. Using CLI\n\n```bash\n# Create example file\nfastapi-mock init my_mock.py\n\n# Create advanced example with error codes\nfastapi-mock init advanced_mock.py --advanced\n\n# Run mock service\nfastapi-mock run my_mock.py\n\n# Run on custom port\nfastapi-mock run my_mock.py --port 9000\n```\n\n### 3. Advanced Usage with Error Codes\n\n```python\nfrom fastapi_mock_service import MockService\nfrom pydantic import BaseModel\nfrom typing import Optional\nfrom datetime import datetime, timezone\n\nmock = MockService()\n\n# Define error codes\nAPI_ERRORS = {\n \"validation\": {\"code\": \"API.01000\", \"message\": \"Validation error\"},\n \"not_found\": {\"code\": \"API.01001\", \"message\": \"Resource not found\"},\n \"server_error\": {\"code\": \"API.01003\", \"message\": \"Internal server error\"},\n}\n\nclass StandardResult(BaseModel):\n timestamp: str\n status: int\n code: str\n message: str\n\nclass UserResponse(BaseModel):\n result: StandardResult\n data: Optional[dict] = None\n\ndef make_result(success: bool = True, error_key: Optional[str] = None) -> StandardResult:\n dt = datetime.now(timezone.utc).isoformat()\n if success:\n return StandardResult(\n timestamp=dt, status=200, code=\"API.00000\", message=\"OK\"\n )\n else:\n error_info = API_ERRORS.get(error_key, API_ERRORS[\"server_error\"])\n return StandardResult(\n timestamp=dt, status=200, \n code=error_info[\"code\"], message=error_info[\"message\"]\n )\n\n@mock.get(\"/api/v1/users/{user_id}\")\ndef get_user_advanced(user_id: int):\n if user_id <= 0:\n return UserResponse(result=make_result(False, \"validation\"))\n \n if user_id > 1000:\n return UserResponse(result=make_result(False, \"not_found\"))\n \n # Success response\n user_data = {\"id\": user_id, \"name\": f\"User {user_id}\"}\n return UserResponse(result=make_result(True), data=user_data)\n\nif __name__ == \"__main__\":\n mock.run()\n```\n\n## \ud83c\udf10 Dashboard & Monitoring\n\nOnce your mock service is running, access:\n\n- **\ud83d\udcca Dashboard**: `http://localhost:8000` - Interactive monitoring interface\n- **\ud83d\udcc8 Metrics**: `http://localhost:8000/metrics` - Prometheus metrics endpoint\n- **\ud83d\udcda API Docs**: `http://localhost:8000/docs` - Auto-generated API documentation\n\n### Dashboard Features\n\n- **Real-time Logs**: View incoming requests and responses\n- **Metrics Visualization**: Charts for request counts, response times, and error rates\n- **Test Management**: Start/stop load testing sessions\n- **Endpoint Overview**: List of all registered mock endpoints\n- **Test Results History**: Historical test results with detailed summaries\n\n## \ud83e\uddea Load Testing\n\nThe service includes built-in load testing capabilities:\n\n```python\n# Your mock service automatically includes testing endpoints\n# POST /api/start-test - Start a new test session\n# POST /api/stop-test - Stop test and generate summary\n# POST /api/reset-metrics - Reset all metrics\n\n# Example: Start test via HTTP\nimport httpx\n\n# Start test\nresponse = httpx.post(\"http://localhost:8000/api/start-test\", \n json={\"test_name\": \"Performance Test\"})\n\n# Your load testing tool hits the mock endpoints\n# ... run your load tests ...\n\n# Stop test and get results\nresults = httpx.post(\"http://localhost:8000/api/stop-test\").json()\nprint(results[\"summary\"])\n```\n\n## \ud83d\udcca Metrics Collection\n\nAutomatic metrics collection includes:\n\n- **Request Count**: Total requests per endpoint\n- **Response Time**: Histogram of response times\n- **Status Codes**: Distribution of response codes\n- **Error Rates**: Success/failure ratios\n- **Custom Result Codes**: Application-specific result codes\n\n## \ud83d\udee0\ufe0f API Reference\n\n### MockService Class\n\n```python\nclass MockService:\n def __init__(self, db_url: str = \"sqlite://test_results.db\"):\n \"\"\"Initialize mock service with optional database URL\"\"\"\n \n def get(self, path: str = None, responses: list = None, tags: list = None):\n \"\"\"GET endpoint decorator\"\"\"\n \n def post(self, path: str = None, responses: list = None, tags: list = None):\n \"\"\"POST endpoint decorator\"\"\"\n \n def put(self, path: str = None, responses: list = None, tags: list = None):\n \"\"\"PUT endpoint decorator\"\"\"\n \n def delete(self, path: str = None, responses: list = None, tags: list = None):\n \"\"\"DELETE endpoint decorator\"\"\"\n \n def run(self, host: str = \"0.0.0.0\", port: int = 8000, **kwargs):\n \"\"\"Run the mock service\"\"\"\n```\n\n### Decorator Parameters\n\n- **path**: URL path for the endpoint (defaults to function name)\n- **responses**: List of possible responses for documentation\n- **tags**: Tags for grouping endpoints in UI\n- **validation_error_handler**: Custom validation error handler\n\n## \ud83d\udcdd Examples\n\n### Example 1: REST API Mock\n\n```python\nfrom fastapi_mock_service import MockService\n\nmock = MockService()\n\n@mock.get(\"/api/products/{product_id}\")\ndef get_product(product_id: int, include_details: bool = False):\n product = {\"id\": product_id, \"name\": f\"Product {product_id}\"}\n if include_details:\n product[\"description\"] = f\"Description for product {product_id}\"\n return product\n\n@mock.get(\"/api/products\")\ndef list_products(category: str = \"all\", limit: int = 10):\n return {\n \"products\": [{\"id\": i, \"name\": f\"Product {i}\"} for i in range(1, limit + 1)],\n \"category\": category,\n \"total\": limit\n }\n\nmock.run()\n```\n\n### Example 2: With Custom Headers\n\n```python\nfrom fastapi_mock_service import MockService\nfrom fastapi import Header\n\nmock = MockService()\n\n@mock.get(\"/api/secure/data\")\ndef get_secure_data(authorization: str = Header(...)):\n if not authorization.startswith(\"Bearer \"):\n return {\"error\": \"Invalid authorization header\"}\n \n return {\"data\": \"sensitive information\", \"user\": \"authenticated\"}\n\nmock.run()\n```\n\n## \ud83e\udd1d Contributing\n\nContributions are welcome! Please feel free to submit a Pull Request.\n\n## \ud83d\udcc4 License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## \ud83d\udcde Support\n\n- **Issues**: [GitHub Issues](https://github.com/username/fastapi-mock-service/issues)\n- **Email**: Sviridov.DS@bk.ru\n\n## Acknowledgments\nBuilt with:\n\n- FastAPI - Modern, fast web framework\n- Prometheus Client - Metrics collection\n- Tortoise ORM - Async ORM for test results\n- Chart.js - Interactive charts in dashboard\n\n\n------------------------------------------\n##### Made with \u2764\ufe0f for the API development and testing community\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Professional mock service library with load testing infrastructure for FastAPI",
"version": "1.0.5",
"project_urls": {
"Bug Tracker": "https://github.com/username/fastapi-mock-service/issues",
"Documentation": "https://github.com/username/fastapi-mock-service#readme",
"Homepage": "https://github.com/username/fastapi-mock-service",
"Repository": "https://github.com/username/fastapi-mock-service.git"
},
"split_keywords": [
"fastapi",
" mock",
" testing",
" api",
" load-testing",
" prometheus",
" dashboard"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "79c23d0cfb24cd953a5a947bd5ca21f8e87bd380c10c5843950056bbdfb361a2",
"md5": "46a2276dcad3967bee1d93884e04342c",
"sha256": "c0ee07138c6c3844712ad37e7c3bea0185cc7c2de8a60842f3d806f1d7db2746"
},
"downloads": -1,
"filename": "fastapi_mock_service-1.0.5-py3-none-any.whl",
"has_sig": false,
"md5_digest": "46a2276dcad3967bee1d93884e04342c",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 28381,
"upload_time": "2025-09-11T07:54:38",
"upload_time_iso_8601": "2025-09-11T07:54:38.838060Z",
"url": "https://files.pythonhosted.org/packages/79/c2/3d0cfb24cd953a5a947bd5ca21f8e87bd380c10c5843950056bbdfb361a2/fastapi_mock_service-1.0.5-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "83d61bd1128cd283211417e16ded695c0cc36c1ad5c4555f9d345d84dea23a11",
"md5": "094d8a87785ddd10b251a77e0d664ef0",
"sha256": "15330b4eaafd12a88f3a8f9a4c866d8912263986e6ed33b571d37e75ff80f101"
},
"downloads": -1,
"filename": "fastapi_mock_service-1.0.5.tar.gz",
"has_sig": false,
"md5_digest": "094d8a87785ddd10b251a77e0d664ef0",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 27586,
"upload_time": "2025-09-11T07:54:39",
"upload_time_iso_8601": "2025-09-11T07:54:39.918125Z",
"url": "https://files.pythonhosted.org/packages/83/d6/1bd1128cd283211417e16ded695c0cc36c1ad5c4555f9d345d84dea23a11/fastapi_mock_service-1.0.5.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-09-11 07:54:39",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "username",
"github_project": "fastapi-mock-service",
"github_not_found": true,
"lcname": "fastapi-mock-service"
}
JSON
