# SCAPI
[](https://codecov.io/github/sesav/scapi)
> Dead simple, **S**elf-**C**ontained, single-file **API** load testing tool built on FastAPI.
A lightweight tool for ad-hoc API testing. It generates controlled request loads, customizes headers and payloads, collects latency metrics, and runs anywhere with minimal setup — just launch and start testing.
## Features
- **Zero Configuration** - One file, one command
- **Self-Contained** - Uses uv's inline metadata format
- **FastAPI Swagger UI** - Beautiful Swagger UI interface;
- **Async Load Testing** - Built on httpx (encode) and asyncio
- **Real-time Results** - View metrics in stdout during execution
- **Container Ready** - Works in any environment (uv handles it)
## Quick Start
Install [uv](https://docs.astral.sh/uv/getting-started/installation/) with the official script or via pip if Python is available on your laptop or server.
### Option 1: Run Directly (No Installation)
```bash
# Download and run the tool directly
curl -LOs https://github.com/sesav/scapi-py/releases/latest/download/scapi.py
uv run scapi.py
# Or with wget
wget https://github.com/sesav/scapi-py/releases/latest/download/scapi.py
uv run scapi.py
```
### Option 2: Install as Package
```bash
# Install from PyPI
pip install scapi-py
# Run the tool
scapi
```
### Option 3: Install with uv
```bash
# Install with uv
uv add scapi-py
# Run the tool
scapi
```
### Usage
1. Open http://localhost:8000 in your browser
2. Use the `/load` endpoint to send requests
3. Check `/results` for metrics and response times
## API Reference
### POST /load
Send load test requests to a target URL.
**Parameters:**
* `url` (string, required) - Target URL to test
* `method` (string, required) - HTTP method (GET, POST, PUT, etc.)
* `attempts` (int, default: 10) - Number of requests to send
* `delay` (float, default: 0.1) - Delay between requests in seconds
* `headers` (dict, optional) - Custom HTTP headers
* `body` (dict, optional) - Request body for POST/PUT requests
* `response_header` (bool, default: false) - Include response headers in stdout
* `response_body` (bool, default: false) - Include response body in stdout
### GET /results
Get aggregated test results and metrics.
**Response:**
```json
{
"results": {
"200": 10,
"404": 2
},
"average_request_time": 0.25
}
```
## Docker Usage
```bash
docker run -ti --rm -p "8000:8000" python:3.12-slim-bookworm bash
```
Then follow the installation steps inside the container.
## Screenshots
*Configure your load test parameters*
*View real-time results and metrics*
## Limitations
It's important to understand that this is a very simple, single-threaded application. Its purpose
is to perform small, quick tests by generating a limited number of requests, and it can run in
almost any environment where the uv binary is available. If you need serious load testing at scale,
consider more robust solutions such as Locust, Apache JMeter, or similar tools.
## Development
```bash
# Clone the repository
git clone https://github.com/sesav/scapi-py.git
cd scapi-py
# Install development dependencies
make install
# Run tests
make test
# Run
make run
```
## Requirements
- Python 3.10+
- uv package manager
- wget or curl (for installation)
## License
This project is licensed under the [MIT License](LICENSE).
Raw data
{
"_id": null,
"home_page": null,
"name": "scapi-py",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": "api, fastapi, load, python, python310, python311, python312, python313, single-file, testing, tool",
"author": null,
"author_email": "Sergey Silaev <hello@8am.dev>",
"download_url": "https://files.pythonhosted.org/packages/f0/b7/1d39aa9f21c47b7a11fda667685e8d22623e61062fc2e7d99ac7710724d7/scapi_py-2.0.1.tar.gz",
"platform": null,
"description": "# SCAPI\n\n\n\n[](https://codecov.io/github/sesav/scapi)\n\n\n> Dead simple, **S**elf-**C**ontained, single-file **API** load testing tool built on FastAPI.\n\nA lightweight tool for ad-hoc API testing. It generates controlled request loads, customizes headers and payloads, collects latency metrics, and runs anywhere with minimal setup \u2014 just launch and start testing.\n\n## Features\n\n- **Zero Configuration** - One file, one command\n- **Self-Contained** - Uses uv's inline metadata format\n- **FastAPI Swagger UI** - Beautiful Swagger UI interface;\n- **Async Load Testing** - Built on httpx (encode) and asyncio\n- **Real-time Results** - View metrics in stdout during execution\n- **Container Ready** - Works in any environment (uv handles it)\n\n## Quick Start\n\nInstall [uv](https://docs.astral.sh/uv/getting-started/installation/) with the official script or via pip if Python is available on your laptop or server.\n\n### Option 1: Run Directly (No Installation)\n\n```bash\n# Download and run the tool directly\ncurl -LOs https://github.com/sesav/scapi-py/releases/latest/download/scapi.py\nuv run scapi.py\n\n# Or with wget\nwget https://github.com/sesav/scapi-py/releases/latest/download/scapi.py\nuv run scapi.py\n```\n\n### Option 2: Install as Package\n\n```bash\n# Install from PyPI\npip install scapi-py\n\n# Run the tool\nscapi\n```\n\n### Option 3: Install with uv\n\n```bash\n# Install with uv\nuv add scapi-py\n\n# Run the tool\nscapi\n```\n\n### Usage\n\n1. Open http://localhost:8000 in your browser\n2. Use the `/load` endpoint to send requests\n3. Check `/results` for metrics and response times\n\n## API Reference\n\n### POST /load\nSend load test requests to a target URL.\n\n**Parameters:**\n* `url` (string, required) - Target URL to test\n* `method` (string, required) - HTTP method (GET, POST, PUT, etc.)\n* `attempts` (int, default: 10) - Number of requests to send\n* `delay` (float, default: 0.1) - Delay between requests in seconds\n* `headers` (dict, optional) - Custom HTTP headers\n* `body` (dict, optional) - Request body for POST/PUT requests\n* `response_header` (bool, default: false) - Include response headers in stdout\n* `response_body` (bool, default: false) - Include response body in stdout\n\n### GET /results\nGet aggregated test results and metrics.\n\n**Response:**\n```json\n{\n \"results\": {\n \"200\": 10,\n \"404\": 2\n },\n \"average_request_time\": 0.25\n}\n```\n\n## Docker Usage\n\n```bash\ndocker run -ti --rm -p \"8000:8000\" python:3.12-slim-bookworm bash\n```\nThen follow the installation steps inside the container.\n\n## Screenshots\n\n\n*Configure your load test parameters*\n\n\n*View real-time results and metrics*\n\n## Limitations\n\nIt's important to understand that this is a very simple, single-threaded application. Its purpose\nis to perform small, quick tests by generating a limited number of requests, and it can run in\nalmost any environment where the uv binary is available. If you need serious load testing at scale,\nconsider more robust solutions such as Locust, Apache JMeter, or similar tools.\n\n## Development\n\n```bash\n# Clone the repository\ngit clone https://github.com/sesav/scapi-py.git\ncd scapi-py\n\n# Install development dependencies\nmake install\n\n# Run tests\nmake test\n\n# Run\nmake run\n```\n\n## Requirements\n\n- Python 3.10+\n- uv package manager\n- wget or curl (for installation)\n\n## License\n\nThis project is licensed under the [MIT License](LICENSE).\n",
"bugtrack_url": null,
"license": null,
"summary": "Dead simple, self-contained, single-file API load testing tool built on FastAPI.",
"version": "2.0.1",
"project_urls": {
"Source code": "https://github.com/sesav/scapi-py"
},
"split_keywords": [
"api",
" fastapi",
" load",
" python",
" python310",
" python311",
" python312",
" python313",
" single-file",
" testing",
" tool"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "1fd63741f5852972e47638d99fc79838577ddb25335d455493c214749f259ce8",
"md5": "d8ad8e4203337dd9445f73c38f5c4a81",
"sha256": "9b26300e3d0954e3fafb6db2e0063b30aa6ed6bab353f838e10c7c86011ed3ce"
},
"downloads": -1,
"filename": "scapi_py-2.0.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "d8ad8e4203337dd9445f73c38f5c4a81",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 6721,
"upload_time": "2025-09-04T11:41:11",
"upload_time_iso_8601": "2025-09-04T11:41:11.613213Z",
"url": "https://files.pythonhosted.org/packages/1f/d6/3741f5852972e47638d99fc79838577ddb25335d455493c214749f259ce8/scapi_py-2.0.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "f0b71d39aa9f21c47b7a11fda667685e8d22623e61062fc2e7d99ac7710724d7",
"md5": "a26a62c9e2487c33ba5d30b6d30c91c5",
"sha256": "6abb0bb6f7f192db4c8e76b165cf41edf0425df9fd0050f792294bd31e4c7067"
},
"downloads": -1,
"filename": "scapi_py-2.0.1.tar.gz",
"has_sig": false,
"md5_digest": "a26a62c9e2487c33ba5d30b6d30c91c5",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 143271,
"upload_time": "2025-09-04T11:41:12",
"upload_time_iso_8601": "2025-09-04T11:41:12.737788Z",
"url": "https://files.pythonhosted.org/packages/f0/b7/1d39aa9f21c47b7a11fda667685e8d22623e61062fc2e7d99ac7710724d7/scapi_py-2.0.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-09-04 11:41:12",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "sesav",
"github_project": "scapi-py",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "scapi-py"
}
JSON
