api-forge-cli 1.0.0__py3-none-any.whl

api_forge/__init__.py

@@ -0,0 +1,3 @@
+"""api-forge — API Testing & Mock Server CLI."""
+
+__version__ = "1.0.0"

api_forge/__main__.py

@@ -0,0 +1,6 @@
+"""Allow running as python -m api_forge."""
+
+from api_forge.cli import cli
+
+if __name__ == "__main__":
+    cli()

api_forge/cli.py

@@ -0,0 +1,277 @@
+"""CLI entry point for api-forge."""
+
+from __future__ import annotations
+
+import asyncio
+import sys
+from pathlib import Path
+
+import click
+
+from . import __version__
+from .client import execute_request, run_load_test, run_test_suite
+from .mock_server import run_mock_server_blocking
+from .models import (
+    HttpMethod,
+    LoadTestConfig,
+    MockServerConfig,
+    RequestConfig,
+)
+from .output import (
+    console,
+    render_load_test_result,
+    render_quick_request,
+    render_test_suite_result,
+)
+from .parser import (
+    generate_example_load_test,
+    generate_example_mock_config,
+    generate_example_suite,
+    parse_load_test_config,
+    parse_mock_config,
+    parse_test_suite,
+)
+
+
+@click.group()
+@click.version_option(__version__, prog_name="api-forge")
+def cli():
+    """🔧 api-forge — API Testing & Mock Server CLI.
+
+    Test APIs, run load tests, and create mock servers from YAML
+    configuration files.
+
+    Examples:
+
+        api-forge test suite.yaml
+
+        api-forge load config.yaml
+
+        api-forge mock mock.yaml
+
+        api-forge get https://api.example.com/users
+    """
+
+
+@cli.command("test")
+@click.argument("file", type=click.Path(exists=True))
+@click.option("--verbose", "-v", is_flag=True, help="Show detailed output")
+def test_cmd(file: str, verbose: bool):
+    """Run API tests from a YAML test suite.
+
+    Examples:
+
+        api-forge test suite.yaml
+
+        api-forge test tests/api-tests.yaml -v
+    """
+    try:
+        suite = parse_test_suite(file)
+    except Exception as e:
+        console.print(f"[red]Failed to parse test suite: {e}[/]")
+        sys.exit(1)
+
+    console.print(f"[dim]Running test suite: {suite.name}[/]")
+
+    result = asyncio.run(run_test_suite(suite))
+    render_test_suite_result(result)
+
+    if result.failed > 0:
+        sys.exit(1)
+
+
+@cli.command("load")
+@click.argument("target", required=False)
+@click.option("--config", "-c", type=click.Path(exists=True), help="Load test config YAML file")
+@click.option("--concurrency", "-n", default=10, help="Number of concurrent connections")
+@click.option("--duration", "-d", default=10, help="Test duration in seconds")
+@click.option("--rps", default=0, help="Requests per second (0 = unlimited)")
+def load_cmd(target: str | None, config: str | None, concurrency: int, duration: int, rps: int):
+    """Run load tests against an API endpoint.
+
+    Examples:
+
+        api-forge load https://api.example.com/health
+
+        api-forge load -c loadtest.yaml
+
+        api-forge load https://api.example.com/users -n 50 -d 30
+    """
+    if config:
+        try:
+            load_config = parse_load_test_config(config)
+        except Exception as e:
+            console.print(f"[red]Failed to parse config: {e}[/]")
+            sys.exit(1)
+    elif target:
+        load_config = LoadTestConfig(
+            url=target,
+            concurrency=concurrency,
+            duration_seconds=duration,
+            requests_per_second=rps,
+        )
+    else:
+        console.print("[red]Please provide a URL or --config file[/]")
+        sys.exit(1)
+
+    console.print(f"[dim]Starting load test: {load_config.url}[/]")
+    console.print(f"[dim]Concurrency: {load_config.concurrency} | Duration: {load_config.duration_seconds}s[/]\n")
+
+    result = asyncio.run(run_load_test(load_config))
+    render_load_test_result(result)
+
+
+@cli.command("mock")
+@click.argument("file", type=click.Path(exists=True), required=False)
+@click.option("--port", "-p", default=8000, help="Server port")
+@click.option("--host", "-h", "host", default="127.0.0.1", help="Server host")
+def mock_cmd(file: str | None, port: int, host: str):
+    """Start a mock API server from YAML configuration.
+
+    Examples:
+
+        api-forge mock mock.yaml
+
+        api-forge mock mock.yaml -p 3000
+
+        api-forge mock  # Starts default server on :8000
+    """
+    if file:
+        try:
+            config = parse_mock_config(file)
+            config.port = port  # CLI override
+            config.host = host
+        except Exception as e:
+            console.print(f"[red]Failed to parse mock config: {e}[/]")
+            sys.exit(1)
+    else:
+        # Default mock server
+        config = MockServerConfig(host=host, port=port)
+
+    console.print(f"[bold green]🚀 Mock server running at http://{config.host}:{config.port}[/]")
+    console.print(f"[dim]Endpoints: {len(config.endpoints)}[/]")
+    console.print("[dim]Press Ctrl+C to stop[/]\n")
+
+    try:
+        run_mock_server_blocking(config)
+    except KeyboardInterrupt:
+        console.print("\n[yellow]Server stopped[/]")
+
+
+@cli.command("get")
+@click.argument("url")
+@click.option("--header", "-H", multiple=True, help="Headers (key:value)")
+@click.option("--timeout", "-t", default=30.0, help="Request timeout")
+def get_cmd(url: str, header: tuple, timeout: float):
+    """Make a GET request to a URL.
+
+    Examples:
+
+        api-forge get https://api.example.com/users
+
+        api-forge get https://api.example.com/users -H "Authorization:Bearer token"
+    """
+    _quick_request(url, HttpMethod.GET, header, None, timeout)
+
+
+@cli.command("post")
+@click.argument("url")
+@click.option("--data", "-d", help="Request body (JSON string)")
+@click.option("--header", "-H", multiple=True, help="Headers (key:value)")
+@click.option("--timeout", "-t", default=30.0, help="Request timeout")
+def post_cmd(url: str, data: str | None, header: tuple, timeout: float):
+    """Make a POST request to a URL.
+
+    Examples:
+
+        api-forge post https://api.example.com/users -d '{"name":"Alice"}'
+
+        api-forge post https://api.example.com/login -d '{"user":"admin"}' -H "Content-Type:application/json"
+    """
+    _quick_request(url, HttpMethod.POST, header, data, timeout)
+
+
+@cli.command("put")
+@click.argument("url")
+@click.option("--data", "-d", help="Request body (JSON string)")
+@click.option("--header", "-H", multiple=True, help="Headers (key:value)")
+@click.option("--timeout", "-t", default=30.0, help="Request timeout")
+def put_cmd(url: str, data: str | None, header: tuple, timeout: float):
+    """Make a PUT request to a URL.
+
+    Examples:
+
+        api-forge put https://api.example.com/users/1 -d '{"name":"Bob"}'
+    """
+    _quick_request(url, HttpMethod.PUT, header, data, timeout)
+
+
+@cli.command("delete")
+@click.argument("url")
+@click.option("--header", "-H", multiple=True, help="Headers (key:value)")
+@click.option("--timeout", "-t", default=30.0, help="Request timeout")
+def delete_cmd(url: str, header: tuple, timeout: float):
+    """Make a DELETE request to a URL.
+
+    Examples:
+
+        api-forge delete https://api.example.com/users/1
+    """
+    _quick_request(url, HttpMethod.DELETE, header, None, timeout)
+
+
+@cli.command("init")
+@click.option("--type", "init_type", type=click.Choice(["test", "load", "mock"]), default="test", help="Type of config to generate")
+@click.option("--output", "-o", help="Output file path")
+def init_cmd(init_type: str, output: str | None):
+    """Generate example configuration files.
+
+    Examples:
+
+        api-forge init --type test -o suite.yaml
+
+        api-forge init --type load -o loadtest.yaml
+
+        api-forge init --type mock -o mock.yaml
+    """
+    generators = {
+        "test": ("test-suite.yaml", generate_example_suite),
+        "load": ("load-test.yaml", generate_example_load_test),
+        "mock": ("mock-server.yaml", generate_example_mock_config),
+    }
+
+    default_name, generator = generators[init_type]
+    content = generator()
+    output_path = output or default_name
+
+    Path(output_path).write_text(content, encoding="utf-8")
+    console.print(f"[green]Created {output_path}[/]")
+
+
+def _quick_request(url: str, method: HttpMethod, headers: tuple, data: str | None, timeout: float) -> None:
+    """Execute a quick HTTP request."""
+    # Parse headers
+    parsed_headers = {}
+    for h in headers:
+        if ":" in h:
+            key, value = h.split(":", 1)
+            parsed_headers[key.strip()] = value.strip()
+
+    config = RequestConfig(
+        name="Quick Request",
+        url=url,
+        method=method,
+        headers=parsed_headers,
+        body=data,
+        timeout=timeout,
+    )
+
+    result = asyncio.run(execute_request(config))
+    render_quick_request(result)
+
+    if result.error or result.status_code >= 400:
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    cli()

