swagtrace 0.0.5__py3-none-any.whl

swagtrace/__main__.py

@@ -0,0 +1,5 @@
+import sys
+from swagtrace.cli import main
+
+if __name__ == "__main__":
+    sys.exit(main())

swagtrace/cli.py

@@ -0,0 +1,41 @@
+import argparse
+
+from swagtrace.core import load_commands
+
+
+def main():
+
+    common_parser = argparse.ArgumentParser(add_help=False)
+    common_parser.add_argument(
+        "--config",
+        default="swagtrace.toml",
+        help="Path to config file",
+    )
+
+    parser = argparse.ArgumentParser(
+        prog="swagtrace",
+        description="SwagTrace - API Test Recorder & Runner",
+        parents=[common_parser],
+    )
+
+    subparsers = parser.add_subparsers(dest="command", help="Available commands")
+
+    commands = load_commands(subparsers=subparsers)
+
+    args = parser.parse_args()
+
+    if hasattr(args, "func"):
+        command = args.command
+        kwargs = {
+            arg[0]: arg[1]
+            for arg in args._get_kwargs()
+            if arg[0] != "command" and arg[0] != "func"
+        }
+
+        commands.run_command_dependencies(command=command, **kwargs)
+
+        kwargs.pop("config")
+
+        return args.func(**kwargs)
+    else:
+        parser.print_help()

swagtrace/consts.py

@@ -0,0 +1,69 @@
+DEFAULT_YAML_FILE = "swagtrace.yaml"
+
+DEFAULT_TEST_MODULE_FOLDER = "swagtrace_tests"
+
+PREPARE_AND_FINAL_FORMAT_FILE  = """from subprocess import CompletedProcess
+# 1. Configuration & Variables
+# Define key-value pairs to be injected into the YAML template.
+# You can set static values here or dynamically update this dictionary inside prepare().
+# NOTE: Variable names (keys) are CASE-SENSITIVE (e.g., 'DB_PORT' != 'db_port').
+VARIABLES = {}
+
+# 2. Main Execution Phase
+# This function runs as the FINAL step, right after the 'execute' command in the YAML file has finished.
+# Place your core logic or post-processing tasks here.
+def main(cp: CompletedProcess):
+    print(cp.stdout)
+
+"""
+
+
+TEST_CASE_FORMAT_FILE = """from httpx import Response
+
+# -----------------------------------------------------------------------------
+# 1. CONFIGURATION & DYNAMIC VARIABLES
+# -----------------------------------------------------------------------------
+# Key-value pairs injected into the HTTP Request template (e.g., YAML/JSON).
+# You can define static defaults here or dynamically populate/override them 
+# inside the prepare() function.
+# NOTE: Variable names (keys) are CASE-SENSITIVE (e.g., 'TOKEN' != 'token').
+VARIABLES = %(variables)s
+
+
+# -----------------------------------------------------------------------------
+# 2. PREPARATION PHASE (PHASE 1 - Runs FIRST)
+# -----------------------------------------------------------------------------
+# Executed BEFORE generating the request template and making the HTTP call.
+# Use this to:
+# - Set up prerequisites (e.g., seed database, generate mock payload).
+# - Fetch authorization tokens or dynamic parameters.
+# - Inject values directly into the 'VARIABLES' dictionary.
+def prepare():
+    pass
+
+
+# -----------------------------------------------------------------------------
+# 3. ASSERTION & INSPECTION PHASE (PHASE 2 - Runs AFTER HTTP Request)
+# -----------------------------------------------------------------------------
+# Executed IMMEDIATELY after the API call finishes.
+# Receives the live 'requests.Response' object from the target server.
+# Use this to:
+# - Write custom asserts (e.g., assert response.status_code == 200).
+# - Parse response JSON/Headers and validate domain logic.
+# - Store state/IDs created by this request for downstream use.
+def main(response: Response):
+    pass
+
+
+# -----------------------------------------------------------------------------
+# 4. CLEANUP & TEARDOWN PHASE (PHASE 3 - Runs LAST)
+# -----------------------------------------------------------------------------
+# Executed as the final step after main() completes.
+# Use this optional step to clean up any side-effects or temporary data:
+# - Delete objects created in database/API during the test execution.
+# - Invalidate session tokens or flush temporary test state.
+def finalize():
+    pass
+
+"""
+

swagtrace/core/__init__.py

