synapse-hub 0.0.0-stage → 2.0.1

package/tools/flaky_detector.py

@@ -0,0 +1,222 @@
+#!/usr/bin/env python3
+"""
+Enterprise Flaky Test Detector & Quarantine Sentinel
+---------------------------------------------------
+Executes a target test scenario N times (default: 5) or parses historical JUnit XML
+reports to calculate the Flakiness Index, detect state flips, and recommend quarantine isolation.
+
+Usage:
+  python tools/flaky_detector.py --repeat 5 --cmd "python -m unittest tests/test_tools.py"
+  python tools/flaky_detector.py --reports "reports/**/junit*.xml"
+"""
+
+import os
+import sys
+import glob
+import json
+import time
+import argparse
+import subprocess
+import xml.etree.ElementTree as ET
+from datetime import datetime
+
+# Enforce UTF-8 stdout encoding for Windows console compatibility
+if hasattr(sys.stdout, 'reconfigure'):
+    try:
+        sys.stdout.reconfigure(encoding='utf-8')
+        sys.stderr.reconfigure(encoding='utf-8')
+    except Exception:
+        pass
+
+REPO_ROOT = os.path.abspath(os.path.join(os.path.dirname(__file__), ".."))
+REPORTS_DIR = os.path.join(REPO_ROOT, "reports")
+
+GREEN = "\033[92m"
+RED = "\033[91m"
+YELLOW = "\033[93m"
+CYAN = "\033[96m"
+BOLD = "\033[1m"
+RESET = "\033[0m"
+
+
+def run_command(cmd, timeout=300):
+    """Executes a shell command and returns (returncode, stdout, stderr, elapsed_ms)."""
+    start = time.time()
+    try:
+        res = subprocess.run(
+            cmd,
+            shell=True,
+            stdout=subprocess.PIPE,
+            stderr=subprocess.PIPE,
+            text=True,
+            timeout=timeout
+        )
+        elapsed_ms = round((time.time() - start) * 1000, 2)
+        return res.returncode, res.stdout, res.stderr, elapsed_ms
+    except subprocess.TimeoutExpired:
+        elapsed_ms = round((time.time() - start) * 1000, 2)
+        return -1, "", "Execution timed out", elapsed_ms
+
+
+def calculate_flakiness(runs):
+    """
+    Given a list of boolean statuses [True, False, True, ...],
+    calculates pass rate, flip count, and flakiness tier.
+    """
+    total = len(runs)
+    if total == 0:
+        return {
+            "total": 0,
+            "passes": 0,
+            "failures": 0,
+            "pass_rate": 0.0,
+            "flips": 0,
+            "status": "NO_DATA",
+            "quarantine": False
+        }
+
+    passes = sum(1 for r in runs if r)
+    failures = total - passes
+    pass_rate = round((passes / total) * 100, 1)
+
+    # Count transitions (Pass -> Fail or Fail -> Pass)
+    flips = 0
+    for i in range(len(runs) - 1):
+        if runs[i] != runs[i + 1]:
+            flips += 1
+
+    if pass_rate == 100.0:
+        status = "STABLE"
+        quarantine = False
+    elif pass_rate == 0.0:
+        status = "DETERMINISTIC_FAIL"
+        quarantine = False
+    elif pass_rate >= 80.0:
+        status = "MILD_FLAKE"
+        quarantine = (flips >= 2)
+    else:
+        status = "SEVERE_FLAKE"
+        quarantine = True
+
+    return {
+        "total": total,
+        "passes": passes,
+        "failures": failures,
+        "pass_rate": pass_rate,
+        "flips": flips,
+        "status": status,
+        "quarantine": quarantine
+    }
+
+
+def parse_junit_reports(glob_pattern):
+    """Parses JUnit XML report files and aggregates pass/fail counts by test case."""
+    test_results = {}
+    files = glob.glob(glob_pattern, recursive=True)
+    if not files:
+        print(f"⚠️  No JUnit XML reports found matching: {glob_pattern}")
+        return test_results
+
+    for f in files:
+        try:
+            tree = ET.parse(f)
+            root = tree.getroot()
+            for tc in root.iter("testcase"):
+                name = tc.attrib.get("name", "unknown")
+                classname = tc.attrib.get("classname", "")
+                full_id = f"{classname}#{name}" if classname else name
+                has_failure = tc.find("failure") is not None or tc.find("error") is not None
+                is_passed = not has_failure
+                test_results.setdefault(full_id, []).append(is_passed)
+        except Exception as e:
+            print(f"⚠️  Could not parse {f}: {e}")
+
+    return test_results
+
+
+def benchmark_live_command(cmd, iterations=5):
+    """Executes a live test command N times to observe flakiness in real time."""
+    print(f"\n{BOLD}{CYAN}======================================================================{RESET}")
+    print(f"{BOLD}{CYAN}      ENTERPRISE FLAKY TEST SENTINEL (Multi-Run Verification)        {RESET}")
+    print(f"{BOLD}{CYAN}======================================================================{RESET}")
+    print(f"  Target Command     : {cmd}")
+    print(f"  Repetition Count   : {iterations} consecutive iterations")
+    print(f"  Timestamp          : {datetime.now().strftime('%Y-%m-%d %H:%M:%S')}\n")
+
+    runs = []
+    latencies = []
+    for i in range(1, iterations + 1):
+        sys.stdout.write(f"  [Run {i}/{iterations}] Executing... ")
+        sys.stdout.flush()
+        code, stdout, stderr, ms = run_command(cmd)
+        is_pass = (code == 0)
+        runs.append(is_pass)
+        latencies.append(ms)
+        status_str = f"{GREEN}PASS{RESET}" if is_pass else f"{RED}FAIL (Exit {code}){RESET}"
+        print(f"{status_str} ({ms} ms)")
+
+    stats = calculate_flakiness(runs)
+    stats["latencies_ms"] = latencies
+    stats["avg_latency_ms"] = round(sum(latencies) / max(1, len(latencies)), 2)
+    stats["command"] = cmd
+
+    # Print Scorecard
+    print(f"\n{BOLD}======================================================================{RESET}")
+    print(f"{BOLD}                   FLAKINESS DIAGNOSTIC SCORECARD                     {RESET}")
+    print(f"{BOLD}======================================================================{RESET}")
+    print(f"  Pass Rate          : {stats['pass_rate']}% ({stats['passes']}/{stats['total']} passes)")
+    print(f"  Status Flips       : {stats['flips']} transitions")
+    print(f"  Average Runtime    : {stats['avg_latency_ms']} ms")
+    print(f"  Stability Status   : {stats['status']}")
+    
+    if stats["quarantine"]:
+        print(f"  Recommendation     : {RED}{BOLD}[QUARANTINE REQUIRED]{RESET} Tag with @quarantine immediately!")
+    else:
+        print(f"  Recommendation     : {GREEN}[SUITE APPROVED]{RESET} Test is deterministic.")
+    print(f"======================================================================\n")
+
+    # Persist Report
+    os.makedirs(REPORTS_DIR, exist_ok=True)
+    report_file = os.path.join(REPORTS_DIR, "quarantine_board.json")
+    with open(report_file, "w", encoding="utf-8") as fp:
+        json.dump(stats, fp, indent=2)
+    print(f"Detailed telemetry saved to: {report_file}")
+
+    return stats
+
+
+def main():
+    parser = argparse.ArgumentParser(description="Enterprise Flaky Test Detector & Quarantine Sentinel")
+    parser.add_argument("--cmd", "-c", default=None, help="Test command to execute repeatedly")
+    parser.add_argument("--repeat", "-r", type=int, default=5, help="Number of repetitions (default: 5)")
+    parser.add_argument("--reports", default=None, help="Glob pattern for JUnit XML reports to analyze")
+    args = parser.parse_args()
+
+    if args.cmd:
+        stats = benchmark_live_command(args.cmd, iterations=args.repeat)
+        sys.exit(1 if stats["quarantine"] else 0)
+    elif args.reports:
+        results = parse_junit_reports(args.reports)
+        quarantine_candidates = []
+        for test_id, runs in results.items():
+            st = calculate_flakiness(runs)
+            st["test_id"] = test_id
+            if st["quarantine"]:
+                quarantine_candidates.append(st)
+
+        print(f"\nAnalyzed {len(results)} distinct test scenarios from reports.")
+        print(f"Quarantine Candidates Detected: {len(quarantine_candidates)}")
+        for qc in quarantine_candidates:
+            print(f"  - {RED}{qc['test_id']}{RESET}: Pass rate {qc['pass_rate']}%, Flips: {qc['flips']}")
+
+        report_file = os.path.join(REPORTS_DIR, "quarantine_board.json")
+        with open(report_file, "w", encoding="utf-8") as fp:
+            json.dump(quarantine_candidates, fp, indent=2)
+        sys.exit(1 if quarantine_candidates else 0)
+    else:
+        parser.print_help()
+        sys.exit(0)
+
+
+if __name__ == "__main__":
+    main()

