Metadata-Version: 2.4
Name: scapi-py
Version: 2.0.4
Summary: Dead simple, self-contained, single-file API load testing tool built on FastAPI.
Project-URL: Source code, https://github.com/sesav/scapi-py
Author-email: Sergey Silaev <hello@8am.dev>
License-Expression: MIT
License-File: LICENSE
Keywords: api,fastapi,load,python,python310,python311,python312,python313,single-file,testing,tool
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: Web Environment
Classifier: Framework :: AsyncIO
Classifier: Framework :: FastAPI
Classifier: Framework :: Pydantic
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Information Technology
Classifier: Intended Audience :: System Administrators
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Education :: Testing
Classifier: Topic :: Internet
Classifier: Topic :: Internet :: WWW/HTTP
Classifier: Topic :: Internet :: WWW/HTTP :: HTTP Servers
Classifier: Topic :: Software Development
Classifier: Topic :: Software Development :: Libraries
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Software Development :: Testing
Classifier: Topic :: Software Development :: Testing :: Traffic Generation
Requires-Python: >=3.10
Requires-Dist: fastapi==0.116.1
Requires-Dist: httpx==0.28.1
Requires-Dist: pydantic>=2.11.7
Requires-Dist: structlog==25.1.0
Requires-Dist: uvicorn==0.35.0
Requires-Dist: uvloop==0.21.0
Description-Content-Type: text/markdown

# SCAPI

![Total](https://img.shields.io/github/downloads/sesav/scapi-py/total)
![Python Version](https://img.shields.io/badge/python-3.10+-blue)
[![codecov](https://codecov.io/github/sesav/scapi/graph/badge.svg?token=GSHBWZGXAH)](https://codecov.io/github/sesav/scapi)
![License](https://img.shields.io/github/license/sesav/scapi-py)

> 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

![Load Testing Interface](https://github.com/sesav/scapi-py/blob/main/images/load.png)
*Configure your load test parameters*

![Results Dashboard](https://github.com/sesav/scapi-py/blob/main/images/results.png)
*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).