@@ -0,0 +1 @@
+from .commands import load_commands

swagtrace/core/commands.py

@@ -0,0 +1,25 @@
+from argparse import _SubParsersAction
+from collections.abc import Callable
+
+from swagtrace.schemas.commands import Command
+from swagtrace.shared import load_config
+
+from .initializer import set_initializer_command
+from .recorder import set_recorder_command
+from .tester import set_tester_command
+
+
+def load_commands(subparsers: _SubParsersAction) -> Command:
+
+    commands: dict[str, list[Callable]] = {}
+
+    init_command = set_initializer_command(subparsers=subparsers)
+    commands[init_command] = []
+
+    recorder_command = set_recorder_command(subparsers=subparsers)
+    commands[recorder_command] = [load_config]
+
+    tester_command = set_tester_command(subparsers=subparsers)
+    commands[tester_command] = [load_config]
+
+    return Command(commands=commands)

swagtrace/core/initializer.py

@@ -0,0 +1,175 @@
+from __future__ import annotations
+
+import json
+import shutil
+from argparse import _SubParsersAction
+from importlib.resources import files
+from pathlib import Path
+from typing import Any
+
+import httpx
+import yaml
+
+from swagtrace.consts import (
+    DEFAULT_TEST_MODULE_FOLDER,
+    DEFAULT_YAML_FILE,
+    PREPARE_AND_FINAL_FORMAT_FILE,
+)
+from swagtrace.schemas.yaml_schema import (
+    ElementInfo,
+    SwagTaceTestFormat,
+    prepareAndFinal,
+)
+
+
+def fetch_openapi(
+    url: str | None, file: str | None, timeout: float = 10.0
+) -> dict[str, Any]:
+    if file:
+        file_json_format_content = {}
+
+        with open(file, "r") as file_object:
+            if file.endswith((".yaml", ".yml")):
+                file_json_format_content = yaml.safe_load(file_object.read())
+            else:
+                file_json_format_content = json.load(file_object)
+        return file_json_format_content
+
+    else:
+        response = httpx.get(url, timeout=timeout)
+        response.raise_for_status()
+
+        content_type = response.headers.get("content-type", "")
+        if "yaml" in content_type or url.endswith((".yaml", ".yml")):
+            return yaml.safe_load(response.text)
+        return response.json()
+
+
+def extract_endpoints(spec: dict[str, Any]) -> SwagTaceTestFormat:
+
+    prepare = prepareAndFinal(execute="echo Starting tests ...")
+    final = prepareAndFinal(execute="echo test complete")
+    info = spec.get("info", {})
+    openapi = spec.get("openapi", "")
+
+    tags_map: dict[str, list[dict[str, Any]]] = {}
+
+    paths = spec.get("paths", {})
+
+    for path, path_item in paths.items():
+        if not isinstance(path_item, dict):
+            continue
+
+        for method, operation in path_item.items():
+            if method.lower() not in {
+                "get",
+                "post",
+                "put",
+                "patch",
+                "delete",
+                "head",
+                "options",
+            }:
+                continue
+            if not isinstance(operation, dict):
+                continue
+
+            tags = operation.get("tags", [])
+            tag = tags[0] if tags else "Default"
+
+            endpoint_info = ElementInfo(
+                method=method.upper(),
+                path=path,
+                operation_id=operation.get("operationId"),
+                summary=operation.get("summary"),
+                description=operation.get("description"),
+                cases=[],
+            )
+
+            if tag not in tags_map:
+                tags_map[tag] = []
+
+            tags_map[tag].append(endpoint_info)
+
+    return SwagTaceTestFormat(
+        openapi=openapi, info=info, prepare=prepare, tags=tags_map, final=final
+    )
+
+
+def save_endpoints_yaml(endpoints: SwagTaceTestFormat, output_path: str) -> None:
+    file_name = DEFAULT_YAML_FILE
+
+    output_path = Path(output_path) / Path(file_name)
+
+    endpoints = endpoints.model_dump()
+    with output_path.open("w", encoding="utf-8") as f:
+        yaml.dump(
+            endpoints, f, allow_unicode=True, sort_keys=False, default_flow_style=False
+        )
+
+
+def create_test_module(output_path: str):
+
+    output_path: Path = Path(output_path)
+    module_path: Path = output_path / Path(DEFAULT_TEST_MODULE_FOLDER)
+    __init__file = module_path / Path("__init__.py")
+    prepare_file = module_path / Path("prepare.py")
+    final_file = module_path / Path("final.py")
+
+    module_path.mkdir()
+
+    __init__file.touch()
+    prepare_file.write_text(PREPARE_AND_FINAL_FORMAT_FILE)
+    final_file.write_text(PREPARE_AND_FINAL_FORMAT_FILE)
+
+
+def init_config_file(output_path: str):
+    template_path = Path(files("swagtrace.templates").joinpath("config.toml"))
+    target_path = output_path / Path("swagtrace.toml")
+
+    shutil.copy(template_path, target_path)
+
+
+def discover_and_save(url: str, output: str, file: str | None = None):
+    print(f"Fetching OpenAPI from: {url}")
+    spec = fetch_openapi(url=url, file=file)
+
+    print("Extracting endpoints...")
+    endpoints = extract_endpoints(spec)
+
+    print("Generating yaml file ...")
+    save_endpoints_yaml(endpoints, output)
+
+    print("Creating Test Module ...")
+    create_test_module(output)
+
+    print("Initializing Config File ...")
+    init_config_file(output)
+
+
+def set_initializer_command(
+    subparsers: _SubParsersAction, command: str = "init"
+) -> str:
+    init_parser = subparsers.add_parser(command, help="initial project")
+    init_parser.add_argument(
+        "--url",
+        type=str,
+        help="url for openapi.json file",
+        default="http://localhost:8000/openapi.json",
+    )
+    init_parser.add_argument(
+        "--file",
+        type=str,
+        help="file of openapi. Json or Yaml format file",
+        required=False,
+    )
+    init_parser.add_argument(
+        "-o",
+        "--output",
+        type=str,
+        help="output path for files and folders",
+        default=".",
+    )
+    init_parser.set_defaults(func=discover_and_save)
+
+    return command

