Metadata-Version: 2.5
Name: specforge-api
Version: 0.1.5
Summary: The interactive API client and automated contract testing engine for Python.
Project-URL: Homepage, https://github.com/specforge-api/specforge
Project-URL: Documentation, https://specforge-api.github.io/specforge/
Project-URL: Repository, https://github.com/specforge-api/specforge
Project-URL: Issues, https://github.com/specforge-api/specforge/issues
Author: SpecForge Team
License: MIT License
        
        Copyright (c) 2026 SpecForge Contributors
        
        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.
License-File: LICENSE
Keywords: api-client,contract-testing,fastapi,fuzzing,openapi,pytest,swagger,testing
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
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 :: Internet :: WWW/HTTP :: HTTP Servers
Classifier: Topic :: Software Development :: Testing
Requires-Python: >=3.9
Requires-Dist: httpx>=0.24.0
Requires-Dist: pydantic>=2.0.0
Requires-Dist: pyyaml>=6.0
Provides-Extra: all
Requires-Dist: fastapi>=0.100.0; extra == 'all'
Requires-Dist: flask>=2.3.0; extra == 'all'
Requires-Dist: rich>=13.0.0; extra == 'all'
Requires-Dist: typer>=0.9.0; extra == 'all'
Provides-Extra: cli
Requires-Dist: rich>=13.0.0; extra == 'cli'
Requires-Dist: typer>=0.9.0; extra == 'cli'
Provides-Extra: dev
Requires-Dist: mypy>=1.5.0; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.21.0; extra == 'dev'
Requires-Dist: pytest>=7.4.0; extra == 'dev'
Requires-Dist: ruff>=0.1.0; extra == 'dev'
Requires-Dist: types-pyyaml; extra == 'dev'
Provides-Extra: docs
Requires-Dist: mkdocs-material>=9.5.0; extra == 'docs'
Requires-Dist: mkdocs>=1.5.0; extra == 'docs'
Requires-Dist: pymdown-extensions>=10.7; extra == 'docs'
Provides-Extra: fastapi
Requires-Dist: fastapi>=0.100.0; extra == 'fastapi'
Provides-Extra: flask
Requires-Dist: flask>=2.3.0; extra == 'flask'
Description-Content-Type: text/markdown

# SpecForge ⚡

