overload-cli 0.1.0__tar.gz

overload_cli-0.1.0/.gitignore

@@ -0,0 +1,20 @@
+__pycache__/
+*.pyc
+*.pyo
+.venv/
+*.egg-info/
+dist/
+build/
+.eggs/
+overload_report_*.html
+overload_results_*.json
+overload_results_*.csv
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+tmp_workdir/
+reports/
+overload.config.yaml
+ttd_collection.json
+.DS_Store
+tmp_workdir/

overload_cli-0.1.0/AGENTS.md

@@ -0,0 +1,148 @@
+# Overload — Project Guide
+
+## What is this?
+
+Overload is a free, open-source load testing tool that reads Postman collections and provides a browser-based UI. Published as `overload` on PyPI, command is `overload`.
+
+## Quick Start
+
+```bash
+pip install -e ".[dev]"   # Install in dev mode
+overload                   # Opens browser UI on port 3000
+overload run --collection path/to/collection.json --pattern burst  # CLI mode
+```
+
+## Project Structure
+
+```
+src/overload/           # Main package (src layout)
+  collection/           # Postman collection parsing (parser, models, variables, environment)
+  engine/               # Test execution (http_client, load_patterns, runner, rate_limiter, events)
+  report/               # HTML report generation + CSV/JSON export
+    templates/           # Jinja2 templates, CSS, JS for reports
+  web/                  # FastAPI browser UI
+    routes/             # API endpoints + WebSocket
+    static/css/         # UI stylesheets
+    static/js/          # Vanilla JS frontend (app, collection, runner, charts)
+    templates/          # index.html SPA shell
+  utils/                # Naming, timestamps
+  cli.py                # CLI entry point
+tests/                  # Unit tests (pytest)
+  fixtures/             # Sample Postman collections for tests
+```
+
+## Tech Stack
+
+- **Python 3.10+**, asyncio for concurrency
+- **FastAPI + Uvicorn** — web server, WebSocket
+- **httpx** — async HTTP client
+- **Jinja2** — report templates
+- **Vanilla JS + Chart.js** — frontend (no build step)
+- **pytest** — testing
+
+## Development Principles
+
+- **Build it right the first time.** Write complete, production-quality code on the first pass. Do not leave TODOs, placeholders, or partial implementations to revisit later.
+- **First principles thinking.** Understand the problem from the ground up before writing code. Don't copy patterns blindly — reason about why a particular approach is correct for this specific case.
+- **Honest feedback.** If the user's approach is wrong or suboptimal, say so directly with reasoning. Don't silently go along with a bad idea.
+- **Major changes require planning.** Any significant architectural change or new feature should be discussed and planned before implementation.
+- **PEP 8 compliance.** Follow PEP 8 style guidelines strictly.
+- **Lazy imports only when necessary.** Use module-level imports by default. Only use lazy imports when there's a concrete performance reason (e.g., heavy optional dependency in a rarely-used code path).
+
+## Conventions
+
+- **Type hints** on all function signatures
+- **Dataclasses** for data models (not Pydantic for internal models; Pydantic only for FastAPI request/response schemas)
+- **async/await** for all HTTP and I/O operations
+- **No comments** unless the "why" is non-obvious
+- Import order: stdlib, then third-party, then local (PEP 8)
+- Use `from __future__ import annotations` in all files
+
+## Git
+
+- Never use Co-Authored-By in commit messages
+- Use the repo owner's git credentials (already configured)
+- Write clear, concise commit messages describing what changed and why
+- Commit after every change
+
+## Async & Concurrency Discipline
+
+- All I/O-bound operations (HTTP requests, file reads during test runs, WebSocket) must use `async/await`. Never block the event loop with synchronous I/O.
+- Use `asyncio.Semaphore` to control concurrency — never create unbounded numbers of tasks.
+- Use `asyncio.Event` for cancellation signals — patterns must check the cancel event and stop gracefully.
+- Never mix `threading` with `asyncio` unless there is no async alternative. If threads are necessary, use `asyncio.to_thread()` to bridge.
+- All shared state accessed from multiple coroutines must be protected or designed to be safe (e.g., append-only lists, asyncio.Queue).
+- Connection pools (httpx.AsyncClient) must be properly opened and closed using async context managers.
+
+## Logging
+
+- Use Python's `logging` module with `logger = logging.getLogger(__name__)` in every module.
+- Log levels: `DEBUG` for detailed execution flow (request/response details, timing), `INFO` for high-level progress, `WARNING` for recoverable issues, `ERROR` for failures.
+- When the user enables debug mode (`--debug` flag or `OVERLOAD_DEBUG=1`), set root logger to `DEBUG`.
+- Default log level is `WARNING` for clean output.
+- Never use `print()` for diagnostic output — always use the logger. `print()` is only for CLI user-facing progress output.
+
+## Key Patterns
+
+- **Load patterns** implement `LoadPattern` protocol with `async execute()` method
+- **EventBus** decouples engine from transport (WebSocket, CLI print)
+- **Collection parser** flattens nested Postman items, handles auth inheritance
+- **Variable substitution** uses `{{var}}` regex with scoped resolution
+
+## Commands
+
+```bash
+# Development
+pip install -e ".[dev]"          # Install with dev deps
+python -m overload               # Run via module
+pytest tests/                    # Run tests
+pytest tests/ -x                 # Stop on first failure
+
+# Package
+python -m build                  # Build package
+pip install dist/*.whl           # Install built package
+```
+
+## Test Types
+
+Load, Stress, Spike, Soak, Ramp, Burst, Breakpoint, Custom (step-based), Rate Limit, Sequential Runner.
+
+## Dependencies
+
+Runtime: fastapi, uvicorn, httpx, jinja2, python-multipart
+Dev: pytest, pytest-asyncio
+
+## Contributing
+
+### Setup
+
+```bash
+git clone https://github.com/dprakash2101/overload
+cd overload
+python -m venv .venv && source .venv/bin/activate
+pip install -e ".[dev]"
+```
+
+### Before submitting a PR
+
+1. **Run the full test suite** — all tests must pass:
+   ```bash
+   pytest tests/
+   ```
+2. **Add tests** for any new behaviour. The test suite covers every module; new code should not lower coverage.
+3. **Follow the conventions** in this file — type hints, dataclasses, async/await, PEP 8, no unnecessary comments.
+4. **Keep PRs focused.** One feature or fix per PR. If you are refactoring and adding a feature, split them.
+
+### Areas open for contribution
+
+- **New load patterns** — implement the `LoadPattern` protocol in [src/overload/engine/load_patterns.py](src/overload/engine/load_patterns.py)
+- **Additional auth types** — extend `_apply_auth` in [src/overload/engine/http_client.py](src/overload/engine/http_client.py)
+- **Report improvements** — HTML/CSS/JS lives in [src/overload/report/templates/](src/overload/report/templates/)
+- **Browser UI features** — vanilla JS in [src/overload/web/static/js/](src/overload/web/static/js/)
+- **Collection format support** — parser in [src/overload/collection/parser.py](src/overload/collection/parser.py)
+
+### Submitting
+
+- Fork the repo, create a branch off `main`, open a PR against `main`.
+- Write a clear PR description: what changed, why, and how to test it.
+- Do not open PRs for cosmetic-only changes (whitespace, renaming for style preference).