package/tools/fuzz_payloads.py

@@ -0,0 +1,197 @@
+#!/usr/bin/env python3
+"""
+Enterprise Edge-Case Fuzzing & Input Sanitization Payload Catalog
+------------------------------------------------------------------
+Supplies standardized boundary, resilience, and sanitization payloads
+for transforming functional automated test suites into robust input
+sanitization and vulnerability boundary validators.
+
+Categories Covered:
+  1. SQLi Harmless Polyglots (no data destruction, tests parser escaping)
+  2. XSS & Script Injection Polyglots
+  3. Unicode BiDi / RTL Trojan Source & Zero-Width characters
+  4. Multi-byte Emoji Surrogate Pairs & ZWJ Sequences
+  5. Extreme Length Strings (10^4 buffer stress testing)
+  6. Null Byte & Control Character Injections
+  7. Numeric Precision & IEEE-754 Boundary Limits
+"""
+
+import sys
+import json
+import argparse
+from typing import Dict, Any, List, Optional
+
+# Enforce UTF-8 stdout encoding for Windows console compatibility
+if hasattr(sys.stdout, 'reconfigure'):
+    try:
+        sys.stdout.reconfigure(encoding='utf-8')
+        sys.stderr.reconfigure(encoding='utf-8')
+    except Exception:
+        pass
+
+
+FUZZ_PAYLOAD_CATALOG: Dict[str, List[Dict[str, Any]]] = {
+    "sqli_polyglots": [
+        {"name": "Standard Tautology", "payload": "' OR '1'='1' -- ", "expected_status": 400},
+        {"name": "Inline Polyglot Comment", "payload": "SLEEP(0)/*'/*\"/*--", "expected_status": 400},
+        {"name": "Union Select Null Probe", "payload": "1' UNION SELECT NULL, NULL, NULL -- ", "expected_status": 400},
+        {"name": "Batched Query Delay Probe", "payload": "'; WAITFOR DELAY '0:0:0'--", "expected_status": 400},
+        {"name": "Admin Comment Bypass", "payload": "admin' -- ", "expected_status": 400}
+    ],
+    "xss_polyglots": [
+        {"name": "Standard Script Tag", "payload": "<script>alert(1)</script>", "expected_status": 400},
+        {"name": "Image Tag OnError", "payload": "<img src=x onerror=console.warn('qa_xss')>", "expected_status": 400},
+        {"name": "Universal Polyglot Vector", "payload": "javascript:/*--></title></style></textarea></script></xmp><svg/onload='+/\"/+/onmouseover=1+(alert)(1)//'>", "expected_status": 400},
+        {"name": "SVG FromCharCode Injection", "payload": "\"><svg/onload=alert(String.fromCharCode(88,83,83))>", "expected_status": 400}
+    ],
+    "unicode_bidi_rtl": [
+        {"name": "Right-to-Left Override (Trojan Source)", "payload": "\u202E\u0041\u0042\u0043_AUTO_TX", "expected_status": 400},
+        {"name": "Zero-Width Space & Joiner Injection", "payload": "AUTO\u200B\u200C\u200D_DATA", "expected_status": 400},
+        {"name": "Byte Order Mark (BOM) In-String", "payload": "\uFEFFAUTO_USER", "expected_status": 400},
+        {"name": "Mixed BiDi Arabic/Latin", "payload": "USER_مرحبا_بالعالم_2026", "expected_status": 200}
+    ],
+    "emoji_surrogates": [
+        {"name": "Complex ZWJ Family Sequence", "payload": "👨‍👩‍👧‍👦_QA_RECORD", "expected_status": 200},
+        {"name": "Rainbow Flag Multi-Code", "payload": "🏳️‍🌈_FLAG_TAG", "expected_status": 200},
+        {"name": "Unpaired Surrogate Pair Boundary", "payload": "\uD83D\uDE00\uD83D", "expected_status": 400},
+        {"name": "4-Byte High Plane UTF-8", "payload": "🔥🚀⚡🧪✨", "expected_status": 200}
+    ],
+    "extreme_length": [
+        {"name": "10^4 (10,000 Chars) Buffer Stress", "payload": "A" * 10000, "expected_status": 400},
+        {"name": "1,024 Chars Text Block", "payload": "X" * 1024, "expected_status": 400},
+        {"name": "Repetitive Delimiter Stress", "payload": "{\"test\": [" + ",".join(["1"] * 500) + "]}", "expected_status": 400}
+    ],
+    "null_byte_control": [
+        {"name": "Null Byte Extension Truncation", "payload": "document\x00.pdf", "expected_status": 400},
+        {"name": "URL Encoded Null Byte", "payload": "test%00.png", "expected_status": 400},
+        {"name": "Carriage Return Linefeed Header Split", "payload": "test\r\nSet-Cookie: QA_LEAK=1", "expected_status": 400}
+    ],
+    "numeric_boundaries": [
+        {"name": "32-bit Integer Max Overflow", "payload": 2147483648, "expected_status": 400},
+        {"name": "32-bit Integer Min Underflow", "payload": -2147483649, "expected_status": 400},
+        {"name": "64-bit BigInt Max Boundary", "payload": 9223372036854775807, "expected_status": 200},
+        {"name": "JavaScript MAX_SAFE_INTEGER + 1", "payload": 9007199254740992, "expected_status": 400},
+        {"name": "IEEE-754 Extreme Float Overflow", "payload": 1e308, "expected_status": 400},
+        {"name": "Negative Zero Float", "payload": -0.0, "expected_status": 200}
+    ]
+}
+
+
+def get_fuzz_payloads(category: Optional[str] = None) -> Dict[str, List[Dict[str, Any]]]:
+    """Returns payloads filtered by category or the entire catalog."""
+    if category and category.lower() != "all":
+        cat_key = category.lower()
+        if cat_key in FUZZ_PAYLOAD_CATALOG:
+            return {cat_key: FUZZ_PAYLOAD_CATALOG[cat_key]}
+        # Fuzzy match
+        for k in FUZZ_PAYLOAD_CATALOG:
+            if cat_key in k:
+                return {k: FUZZ_PAYLOAD_CATALOG[k]}
+    return FUZZ_PAYLOAD_CATALOG
+
+
+def get_field_fuzz_scenarios(field_name: str, field_type: str = "string") -> List[Dict[str, Any]]:
+    """
+    Generates actionable test scenarios for a given field name and data type.
+    """
+    scenarios = []
+    if field_type == "string":
+        # 1. SQLi Polyglot
+        scenarios.append({
+            "scenario": f"{field_name} SQLi Polyglot Sanitization",
+            "category": "SECURITY_SANITY",
+            "value": FUZZ_PAYLOAD_CATALOG["sqli_polyglots"][0]["payload"],
+            "expected": 400
+        })
+        # 2. XSS Probe
+        scenarios.append({
+            "scenario": f"{field_name} XSS Universal Polyglot",
+            "category": "SECURITY_SANITY",
+            "value": FUZZ_PAYLOAD_CATALOG["xss_polyglots"][1]["payload"],
+            "expected": 400
+        })
+        # 3. BiDi RTL Trojan Source
+        scenarios.append({
+            "scenario": f"{field_name} Unicode BiDi RTL Override",
+            "category": "RESILIENCE_UNICODE",
+            "value": FUZZ_PAYLOAD_CATALOG["unicode_bidi_rtl"][0]["payload"],
+            "expected": 400
+        })
+        # 4. Multi-byte Emoji Surrogate
+        scenarios.append({
+            "scenario": f"{field_name} Emoji Surrogate & ZWJ Sequence",
+            "category": "RESILIENCE_UNICODE",
+            "value": FUZZ_PAYLOAD_CATALOG["emoji_surrogates"][0]["payload"],
+            "expected": 200
+        })
+        # 5. Extreme Length 10^4
+        scenarios.append({
+            "scenario": f"{field_name} 10^4 Chars Buffer Stress",
+            "category": "RESILIENCE_OVERFLOW",
+            "value": "A" * 10000,
+            "expected": 400
+        })
+        # 6. Null Byte Injection
+        scenarios.append({
+            "scenario": f"{field_name} Null Byte Injection",
+            "category": "SECURITY_SANITY",
+            "value": "item\x00_test",
+            "expected": 400
+        })
+
+    elif field_type in ("integer", "number"):
+        for item in FUZZ_PAYLOAD_CATALOG["numeric_boundaries"]:
+            scenarios.append({
+                "scenario": f"{field_name} {item['name']}",
+                "category": "RESILIENCE_NUMERIC",
+                "value": item["payload"],
+                "expected": item["expected_status"]
+            })
+
+    return scenarios
+
+
+def main():
+    parser = argparse.ArgumentParser(description="Edge-Case Fuzzing & Input Sanitization Payload Generator")
+    parser.add_argument("--category", default="all", help="Payload category (sqli, xss, bidi, emoji, length, null, numeric, or all)")
+    parser.add_argument("--field", default="", help="Optional field name to generate targeted boundary suite")
+    parser.add_argument("--type", default="string", choices=["string", "integer", "number"], help="Field data type")
+    parser.add_argument("--json", action="store_true", help="Output results in JSON format")
+    args = parser.parse_args()
+
+    if args.field:
+        scenarios = get_field_fuzz_scenarios(args.field, field_type=args.type)
+        if args.json:
+            print(json.dumps(scenarios, indent=2, ensure_ascii=False))
+        else:
+            print(f"\n======================================================================")
+            print(f"      EDGE-CASE FUZZING SCENARIOS FOR FIELD: '{args.field}' ({args.type.upper()})")
+            print(f"======================================================================")
+            for idx, sc in enumerate(scenarios, start=1):
+                val_disp = repr(sc['value']) if len(str(sc['value'])) < 60 else repr(str(sc['value'])[:50] + "...")
+                print(f"  [{idx:02d}] {sc['scenario']:<45} | Expected: HTTP {sc['expected']} | Value: {val_disp}")
+            print()
+        return 0
+
+    catalog = get_fuzz_payloads(args.category)
+    if args.json:
+        print(json.dumps(catalog, indent=2, ensure_ascii=False))
+    else:
+        print(f"\n======================================================================")
+        print(f"         ENTERPRISE EDGE-CASE FUZZING & SANITIZATION CATALOG          ")
+        print(f"======================================================================")
+        total_payloads = sum(len(items) for items in catalog.values())
+        print(f"Categories: {len(catalog)} | Total Payloads: {total_payloads}\n")
+
+        for cat, items in catalog.items():
+            print(f"📁 [{cat.upper()}] ({len(items)} vectors):")
+            for it in items:
+                p_disp = repr(it['payload']) if len(str(it['payload'])) < 60 else repr(str(it['payload'])[:50] + "...")
+                print(f"   • {it['name']:<35} -> HTTP {it['expected_status']} | {p_disp}")
+            print()
+
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/tools/generate_allure_report.ps1