[![PyPI version](https://img.shields.io/pypi/v/specforge-api)](https://pypi.org/project/specforge-api/)
[![Python versions](https://img.shields.io/pypi/pyversions/specforge-api)](https://pypi.org/project/specforge-api/)
[![Documentation](https://img.shields.io/badge/docs-specforge--api.github.io-0f9488)](https://specforge-api.github.io/specforge/)
[![CI](https://github.com/specforge-api/specforge/actions/workflows/ci.yml/badge.svg)](https://github.com/specforge-api/specforge/actions/workflows/ci.yml)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)

**The Interactive API Client & Automated Contract Testing Engine for Python.**

A modern, drop-in Python library that replaces Swagger UI with a beautiful, responsive API workspace **and** automatically discovers boundary vulnerabilities, missing whitespace stripping, and unhandled 500 server crashes directly against your endpoints.

<p align="center">
  <img src="https://raw.githubusercontent.com/specforge-api/specforge/main/docs/images/specforge-preview.png" alt="SpecForge Interactive Studio & Contract Fuzzer" width="100%" />
</p>

---

## 🚀 Why SpecForge?

1. **Active Quality Gate, Not Just Passive Docs**: Traditional tools like Swagger UI only show the "happy path". SpecForge algorithmically analyzes your schema constraints and runs targeted boundary fuzzing right in your browser.
2. **"Zero 500s" Invariant**: Verifies that edge-case inputs (e.g. `"   "`, empty strings, off-by-one numbers, malformed emails) return clean client errors (`422/400`), never unhandled server exceptions (`500`).
3. **One-Click Pytest Exporter**: Discovered edge cases can be instantly exported into commit-ready `test_api_contracts.py` files with `@pytest.mark.parametrize`.
4. **Zero Frontend Build Dependencies**: The interactive workspace is fully compiled and inlined into the Python package. No Node.js or npm needed on your machine.

---

## 📦 Installation

```bash
pip install specforge-api
```

With framework extras:
```bash
pip install "specforge-api[fastapi]"   # FastAPI
pip install "specforge-api[flask]"     # Flask
pip install "specforge-api[all]"       # Full CLI & all framework adapters
```

---

## ⚡ Quickstart

### FastAPI

```python
from fastapi import FastAPI
from specforge import SpecForge

app = FastAPI(title="My API", version="1.0.0")

# Mount SpecForge (auto-detects /openapi.json)
SpecForge(app)

@app.post("/users")
def create_user(username: str, age: int):
    return {"status": "created", "username": username}
```

Now open `http://localhost:8000/docs` in your browser. You get:
- A modern, interactive dark/light mode API client (Try-It-Out, request history, multi-language code snippets).
- An integrated **Boundary & Contract Testing Tab** to run automated fuzzing on all endpoints with one click.

---

### Flask

```python
from flask import Flask
from specforge.flask import SpecForge

app = Flask(__name__)

# Register Blueprint
SpecForge(app, spec_url="/api/spec.json", path="/docs")
```

---

## 🧪 Schema-Aware Boundary Fuzzing

SpecForge generates targeted test cases according to field types:

| Field Type | Automated Test Coverage |
|---|---|
| **String** | Rejecting whitespace-only (`"   "`), empty strings (`""`), min/max bounds, Unicode 4-byte emojis, null bytes (`\x00`), format violations (email, uuid, datetime), and injection probes. |
| **Number / Integer** | Boundary checks (`min - 1`, `max + 1`), negative values on unsigned fields, zero checks, float-into-integer pollution, and integer overflow. |
| **Boolean** | Strict type testing vs loose coercion (`"true"`, `"yes"`, `1`, `0`, `null`). |
| **Array** | Empty lists (`[]`), `minItems` / `maxItems` boundaries, and `uniqueItems: true` duplicates. |
| **Object** | Combinatorial required field omission, extra unexpected keys (`additionalProperties: false`), and empty bodies. |

---

## 📁 Integrating Existing Project Tests

If your repository already contains test suites (written in `pytest` or `unittest`), SpecForge can automatically index and display them in a dedicated **Project Tests** tab and link them directly to their corresponding API routes.

### Quick Setup

Pass `test_paths` when mounting SpecForge in your application:

```python
from fastapi import FastAPI
from specforge import SpecForge

app = FastAPI()

# Mount SpecForge with existing project tests
SpecForge(
    app,
    test_paths=["tests"],  # Can be directories or individual test files
)
```

Now open `/docs` to see:
- **📁 Project Tests Tab**: Browse all repository tests, file paths, line numbers, docstrings, and parameter matrices.
- **Route Coverage Linking**: View your existing tests directly inside the API Explorer alongside SpecForge's automated boundary fuzzers.

### Linking Tests to API Routes

SpecForge associates existing tests with OpenAPI routes using two mechanisms:

#### 1. Automatic HTTP Client Detection (Zero Configuration)
If your test uses `TestClient`, `httpx`, or `requests` to call an API path, SpecForge automatically recognizes the route:
```python
def test_user_creation_underage(client):
    """Rejects underage registrations."""
    response = client.post("/api/v1/users", json={"username": "bob", "age": 16})
    assert response.status_code == 422
```

#### 2. Explicit Pytest Marker (Recommended for Complex Tests)
For tests with dynamic URLs or mocks, declare the endpoint explicitly:
```python
import pytest

@pytest.mark.endpoint("POST", "/api/v1/users")
def test_user_signup_pipeline():
    """End-to-end user registration and event dispatch."""
    ...
```

### 🔒 Security & Zero-Execution Guarantee

SpecForge uses **Python Static Abstract Syntax Tree (AST) parsing** to discover tests:
- **Zero Code Execution**: SpecForge **never** imports or executes your test files. Tests are analyzed purely as static syntax trees.
- **No Side Effects**: Discovering tests will never trigger database operations, background tasks, or network calls.
- **Path Sandboxing**: Scanned paths are strictly verified to remain within the project root directory, preventing any path traversal.

---

## 🛠️ CLI & CI/CD Pipeline

Run headless contract fuzzing in your continuous integration pipeline:

```bash
specforge test http://localhost:8000/openapi.json --fail-on-500
```

---

## 💻 Local Development & Testing Guide

### 1. Run the Interactive Live Demo (Zero Dependencies)
You can launch and explore SpecForge immediately using Python's standard library:
```bash
python examples/standalone_demo.py
```
Open **`http://localhost:8000/docs`** in your browser to:
- Test API endpoints and inspect formatted JSON responses.
- Click **"⚡ Run Boundary Test Suite"** to watch automated fuzzing of whitespace strings, negative numbers, and missing fields.
- Click **"🐍 Export to Pytest"** to view and copy auto-generated test code.

### 2. Run the Automated Unit Test Suite
```bash
pytest -v
```

### 3. Install in Another Project Locally (Editable Mode)
To use this local version inside any other Python app on your machine without publishing to PyPI:
```bash
# In your other project's directory and virtualenv:
pip install -e c:\Research-projects\specforge
```
*Any change you make in SpecForge source code will instantly reflect in your other application without reinstalling!*

### 4. Build a Distribution Wheel (.whl)
```bash
pip install build
python -m build
# Outputs wheel file in dist/specforge-0.1.0-py3-none-any.whl
```

---

## 📄 License

SpecForge is licensed under the [MIT License](LICENSE).