api_forge/client.py

@@ -0,0 +1,197 @@
+"""HTTP client for API testing."""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import time
+
+import httpx
+
+from .models import (
+    LoadTestConfig,
+    LoadTestResult,
+    RequestConfig,
+    RequestResult,
+    TestSuite,
+    TestSuiteResult,
+)
+
+
+async def execute_request(
+    config: RequestConfig,
+    base_url: str = "",
+    global_headers: dict[str, str] | None = None,
+    variables: dict[str, str] | None = None,
+) -> RequestResult:
+    """Execute a single API request."""
+    # Resolve URL
+    url = config.url
+    if base_url and not url.startswith(("http://", "https://")):
+        url = f"{base_url.rstrip('/')}/{url.lstrip('/')}"
+
+    # Variable substitution
+    all_vars = {**(variables or {}), **config.variables}
+    url = _substitute_variables(url, all_vars)
+
+    # Merge headers
+    headers = {**(global_headers or {}), **config.headers}
+    headers = {k: _substitute_variables(v, all_vars) for k, v in headers.items()}
+
+    # Prepare body
+    body = config.body
+    if isinstance(body, dict):
+        body = json.dumps(body)
+    elif isinstance(body, str):
+        body = _substitute_variables(body, all_vars)
+
+    start = time.perf_counter()
+    result = RequestResult(
+        name=config.name,
+        url=url,
+        method=config.method.value,
+        status_code=0,
+        headers={},
+        body="",
+        duration_ms=0.0,
+    )
+
+    try:
+        async with httpx.AsyncClient(timeout=config.timeout, follow_redirects=True) as client:
+            response = await client.request(
+                method=config.method.value,
+                url=url,
+                headers=headers,
+                content=body,
+            )
+
+            result.status_code = response.status_code
+            result.headers = dict(response.headers)
+            result.body = response.text
+
+    except httpx.TimeoutException:
+        result.error = "Request timed out"
+    except httpx.ConnectError as e:
+        result.error = f"Connection failed: {e}"
+    except Exception as e:
+        result.error = f"Request failed: {e}"
+
+    result.duration_ms = (time.perf_counter() - start) * 1000
+
+    # Run assertions
+    for assertion in config.assertions:
+        assertion.evaluate(result)
+        result.assertions.append(assertion)
+
+    return result
+
+
+async def run_test_suite(suite: TestSuite) -> TestSuiteResult:
+    """Run all tests in a test suite."""
+    start = time.perf_counter()
+    result = TestSuiteResult(name=suite.name)
+
+    variables = dict(suite.variables)
+
+    for request in suite.requests:
+        req_result = await execute_request(
+            request,
+            base_url=suite.base_url,
+            global_headers=suite.headers,
+            variables=variables,
+        )
+        result.results.append(req_result)
+
+        # Extract variables from response for chaining
+        for var_name, json_path in request.variables.items():
+            from .models import _json_path_extract
+
+            extracted = _json_path_extract(req_result.body, json_path)
+            if extracted is not None:
+                variables[var_name] = str(extracted)
+
+    result.total_duration_ms = (time.perf_counter() - start) * 1000
+    return result
+
+
+async def run_load_test(config: LoadTestConfig) -> LoadTestResult:
+    """Run a load test against an endpoint."""
+    result = LoadTestResult(config=config)
+    start = time.perf_counter()
+    end_time = start + config.duration_seconds
+
+    # Prepare body
+    body = config.body
+    if isinstance(body, dict):
+        body = json.dumps(body)
+
+    semaphore = asyncio.Semaphore(config.concurrency)
+    tasks: list[asyncio.Task] = []
+
+    async def make_request() -> tuple[int, float, str | None]:
+        async with semaphore:
+            req_start = time.perf_counter()
+            try:
+                async with httpx.AsyncClient(timeout=config.timeout) as client:
+                    response = await client.request(
+                        method=config.method.value,
+                        url=config.url,
+                        headers=config.headers,
+                        content=body,
+                    )
+                    duration_ms = (time.perf_counter() - req_start) * 1000
+                    return response.status_code, duration_ms, None
+            except Exception as e:
+                duration_ms = (time.perf_counter() - req_start) * 1000
+                return 0, duration_ms, str(e)
+
+    # Generate requests until duration expires
+    request_count = 0
+    delay = 1.0 / config.requests_per_second if config.requests_per_second > 0 else 0
+
+    while time.perf_counter() < end_time:
+        tasks.append(asyncio.create_task(make_request()))
+        request_count += 1
+
+        if delay > 0:
+            await asyncio.sleep(delay)
+        else:
+            # Batch to avoid overwhelming event loop
+            if request_count % 100 == 0:
+                await asyncio.sleep(0.001)
+
+    # Wait for all requests to complete
+    responses = await asyncio.gather(*tasks, return_exceptions=True)
+
+    result.duration_seconds = time.perf_counter() - start
+
+    for resp in responses:
+        if isinstance(resp, Exception):
+            result.failed_requests += 1
+            result.errors.append(str(resp))
+            continue
+
+        status, latency, error = resp
+        result.total_requests += 1
+        result.latencies_ms.append(latency)
+
+        if error:
+            result.failed_requests += 1
+            if len(result.errors) < 10:  # Cap error samples
+                result.errors.append(error)
+        else:
+            result.successful_requests += 1
+            result.status_codes[status] = result.status_codes.get(status, 0) + 1
+
+    return result
+
+
+def _substitute_variables(text: str, variables: dict[str, str]) -> str:
+    """Replace {{var}} placeholders with variable values."""
+    import re
+
+    def replacer(match: re.Match) -> str:
+        var_name = match.group(1)
+        return variables.get(var_name, match.group(0))
+
+    return re.sub(r"\{\{(\w+)\}\}", replacer, text)