@@ -0,0 +1,30 @@
+Write-Host "==========================================================" -ForegroundColor Cyan
+Write-Host "   ENTERPRISE AUTOMATION - ALLURE REPORT GENERATOR" -ForegroundColor Cyan
+Write-Host "==========================================================" -ForegroundColor Cyan
+
+$projectDir = Split-Path -Parent $PSScriptRoot
+$resultsDir = Join-Path $projectDir "allure-results"
+$reportDir  = Join-Path $projectDir "allure-report"
+
+if (-not (Test-Path $resultsDir)) {
+    Write-Host "[!] Không tìm thấy thư mục: $resultsDir" -ForegroundColor Yellow
+    Write-Host "[!] Hãy thực thi Test Suite trước để sinh dữ liệu kết quả." -ForegroundColor Yellow
+    exit 0
+}
+
+# Kiểm tra Allure CLI
+$allureCmd = Get-Command allure -ErrorAction SilentlyContinue
+
+if ($allureCmd) {
+    Write-Host "[+] Đang xuất báo cáo Allure HTML..." -ForegroundColor Green
+    allure generate $resultsDir -o $reportDir --clean
+    Write-Host "[+] Xuất báo cáo hoàn tất tại: $reportDir" -ForegroundColor Green
+    Write-Host "[+] Đang mở báo cáo trên trình duyệt..." -ForegroundColor Cyan
+    allure open $reportDir
+} else {
+    Write-Host "[!] Không tìm thấy công cụ Allure CLI trong hệ thống." -ForegroundColor Yellow
+    Write-Host "[*] Hướng dẫn cài đặt nhanh:" -ForegroundColor White
+    Write-Host "    Cách 1: npm install -g allure-commandline" -ForegroundColor Gray
+    Write-Host "    Cách 2: scoop install allure" -ForegroundColor Gray
+    Write-Host "    Cách 3: choco install allure-commandline" -ForegroundColor Gray
+}