overload_cli-0.1.0/CHANGELOG.md

@@ -0,0 +1,70 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+---
+
+## [0.1.0] — 2026-05-30
+
+First public release.
+
+### Added
+
+**Core engine**
+- Async HTTP engine built on `httpx` with connection pooling and configurable concurrency
+- 10 load test patterns: Burst, Load, Stress, Spike, Soak, Ramp, Breakpoint, Custom (stage-based), Rate Limit, Sequential
+- Postman Collection v2.1 parser — nested folders, auth inheritance, variable substitution, all body types (raw, form-data, urlencoded, GraphQL)
+
+**Authentication**
+- Bearer token auth
+- HTTP Basic auth
+- API key auth — header and query string placement
+- OAuth2 client-credentials flow — pre-run token acquisition with in-process caching and `expires_in` respect
+
+**Variable system**
+- Three-scope variable resolution: runtime (`--var`) > environment file > collection variables
+- Dynamic variables: `{{$guid}}`, `{{$timestamp}}`, `{{$randomInt}}`, `{{$randomBoolean}}`, `{{$randomEmail}}`
+- Recursive resolution (a variable whose value references another variable)
+
+**CI/CD assertions**
+- `--assert "p95_latency_ms<500"` inline threshold expressions (repeatable)
+- Exit code 1 on assertion failure — the primitive every CI system reads
+- JUnit XML output via `--junit report.xml` — native test results in GitHub Actions, GitLab, Jenkins
+- Colored terminal verdict table with per-assertion ✓/✗ rows
+- YAML config file (`overload.config.yaml`) for storing test configuration and thresholds in source control
+- `--config` flag to load the YAML config; CLI flags override file values
+
+**Browser UI**
+- FastAPI + Vanilla JS SPA — no build step, no Node.js required
+- Auto-detects Postman collections and environment files in the working directory
+- Live progress dashboard with Chart.js charts (RPS, latency, error rate)
+- Assertions editor with metric/operator/value rows
+- Save Config / Load Config — writes/reads `overload.config.yaml`
+- PASS/FAIL verdict banner with per-assertion breakdown
+- Past runs table with verdict badge
+- HTML report viewer
+
+**Reports**
+- HTML report with embedded Chart.js charts and verdict section
+- JSON export
+- CSV export (one row per request)
+- Reports written to `reports/` subdirectory
+
+**CLI**
+- `overload` — starts browser UI on port 3000
+- `overload run` — headless CLI mode with full flag surface
+- `overload sequential` — sequential runner for functional flows
+- `--open-report` — opens HTML report in browser after run
+
+**Supported metrics for assertions**
+`p50_latency_ms`, `p95_latency_ms`, `p99_latency_ms`, `max_latency_ms`, `mean_latency_ms`,
+`error_rate_pct`, `success_rate_pct`, `avg_rps`, `total_requests`, `rate_limited_count`
+
+**Test suite**
+- 124 unit tests across all layers (assertions, auth, collection parser, variables, HTTP client, models, report, API)
+- GitHub Actions CI matrix: Python 3.10 · 3.11 · 3.12 · 3.13
+
+[0.1.0]: https://github.com/dprakash2101/overload/releases/tag/v0.1.0