swagtrace/core/recorder.py

@@ -0,0 +1,346 @@
+import json
+import pprint
+import urllib.error
+import urllib.request
+from argparse import _SubParsersAction
+from functools import partial
+from http.server import BaseHTTPRequestHandler, HTTPServer
+from importlib.resources import files
+from pathlib import Path
+from string import Template
+from urllib.parse import parse_qsl, urlparse
+
+import yaml
+from yaml_syntax.syntax import YamlSyntax
+
+import swagtrace.monkey_patching
+from swagtrace.consts import DEFAULT_TEST_MODULE_FOLDER, DEFAULT_YAML_FILE
+from swagtrace.schemas.yaml_schema import SwagTaceTestFormat, TestCase
+from swagtrace.shared.backend import get_config
+from swagtrace.utils import get_yes_no_user_options, match_path_template
+
+
+# TODO: This is not a clean structure! Create an independent method or class to store and create test files.
+class APIRecorderProxyHandler(BaseHTTPRequestHandler):
+    def __init__(
+        self, yaml_syntax: YamlSyntax, host: str, test_module_path: str, *args, **kwargs
+    ):
+        self.yaml_syntax = yaml_syntax
+        self.host = host
+        self.test_module_path = Path(test_module_path)
+
+        self.yaml_schema = yaml_syntax.serialized_data
+
+        self.PATH_TO_CASES_MAPPER: dict[str, list[TestCase]] = {
+            f"{el.method.lower()}-{el.path}": el.cases
+            for _, elements in self.yaml_schema.tags.items()
+            for el in elements
+        }
+        self.PATH_TO_TAG_MAPPER: dict[str, str] = {
+            el.path: tag
+            for tag, elements in self.yaml_schema.tags.items()
+            for el in elements
+        }
+
+        config = get_config()
+
+        # TODO: Also use variables of recorder
+        self.BROWSER_NOISE_HEADERS = [
+            noise.lower() for noise in config.recorder.header_noise
+        ]
+        self.IS_ASYNC_FORMAT = config.project.type == "async"
+
+        super().__init__(*args, **kwargs)
+
+    def handle_proxy(self):
+        method = self.command
+        headers = self.headers
+        parsed_url = urlparse(self.path)
+
+        actual_path = parsed_url.path
+        if not actual_path.startswith("/"):
+            actual_path = "/" + actual_path
+
+        query_params = parse_qsl(parsed_url.query)
+        if query_params:
+            query_params = {query[0]: query[1] for query in query_params}
+        else:
+            query_params = {}
+
+        content_length = int(headers.get("Content-Length", 0))
+        body_bytes = self.rfile.read(content_length) if content_length > 0 else b""
+        body_str = body_bytes.decode("utf-8", errors="ignore") if body_bytes else ""
+
+        clean_headers = {
+            k: v
+            for k, v in headers.items()
+            if k.lower() not in self.BROWSER_NOISE_HEADERS
+        }
+
+        is_api_request = not any(
+            actual_path.endswith(ext)
+            for ext in [".js", ".css", ".png", ".ico", ".html"]
+        )
+
+        matched_template = None
+        variables = {}
+
+        if f"{method.lower()}-{actual_path}" in self.PATH_TO_CASES_MAPPER:
+            matched_template = actual_path
+
+        else:
+            for template in self.PATH_TO_CASES_MAPPER:
+                result = match_path_template(
+                    template, f"{method.lower()}-{actual_path}"
+                )
+                if result is not None:
+                    matched_template = template.split("-")[1]
+                    variables = result
+                    break
+
+        full_path = actual_path
+        if parsed_url.query:
+            full_path += f"?{parsed_url.query}"
+
+        target_url = f"{self.host}{full_path}"
+        forward_headers = {k: v for k, v in headers.items() if k.lower() != "host"}
+
+        req = urllib.request.Request(
+            url=target_url,
+            data=body_bytes if body_bytes else None,
+            headers=forward_headers,
+            method=method,
+        )
+
+        try:
+            with urllib.request.urlopen(req) as response:
+                res_status = response.status
+                res_headers = response.headers
+                res_body = response.read()
+
+                if is_api_request and matched_template is not None:
+                    self.captured(
+                        method=method,
+                        path=matched_template,
+                        headers=clean_headers,
+                        req_body=body_str,
+                        status_code=res_status,
+                        res_body_bytes=res_body,
+                        variables=variables,
+                        query_params=query_params,
+                    )
+
+                self.send_response(res_status)
+                for k, v in res_headers.items():
+                    if k.lower() not in ["transfer-encoding", "content-length"]:
+                        self.send_header(k, v)
+                self.send_header("Content-Length", str(len(res_body)))
+                self.end_headers()
+                self.wfile.write(res_body)
+
+        except urllib.error.HTTPError as e:
+            err_body = e.read()
+            err_status = e.status
+
+            if is_api_request and matched_template is not None:
+                self.captured(
+                    method=method,
+                    path=matched_template,
+                    headers=clean_headers,
+                    req_body=body_str,
+                    status_code=err_status,
+                    res_body_bytes=err_body,
+                    variables=variables,
+                    query_params=query_params,
+                )
+
+            self.send_response(e.code)
+
+            for k, v in e.headers.items():
+                if k.lower() not in ["transfer-encoding", "content-length"]:
+                    self.send_header(k, v)
+            self.send_header("Content-Length", str(len(err_body)))
+            self.end_headers()
+            self.wfile.write(err_body)
+
+        except Exception as e:
+            self.send_error(
+                502, f"Bad Gateway: Could not connect to {target_url}. Error: {e!s}"
+            )
+
+    def captured(
+        self,
+        method,
+        path,
+        headers,
+        req_body,
+        status_code,
+        res_body_bytes,
+        variables,
+        query_params,
+    ):
+        print("\n" + "═" * 60)
+        print(f"🎯 [CAPTURED API] {method} {path}")
+        print("─" * 60)
+
+        print("📋 HEADERS:")
+        for k, v in headers.items():
+            print(f"  {k}: {v}")
+
+        if req_body:
+            try:
+                req_body = json.loads(req_body)
+            except:
+                req_body = str(req_body)
+
+            print("─" * 60)
+            print("📦 BODY:")
+            print(req_body)
+
+        print("─" * 60)
+        print("💻 REPRODUCIBLE cURL:")
+        curl_headers = " ".join([f"-H '{k}: {v}'" for k, v in headers.items()])
+        curl_data = f" -d '{req_body}'" if req_body else ""
+        print(f"curl -X '{method}' '{self.host}{path}' {curl_headers}{curl_data}")
+        print("─" * 60)
+        print(f"Status Code: {status_code}")
+
+        res_body_str = (
+            res_body_bytes.decode("utf-8", errors="ignore") if res_body_bytes else ""
+        )
+        if res_body_str:
+            print("📦 RESPONSE BODY:")
+            try:
+                print(
+                    json.dumps(json.loads(res_body_str), indent=2, ensure_ascii=False)
+                )
+            except Exception:
+                print(res_body_str)
+        print("═" * 60 + "\n")
+
+        is_user_wants_save_this_case = get_yes_no_user_options(
+            "Do you want to save this case"
+        )
+
+        if is_user_wants_save_this_case:
+            is_user_wants_save_this_response = get_yes_no_user_options(
+                "Also Save Response Content"
+            )
+
+            res_body_str = (
+                None if not is_user_wants_save_this_response else res_body_str
+            )
+
+            case_name = input("Enter case name: ")
+            case_name = case_name.replace(" ", "_").lower()
+
+            case = TestCase(
+                name=case_name,
+                query_params=query_params,
+                request_header=headers,
+                request_body=req_body,
+                status_code=status_code,
+                response_content=res_body_str,
+            )
+
+            test_tag_folder = self.test_module_path / Path(
+                self.PATH_TO_TAG_MAPPER[path]
+            )
+            test_tag_folder.mkdir(exist_ok=True)
+
+            init_test_file = test_tag_folder / Path("__init__.py")
+            init_test_file.touch()
+
+            test_file_path = test_tag_folder / Path(f"{case_name}.py")
+
+            formatted_vars = pprint.pformat(variables, indent=4)
+
+            async_prefix = "async " if self.IS_ASYNC_FORMAT else ""
+
+            template_path = Path(
+                files("swagtrace.templates").joinpath("test_script.py.tmpl")
+            )
+            template_content = template_path.read_text()
+
+            template = Template(template_content)
+            rendered_code = template.substitute(
+                variables_dict=formatted_vars, async_prefix=async_prefix
+            )
+
+            with open(test_file_path, "w", encoding="utf-8") as f:
+                f.write(rendered_code)
+
+            # TODO: add validation if case name already exist!
+            self.PATH_TO_CASES_MAPPER[f"{method.lower()}-{path}"].append(case)
+
+    def do_CONNECT(self):
+        self.send_error(501, "CONNECT method is not supported by this proxy")
+
+    def handle_one_request(self):
+        try:
+            super().handle_one_request()
+        except BrokenPipeError:
+            pass
+        except ConnectionResetError:
+            pass
+
+    do_GET = handle_proxy
+    do_POST = handle_proxy
+    do_PUT = handle_proxy
+    do_DELETE = handle_proxy
+    do_PATCH = handle_proxy
+    do_HEAD = handle_proxy
+    do_OPTIONS = handle_proxy
+
+
+def run_server(host: str, port: int, file: str, dir: str):
+
+    yaml_syntax = YamlSyntax.from_file(SwagTaceTestFormat, file)
+
+    handler_class = partial(APIRecorderProxyHandler, yaml_syntax, host, dir)
+
+    server_address = ("", port)
+    httpd = HTTPServer(server_address, handler_class)
+    print(f"🚀 API Recorder Proxy running on http://127.0.0.1:{port}")
+    print("🎯 Capturing clean API requests for test replay...\n")
+    try:
+        httpd.serve_forever()
+    except KeyboardInterrupt:
+        print("\nStopping proxy server...")
+
+        file_address = Path(file)
+        with file_address.open("w", encoding="utf-8") as f:
+            yaml.dump(
+                yaml_syntax.to_json,
+                f,
+                allow_unicode=True,
+                sort_keys=False,
+                default_flow_style=False,
+            )
+
+        httpd.server_close()
+
+
+def set_recorder_command(subparsers: _SubParsersAction, command: str = "record") -> str:
+    recorder_parser = subparsers.add_parser(command, help="record requests API")
+    recorder_parser.add_argument(
+        "--host", type=str, help="API Base url", default="http://127.0.0.1:8000"
+    )
+    recorder_parser.add_argument(
+        "--port", type=int, help="Proxy Listen Port", default=8080
+    )
+    recorder_parser.add_argument(
+        "--file",
+        type=str,
+        help="path of swagtrace.yaml file",
+        default=DEFAULT_YAML_FILE,
+    )
+    recorder_parser.add_argument(
+        "--dir",
+        type=str,
+        help="path of test module",
+        default=DEFAULT_TEST_MODULE_FOLDER,
+    )
+    recorder_parser.set_defaults(func=run_server)
+
+    return command