package/tools/generate_api_matrix.py

@@ -0,0 +1,193 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""
+tools/generate_api_matrix.py — OpenAPI / Swagger to E2E Testing Matrix Generator
+Generates Positive, Boundary Value, Negative, and Edge-Case Fuzzing scenarios from API schemas.
+Compatible with Windows, macOS, and Linux.
+"""
+
+import sys
+import os
+import json
+import argparse
+
+SCRIPT_DIR = os.path.dirname(os.path.abspath(__file__))
+if SCRIPT_DIR not in sys.path:
+    sys.path.insert(0, SCRIPT_DIR)
+
+try:
+    from fuzz_payloads import get_field_fuzz_scenarios
+except ImportError:
+    get_field_fuzz_scenarios = None
+
+
+def generate_field_boundaries(field_name, field_schema):
+    f_type = field_schema.get("type", "string")
+    boundaries = []
+
+    if f_type == "string":
+        min_l = field_schema.get("minLength", 1)
+        max_l = field_schema.get("maxLength", 50)
+        boundaries.append({"scenario": f"{field_name} Empty String", "value": "", "expected": 400})
+        boundaries.append({"scenario": f"{field_name} Below MinLength ({min_l - 1} chars)", "value": "A" * max(0, min_l - 1), "expected": 400 if min_l > 0 else 200})
+        boundaries.append({"scenario": f"{field_name} Exact MaxLength ({max_l} chars)", "value": "A" * max_l, "expected": 200})
+        boundaries.append({"scenario": f"{field_name} Exceed MaxLength ({max_l + 1} chars)", "value": "A" * (max_l + 1), "expected": 400})
+        boundaries.append({"scenario": f"{field_name} Special & XSS Payload", "value": "<script>alert(1)</script>", "expected": 400})
+
+        # --- Enterprise Edge-Case Fuzzing & Input Sanitization Scenarios ---
+        if get_field_fuzz_scenarios:
+            fuzz_items = get_field_fuzz_scenarios(field_name, "string")
+            for item in fuzz_items:
+                boundaries.append({
+                    "scenario": item["scenario"],
+                    "value": item["value"],
+                    "expected": item["expected"]
+                })
+        else:
+            boundaries.append({"scenario": f"{field_name} SQLi Polyglot Probe", "value": "' OR '1'='1' -- ", "expected": 400})
+            boundaries.append({"scenario": f"{field_name} Unicode BiDi RTL Override", "value": "\u202E\u0041\u0042\u0043_AUTO_TX", "expected": 400})
+            boundaries.append({"scenario": f"{field_name} Emoji Surrogate & ZWJ Sequence", "value": "👨‍👩‍👧‍👦_QA_TAG", "expected": 200})
+            boundaries.append({"scenario": f"{field_name} Extreme Length 10^4 Buffer Stress", "value": "A" * 10000, "expected": 400})
+            boundaries.append({"scenario": f"{field_name} Null Byte Truncation Injection", "value": "data\x00.json", "expected": 400})
+
+    elif f_type in ("integer", "number"):
+        minimum = field_schema.get("minimum", 0)
+        maximum = field_schema.get("maximum", 1000)
+        boundaries.append({"scenario": f"{field_name} Negative Value ({minimum - 1})", "value": minimum - 1, "expected": 400})
+        boundaries.append({"scenario": f"{field_name} Boundary Minimum ({minimum})", "value": minimum, "expected": 200})
+        boundaries.append({"scenario": f"{field_name} Boundary Maximum ({maximum})", "value": maximum, "expected": 200})
+        boundaries.append({"scenario": f"{field_name} Exceed Maximum ({maximum + 1})", "value": maximum + 1, "expected": 400})
+        boundaries.append({"scenario": f"{field_name} 32-bit Integer Overflow (2^31)", "value": 2147483648, "expected": 400})
+
+    elif f_type == "boolean":
+        boundaries.append({"scenario": f"{field_name} Invalid String Instead of Boolean", "value": "not_a_bool", "expected": 400})
+
+    return boundaries
+
+
+def parse_spec(spec_data):
+    matrix = []
+    paths = spec_data.get("paths", {})
+
+    for endpoint, methods in paths.items():
+        for method, details in methods.items():
+            if method.lower() not in ("get", "post", "put", "delete", "patch"):
+                continue
+
+            summary = details.get("summary", details.get("operationId", f"{method.upper()} {endpoint}"))
+            req_body = details.get("requestBody", {}).get("content", {}).get("application/json", {}).get("schema", {})
+            properties = req_body.get("properties", {})
+            required_fields = req_body.get("required", [])
+
+            # 1. Happy Path
+            matrix.append({
+                "endpoint": endpoint,
+                "method": method.upper(),
+                "type": "POSITIVE",
+                "name": f"TC_API_{method.upper()}_{endpoint.replace('/', '_')}_HappyPath",
+                "description": f"Valid payload execution for {summary}",
+                "expected_status": 200 if method.lower() == "get" else 201
+            })
+
+            # 2. Missing Required Fields (Negative)
+            for req in required_fields:
+                matrix.append({
+                    "endpoint": endpoint,
+                    "method": method.upper(),
+                    "type": "NEGATIVE",
+                    "name": f"TC_API_{method.upper()}_{endpoint.replace('/', '_')}_Missing_{req}",
+                    "description": f"Submit request omitting required field '{req}'",
+                    "expected_status": 400
+                })
+
+            # 3. Boundary Values & Edge-Case Fuzzing
+            for fname, fschema in properties.items():
+                b_list = generate_field_boundaries(fname, fschema)
+                for b in b_list:
+                    clean_scenario = b['scenario'].replace(' ', '_').replace('(', '').replace(')', '').replace('&', 'and')
+                    val_str = str(b['value'])
+                    if len(val_str) > 30:
+                        val_str = val_str[:27] + "..."
+                    matrix.append({
+                        "endpoint": endpoint,
+                        "method": method.upper(),
+                        "type": "BOUNDARY",
+                        "name": f"TC_API_{method.upper()}_{endpoint.replace('/', '_')}_{clean_scenario}",
+                        "description": f"Boundary/Fuzz testing: {b['scenario']} with value '{val_str}'",
+                        "expected_status": b["expected"]
+                    })
+
+    return matrix
+
+
+def to_markdown(matrix):
+    lines = []
+    lines.append("# Automated E2E & API Contract Testing Matrix")
+    lines.append("")
+    lines.append("| ID | Method | Endpoint | Test Type | Scenario Description | Expected Status |")
+    lines.append("| :--- | :---: | :--- | :---: | :--- | :---: |")
+
+    for idx, tc in enumerate(matrix, 1):
+        lines.append(f"| TC-API-{idx:03d} | `{tc['method']}` | `{tc['endpoint']}` | **{tc['type']}** | {tc['description']} | `{tc['expected_status']}` |")
+
+    return "\n".join(lines)
+
+
+def main():
+    parser = argparse.ArgumentParser(description="Generate E2E Positive, Boundary, and Negative test matrix from OpenAPI/Swagger schema.")
+    parser.add_argument("--spec", "-s", help="Path to OpenAPI / Swagger JSON schema file.")
+    parser.add_argument("--format", "-f", choices=["md", "json"], default="md", help="Output format (markdown or json).")
+    parser.add_argument("--output", "-o", help="Output file path.")
+    parser.add_argument("--sample", action="store_true", help="Generate a sample matrix using built-in demonstration schema.")
+    args = parser.parse_args()
+
+    if args.sample or not args.spec:
+        sample_spec = {
+            "paths": {
+                "/api/v1/categories": {
+                    "post": {
+                        "summary": "Create new category",
+                        "requestBody": {
+                            "content": {
+                                "application/json": {
+                                    "schema": {
+                                        "type": "object",
+                                        "required": ["code", "name"],
+                                        "properties": {
+                                            "code": {"type": "string", "minLength": 3, "maxLength": 20},
+                                            "name": {"type": "string", "minLength": 1, "maxLength": 100},
+                                            "priority": {"type": "integer", "minimum": 1, "maximum": 100}
+                                        }
+                                    }
+                                }
+                            }
+                        }
+                    }
+                }
+            }
+        }
+        spec_data = sample_spec
+    else:
+        if not os.path.exists(args.spec):
+            print(f"Error: Specification file not found: {args.spec}", file=sys.stderr)
+            sys.exit(1)
+        with open(args.spec, "r", encoding="utf-8") as fp:
+            spec_data = json.load(fp)
+
+    matrix = parse_spec(spec_data)
+
+    if args.format == "json":
+        result = json.dumps(matrix, indent=2, ensure_ascii=False)
+    else:
+        result = to_markdown(matrix)
+
+    if args.output:
+        with open(args.output, "w", encoding="utf-8") as fp:
+            fp.write(result)
+        print(f"✅ Matrix successfully generated to: {args.output} ({len(matrix)} test cases)")
+    else:
+        print(result)
+
+
+if __name__ == "__main__":
+    main()