overload_cli-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Devi Prakash
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

overload_cli-0.1.0/PKG-INFO

@@ -0,0 +1,267 @@
+Metadata-Version: 2.4
+Name: overload-cli
+Version: 0.1.0
+Summary: Free load testing tool that reads Postman collections — browser UI + CLI
+Project-URL: Homepage, https://github.com/dprakash2101/overload
+Project-URL: Repository, https://github.com/dprakash2101/overload
+Project-URL: Issues, https://github.com/dprakash2101/overload/issues
+Project-URL: Documentation, https://dprakash2101.github.io/overload/
+Project-URL: Changelog, https://github.com/dprakash2101/overload/blob/main/CHANGELOG.md
+Author: Devi Prakash
+License-Expression: MIT
+License-File: LICENSE
+Keywords: api-testing,assertions,ci-cd,load-testing,performance,postman,stress-test
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Environment :: Web Environment
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+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 :: Software Development :: Testing
+Classifier: Topic :: System :: Networking
+Requires-Python: >=3.10
+Requires-Dist: fastapi>=0.100.0
+Requires-Dist: httpx>=0.24.0
+Requires-Dist: jinja2>=3.1.0
+Requires-Dist: python-multipart>=0.0.6
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: uvicorn[standard]>=0.20.0
+Provides-Extra: dev
+Requires-Dist: build; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.21; extra == 'dev'
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Requires-Dist: twine; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# Overload
+
+Free, open-source load testing tool that reads Postman collections. Run tests from a browser dashboard or the terminal CLI.
+
+**📚 [Read the Full Documentation](https://dprakash2101.github.io/overload/)**
+
+---
+
+## Install
+
+```bash
+pip install overload-cli
+```
+
+Or in dev mode from source:
+
+```bash
+git clone https://github.com/dprakash2101/overload
+cd overload
+pip install -e ".[dev]"
+```
+
+---
+
+## Two Ways to Run
+
+### Option 1 — Browser UI (results on screen)
+
+Run `overload` with no arguments. It starts a local server and opens a dashboard in your browser where you configure the test, watch live progress, and view charts and reports — **no terminal reading required**.
+
+```bash
+overload
+# Opens http://localhost:3000 automatically
+```
+
+**Step-by-step in the browser:**
+
+1. The app auto-detects any Postman collection JSON files in your working directory and lists them under **"Detected Files"**. Click **Load** next to the one you want.
+2. Optionally load a Postman environment file the same way.
+3. Pick the **Test Type** from the dropdown (Burst, Load, Stress, Spike, etc.).
+4. Adjust the config fields that appear (concurrency, RPS, duration, etc.).
+5. Click **Start Test**. The dashboard shows live progress: phase, request count, RPS, and a real-time latency chart.
+6. When the test finishes, click **View Report** to open the full HTML report in a new tab — latency charts, timeline scatter, per-second breakdown, and the raw request log.
+7. Click **Stop** at any time to cancel immediately with partial results saved.
+
+**Options:**
+
+```bash
+overload ui --port 8080          # Use a different port
+overload ui --no-browser         # Start server without auto-opening browser
+overload ui --host 0.0.0.0       # Bind to all interfaces (LAN access)
+```
+
+---
+
+### Option 2 — CLI (results in terminal)
+
+Run tests headlessly and see a progress bar + summary printed to the terminal. An HTML report is saved to disk.
+
+```bash
+overload run --collection path/to/collection.json --pattern burst
+```
+
+**Output looks like:**
+
+```
+  OVERLOAD — BURST TEST
+  Collection: my_api.json
+  Requests: 5
+  Run ID: burst_20260529_abc123
+
+  [####################] 100% (200 requests) — complete
+
+  Results:
+    Total: 200  OK: 198  Errors: 2
+    Latency — min: 45ms  p95: 312ms  max: 891ms
+    Duration: 4.2s  Avg RPS: 47.6
+
+  Report: /path/to/overload_report_20260529_abc123.html
+```
+
+**All CLI flags for `overload run`:**
+
+| Flag | Default | Description |
+|------|---------|-------------|
+| `--collection` | *(required)* | Path to Postman collection JSON |
+| `--environment` | — | Path to Postman environment JSON |
+| `--pattern` | `burst` | Test type: `load`, `stress`, `spike`, `soak`, `ramp`, `burst`, `breakpoint`, `custom`, `ratelimit` |
+| `--requests` | `200` | Total requests (burst / rate limit tests) |
+| `--concurrency` | `20` | Max simultaneous connections |
+| `--rps` | `50` | Target requests per second |
+| `--duration` | `300` | Test duration in seconds |
+| `--timeout` | `30` | Per-request timeout in seconds |
+| `--stages` | — | Custom stages JSON: `'[{"duration":60,"rps":100}]'` |
+| `--var KEY=VALUE` | — | Override a collection variable (repeatable) |
+| `--save-responses` | off | Save response bodies in the report |
+| `--no-verify-ssl` | off | Skip SSL certificate verification |
+| `--output` | `reports` | Directory to write the HTML report |
+| `--format` | `html` | Report format: `html`, `json`, `csv` |
+| `--assert EXPR` | — | Assertion threshold (repeatable), e.g. `p95_latency_ms<500` |
+| `--junit PATH` | — | Write JUnit XML report for CI systems |
+| `--config PATH` | — | Load config from `overload.config.yaml` |
+| `--open-report` | off | Open HTML report in browser after run |
+
+**Sequential runner (run requests in order):**
+
+```bash
+overload sequential --collection my_api.json --iterations 5 --delay 500
+```
+
+| Flag | Default | Description |
+|------|---------|-------------|
+| `--collection` | *(required)* | Path to Postman collection JSON |
+| `--environment` | — | Path to Postman environment JSON |
+| `--iterations` | `1` | How many times to run the full collection |
+| `--delay` | `0` | Milliseconds to wait between requests |
+| `--timeout` | `30` | Per-request timeout in seconds |
+| `--output` | `.` | Directory to write the HTML report |
+
+---
+
+## Test Types
+
+| Type | What it does |
+|------|-------------|
+| **Burst** | Fires all N requests at once as fast as possible |
+| **Load** | Sustained traffic — ramp up → hold at target RPS → ramp down |
+| **Stress** | Steps up RPS until errors exceed the failure threshold |
+| **Spike** | Baseline RPS → sudden spike → recovery, to test elasticity |
+| **Soak** | Steady low RPS over a long duration (find memory leaks / drift) |
+| **Ramp** | Linearly increases from start RPS to end RPS |
+| **Breakpoint** | Binary search to find the exact RPS where latency or errors degrade |
+| **Custom** | Define your own stages: `[{"duration": 60, "rps": 100}, ...]` |
+| **Rate Limit** | Verifies that the API enforces its rate limit correctly |
+| **Sequential** | Runs each request in collection order, N iterations |
+
+---
+
+## CI/CD Integration
+
+Overload can gate your CI pipeline. Add assertions and the process exits `1` on failure — the universal CI signal.
+
+**Inline assertions:**
+
+```bash
+overload run --collection api.json --pattern load --rps 100 --duration 60 \
+  --assert "p95_latency_ms<500" \
+  --assert "error_rate_pct<1" \
+  --junit results.xml
+```
+
+**Using a config file:**
+
+Save your test config with assertions to `overload.config.yaml` (the browser UI can do this via **Save Config**):
+
+```yaml
+test_type: load
+config:
+  target_rps: 100
+  hold_duration_seconds: 60
+  concurrency: 20
+thresholds:
+  - metric: p95_latency_ms
+    operator: "<"
+    value: 500
+  - metric: error_rate_pct
+    operator: "<"
+    value: 1
+```
+
+Then in CI:
+
+```bash
+overload run --collection api.json --config overload.config.yaml --junit results.xml
+```
+
+**GitHub Actions example:**
+
+```yaml
+- name: Run load test
+  run: |
+    pip install overload-cli
+    overload run --collection tests/api.json \
+      --config overload.config.yaml \
+      --junit results.xml
+
+- name: Publish test results
+  uses: dorny/test-reporter@v1
+  if: always()
+  with:
+    name: Load Test
+    path: results.xml
+    reporter: java-junit
+```
+
+**Available assertion metrics:** `p50_latency_ms`, `p95_latency_ms`, `p99_latency_ms`, `max_latency_ms`, `mean_latency_ms`, `error_rate_pct`, `success_rate_pct`, `avg_rps`, `total_requests`, `rate_limited_count`
+
+**Operators:** `<`, `<=`, `>`, `>=`, `==`
+
+---
+
+## Quick Reference
+
+```
+# See results in browser (recommended)
+overload
+
+# See results in terminal
+overload run --collection my_api.json --pattern burst --requests 100
+
+# Debug mode (verbose logging)
+overload --debug
+# or
+OVERLOAD_DEBUG=1 overload
+```
+
+---
+
+## Working Directory
+
+When you launch `overload` from a directory that contains Postman JSON files, the UI auto-detects and lists them. Start from your project folder:
+
+```bash
+cd path/to/my-api-tests/
+overload
+```
+
+The HTML report is also saved to the working directory after each test.