api_forge/mock_server.py

@@ -0,0 +1,190 @@
+"""Mock HTTP server for API testing."""
+
+from __future__ import annotations
+
+import json
+import time
+from http.server import BaseHTTPRequestHandler, HTTPServer
+from threading import Thread
+from typing import Any
+
+from .models import MockEndpoint, MockServerConfig
+
+
+class MockHandler(BaseHTTPRequestHandler):
+    """HTTP request handler for mock server."""
+
+    server_config: MockServerConfig
+
+    def log_message(self, format: str, *args: Any) -> None:
+        """Suppress default logging."""
+        pass
+
+    def _handle_request(self, method: str) -> None:
+        """Handle an incoming request."""
+        config = self.server_config
+        path = self.path.split("?")[0]  # Remove query string
+
+        # Read request body if present
+        content_length = int(self.headers.get("Content-Length", 0))
+        body = self.rfile.read(content_length).decode("utf-8") if content_length > 0 else ""
+
+        # Find matching endpoint
+        endpoint = self._find_endpoint(path, method, body)
+
+        if endpoint:
+            # Simulate latency
+            if endpoint.delay_ms > 0:
+                time.sleep(endpoint.delay_ms / 1000)
+
+            self._send_response(endpoint.status_code, endpoint.headers, endpoint.body)
+        else:
+            self._send_response(config.default_status, {}, config.default_body)
+
+    def _find_endpoint(self, path: str, method: str, body: str) -> MockEndpoint | None:
+        """Find a matching mock endpoint."""
+        for ep in self.server_config.endpoints:
+            # Check path match
+            if not self._path_matches(path, ep.path):
+                continue
+
+            # Check method match
+            if ep.method.value != method:
+                continue
+
+            # Check header requirements
+            if ep.match_headers:
+                headers_match = all(self.headers.get(k, "").lower() == v.lower() for k, v in ep.match_headers.items())
+                if not headers_match:
+                    continue
+
+            # Check body requirements
+            if ep.match_body and ep.match_body not in body:
+                continue
+
+            return ep
+
+        return None
+
+    def _path_matches(self, request_path: str, pattern: str) -> bool:
+        """Check if request path matches the pattern.
+
+        Supports simple wildcards: /users/* matches /users/123
+        """
+        if pattern == request_path:
+            return True
+
+        if "*" in pattern:
+            pattern_parts = pattern.split("/")
+            request_parts = request_path.split("/")
+
+            if len(pattern_parts) != len(request_parts):
+                return False
+
+            for pp, rp in zip(pattern_parts, request_parts):
+                if pp != "*" and pp != rp:
+                    return False
+            return True
+
+        return False
+
+    def _send_response(self, status: int, headers: dict[str, str], body: str | dict) -> None:
+        """Send HTTP response."""
+        self.send_response(status)
+
+        # CORS headers if enabled
+        if self.server_config.cors:
+            self.send_header("Access-Control-Allow-Origin", "*")
+            self.send_header("Access-Control-Allow-Methods", "GET, POST, PUT, PATCH, DELETE, OPTIONS")
+            self.send_header("Access-Control-Allow-Headers", "*")
+
+        # Custom headers
+        for key, value in headers.items():
+            self.send_header(key, value)
+
+        # Default content-type
+        if "Content-Type" not in headers:
+            self.send_header("Content-Type", "application/json")
+
+        self.end_headers()
+
+        # Body
+        if isinstance(body, dict):
+            body = json.dumps(body)
+        self.wfile.write(body.encode("utf-8"))
+
+    def do_GET(self) -> None:
+        self._handle_request("GET")
+
+    def do_POST(self) -> None:
+        self._handle_request("POST")
+
+    def do_PUT(self) -> None:
+        self._handle_request("PUT")
+
+    def do_PATCH(self) -> None:
+        self._handle_request("PATCH")
+
+    def do_DELETE(self) -> None:
+        self._handle_request("DELETE")
+
+    def do_HEAD(self) -> None:
+        self._handle_request("HEAD")
+
+    def do_OPTIONS(self) -> None:
+        """Handle CORS preflight requests."""
+        self.send_response(200)
+        if self.server_config.cors:
+            self.send_header("Access-Control-Allow-Origin", "*")
+            self.send_header("Access-Control-Allow-Methods", "GET, POST, PUT, PATCH, DELETE, OPTIONS")
+            self.send_header("Access-Control-Allow-Headers", "*")
+        self.end_headers()
+
+
+class MockServer:
+    """Mock HTTP server for API testing."""
+
+    def __init__(self, config: MockServerConfig):
+        self.config = config
+        self._server: HTTPServer | None = None
+        self._thread: Thread | None = None
+
+    def start(self) -> None:
+        """Start the mock server in a background thread."""
+        handler_class = type("ConfiguredMockHandler", (MockHandler,), {"server_config": self.config})
+        self._server = HTTPServer((self.config.host, self.config.port), handler_class)
+        self._thread = Thread(target=self._server.serve_forever, daemon=True)
+        self._thread.start()
+
+    def stop(self) -> None:
+        """Stop the mock server."""
+        if self._server:
+            self._server.shutdown()
+            self._server = None
+        if self._thread:
+            self._thread.join(timeout=1)
+            self._thread = None
+
+    @property
+    def url(self) -> str:
+        """Get the mock server URL."""
+        return f"http://{self.config.host}:{self.config.port}"
+
+    def __enter__(self) -> "MockServer":
+        self.start()
+        return self
+
+    def __exit__(self, *args: Any) -> None:
+        self.stop()
+
+
+def run_mock_server_blocking(config: MockServerConfig) -> None:
+    """Run the mock server in blocking mode (for CLI use)."""
+    handler_class = type("ConfiguredMockHandler", (MockHandler,), {"server_config": config})
+    server = HTTPServer((config.host, config.port), handler_class)
+    try:
+        server.serve_forever()
+    except KeyboardInterrupt:
+        pass
+    finally:
+        server.shutdown()