apitestgen-cli 0.5.35__cp315-cp315-win_amd64.whl

apitestgen/analyzer/backend_enrich/__init__.py

@@ -0,0 +1,13 @@
+"""Enrich `.apitestgen/*.json` with information mined from a Java Spring backend repo.
+
+The package is a self-contained `analyze enrich` subcommand. Submodules:
+
+- ``cli``                 — argparse entry point mounted via ``apitestgen analyze enrich``
+- ``java_lex``            — shared regex / Java string-literal helpers
+- ``controller_index``    — A1-A4: scan controllers, build (method, path) → (file, java_method, ...)
+- ``dto_resolver``        — B5-B9: locate request DTOs, extract JSR-380 annotations + enums
+- ``response_resolver``   — C10: identify wrapper class (R<T> / Result<T> / ...) + inner T
+- ``error_codes``         — C11-C12: error-code constant dictionary + service-layer throw inversion
+- ``meta_extractor``      — E13-E14: @Tag module label + BaseEntity audit fields
+- ``merge``               — fold resolver outputs into ``<api>.enriched.json``
+"""

apitestgen/common/__init__.py

@@ -0,0 +1,3 @@
+"""Shared helpers for recorder and analyzer modules."""
+
+from .stdio import configure_utf8_stdio

apitestgen/integrations/__init__.py

@@ -0,0 +1 @@
+"""Outbound integrations with external test-management platforms."""

apitestgen/recorder/addon.py

@@ -0,0 +1,244 @@
+"""mitmproxy addon that records API/browser traffic into SQLite."""
+
+from __future__ import annotations
+
+import logging
+import time
+from urllib.parse import urlparse
+
+from mitmproxy import ctx, http
+from mitmproxy.addonmanager import Loader
+
+from apitestgen.common.host_classifier import infer_primary_base_url
+from apitestgen.recorder._normalize import (
+    TEST_ID_HEADER,
+    extract_response_headers,
+    filter_request_headers,
+    flatten_query_params,
+    host_with_port,
+    normalize_allowed_hosts,
+    parse_request_body,
+    parse_response_body,
+    should_record,
+)
+from apitestgen.recorder.db import create_session, init_db, insert_api_call, update_session_base_url
+
+logger = logging.getLogger("apitestgen.recorder")
+
+
+class RecorderAddon:
+    """Record filtered browser/API flows into SQLite."""
+
+    def __init__(self):
+        self.db_path: str = ".apitestgen/recordings.db"
+        self.session_name: str = "default"
+        self.filter_prefixes: list[str] = []
+        self.allowed_hosts: list[str] = []
+        self.role: str = ""
+        self.include_browser_noise: bool = False
+        self.conn = None
+        self.session_id: int | None = None
+        self.seq_counter: int = 0
+        self._flow_start_times: dict[str, float] = {}
+        self._recorded_calls: list[dict] = []
+        self._seen_host_keys: set[tuple[str, str]] = set()
+        self._current_base_url: str = ""
+
+    def load(self, loader: Loader):
+        loader.add_option(
+            "apitestgen_db",
+            str,
+            ".apitestgen/recordings.db",
+            "SQLite database path",
+        )
+        loader.add_option(
+            "apitestgen_session",
+            str,
+            "default",
+            "Recording session name",
+        )
+        loader.add_option(
+            "apitestgen_filter",
+            str,
+            "",
+            "Comma-separated URL path prefixes to record",
+        )
+        loader.add_option(
+            "apitestgen_domains",
+            str,
+            "",
+            "Comma-separated exact hostnames to record",
+        )
+        loader.add_option(
+            "apitestgen_role",
+            str,
+            "",
+            "Role label for this session — every flow gets tagged with it. For multi-role flows, run one mitmdump per role on different ports.",
+        )
+        loader.add_option(
+            "apitestgen_include_browser_noise",
+            bool,
+            False,
+            "Record browser-internal chatter (Safe Browsing, OCSP, DoH, telemetry, etc.). Off by default.",
+        )
+
+    def configure(self, updated):
+        self.db_path = ctx.options.apitestgen_db
+        self.session_name = ctx.options.apitestgen_session
+        self.filter_prefixes = [
+            prefix.strip() for prefix in ctx.options.apitestgen_filter.split(",") if prefix.strip()
+        ]
+        self.allowed_hosts = normalize_allowed_hosts(ctx.options.apitestgen_domains)
+        self.role = (ctx.options.apitestgen_role or "").strip()
+        self.include_browser_noise = bool(ctx.options.apitestgen_include_browser_noise)
+
+        if self.conn is None:
+            self.conn = init_db(self.db_path)
+            self.session_id = create_session(
+                self.conn, self.session_name, role=self.role or None
+            )
+            logger.info(
+                "Recording session #%d (%s) -> %s (role=%s)",
+                self.session_id,
+                self.session_name,
+                self.db_path,
+                self.role or "-",
+            )
+
+    def request(self, flow: http.HTTPFlow):
+        self._flow_start_times[flow.id] = time.time()
+
+    def response(self, flow: http.HTTPFlow):
+        if not self._should_record(flow):
+            self._flow_start_times.pop(flow.id, None)
+            return
+
+        start_time = self._flow_start_times.pop(flow.id, None)
+        duration_ms = int((time.time() - start_time) * 1000) if start_time else 0
+
+        self.seq_counter += 1
+        req = flow.request
+        resp = flow.response
+        if resp is None:
+            return
+
+        query_params = flatten_query_params(urlparse(req.url).query)
+
+        test_id: str | None = None
+        raw_request_headers: dict[str, str] = {}
+        for key, value in req.headers.items():
+            if key.lower() == TEST_ID_HEADER.lower():
+                if not test_id:
+                    test_id = value
+                continue
+            raw_request_headers[key] = value
+        request_headers = filter_request_headers(raw_request_headers)
+        # mitmproxy can multi-value headers; expand via get_all so the shared
+        # extract_response_headers sees every occurrence.
+        response_header_pairs = [
+            (name, value)
+            for name in resp.headers.keys()
+            for value in resp.headers.get_all(name)
+        ]
+        response_headers = extract_response_headers(response_header_pairs)
+
+        request_content_type = req.headers.get("content-type", "")
+        request_body, request_body_text = parse_request_body(
+            self._safe_get_text(req),
+            request_content_type,
+        )
+        response_body, response_body_text = parse_response_body(
+            self._safe_get_text(resp),
+            resp.headers.get("content-type", ""),
+        )
+
+        scheme = req.scheme
+        host_str = host_with_port(req.host, req.port)
+
+        actor = self.role or None
+
+        call_snapshot = {
+            "seq": self.seq_counter,
+            "scheme": scheme,
+            "host": host_str,
+            "path": req.path.split("?")[0],
+            "method": req.method,
+            "status_code": resp.status_code,
+            "content_type": resp.headers.get("content-type", ""),
+            "request_content_type": request_content_type,
+            "request_headers": request_headers,
+            "actor": actor,
+        }
+
+        try:
+            call_id = insert_api_call(
+                self.conn,
+                self.session_id,
+                self.seq_counter,
+                method=req.method,
+                scheme=scheme,
+                host=host_str,
+                path=req.path.split("?")[0],
+                query_params=query_params if query_params else None,
+                request_content_type=request_content_type,
+                request_headers=request_headers if request_headers else None,
+                request_body=request_body,
+                request_body_text=request_body_text,
+                status_code=resp.status_code,
+                response_body=response_body,
+                response_body_text=response_body_text,
+                response_headers=response_headers if response_headers else None,
+                content_type=resp.headers.get("content-type", ""),
+                duration_ms=duration_ms,
+                test_id=test_id,
+                actor=actor,
+            )
+
+            self._recorded_calls.append(call_snapshot)
+            host_key = (scheme, host_str)
+            if host_key not in self._seen_host_keys:
+                self._seen_host_keys.add(host_key)
+                inferred_base_url = infer_primary_base_url(self._recorded_calls)
+                if inferred_base_url and inferred_base_url != self._current_base_url:
+                    self._current_base_url = inferred_base_url
+                    update_session_base_url(self.conn, self.session_id, inferred_base_url)
+                    logger.info("Updated inferred base_url: %s", inferred_base_url)
+
+            logger.info(
+                "[#%d] %s %s -> %d (%dms)%s",
+                call_id,
+                req.method,
+                req.path.split("?")[0],
+                resp.status_code,
+                duration_ms,
+                f" actor={actor}" if actor else "",
+            )
+        except Exception:
+            logger.exception("Failed to record API call")
+
+    def _should_record(self, flow: http.HTTPFlow) -> bool:
+        if flow.response is None:
+            return False
+        path = flow.request.path.split("?")[0]
+        return should_record(
+            flow.request.host,
+            path,
+            self.filter_prefixes,
+            self.include_browser_noise,
+            self.allowed_hosts,
+        )
+
+    @staticmethod
+    def _safe_get_text(message) -> str | None:
+        try:
+            return message.get_text(strict=False)
+        except TypeError:
+            try:
+                return message.get_text()
+            except Exception:
+                return None
+        except Exception:
+            return None
+
+
+addons = [RecorderAddon()]

apitestgen/templates/apitestgen.yaml

@@ -0,0 +1,101 @@
+# ApiTestGen v2 配置
+# 后端 Java Web 仓库本地绝对路径
+# - 仅 /apitestgen-backend-enrich(及底层 `apitestgen analyze enrich`)需要它
+# - 录制 → 分析 → 生成 主流程不依赖此字段;留默认占位也能跑
+# - 配置后会:扫 controller 注解填 controller_file/permission/path_params,
+#   读 DTO 类拿精确的 @NotNull/@Size/@Pattern,识别 R<T>/CommonResult<T> 包装类,
+#   倒排 service 层 throw 链路给 negative case 提供具体错误码
+backend:
+  repo_path: /absolute/path/to/your/spring-backend
+  # 可选:限定扫描子目录,加速 Grep。逗号分隔多个根。
+  module_roots:
+    - src/main/java
+
+# 测试输出目录(相对当前项目)
+output_dir: api_tests
+
+# 测试策略：控制每个接口生成的用例数量
+# 同时也会影响 `.apitestgen/plans/test_strategy.json` 中的默认测试深度描述
+# - minimal:  1 正向 + 1 必填缺失 + 1 安全（无 token），共 3 条；仅用于冒烟
+# - balanced: 每字段最多 1 条负向 + 1 边界，去重（默认，适合日常回归）
+# - full:     所有组合，包括全部边界/枚举负向用例
+test_strategy: balanced
+
+# 说明：
+# - `record-analyze` / `json_converter` 会自动生成 `.apitestgen/*.json`
+# - 同时自动刷新 `.apitestgen/plans/requirement_matrix.json`
+#   `.apitestgen/plans/test_strategy.json`
+#   `.apitestgen/plans/quality_review.json`
+# - 这些 sidecar 不参与运行时请求发送，但会被后续人工审查和校验脚本使用
+
+# 代理录制配置(可选,使用 /apitestgen-record 时生效)
+proxy:
+  port: 8888
+  filter_paths:
+    - "/admin-api/"
+  # 排除的路径模式
+  # exclude_patterns:
+  #   - "/ws/"
+
+  # 依赖检测算法配置（P2-2）
+  dependency_detector:
+    # 高频值过滤阈值：值出现在超过此比例的响应中则视为噪音（0~1）
+    high_freq_threshold: 0.5
+    # 最低置信度阈值：低于此值的关联不写入数据库
+    min_confidence: 0.5
+    # 时间窗（秒）：依赖必须在目标请求之前 N 秒内出现；0 = 不限制
+    time_window_seconds: 0
+
+# 测试用例文案语言：zh-CN（默认）或 en
+# 影响 `_generate_analysis_test_cases` 的 testpoint / expectation / precondition 字面值
+locale: zh-CN
+
+# CloudTest 平台对接配置（供 tools/analyzer/output_formatter.py --format cloudtest
+# 及 tools/integrations/cloudtest_pusher.py 读取）
+# cloudtest:
+#   # 创建用例接口的 featureUri 默认值；后续也可按项目自定义成真实特性目录 URI
+#   default_feature_uri: REPLACE_WITH_FEATURE_URI
+#   # 可选：CloudTest/SVN 中脚本路径的仓库前缀；不配时使用 api_tests/... 相对路径
+#   # svn_script_path_prefix: /svn/your-project
+#   # CSV 列顺序（可选，默认按下方 headers 字面量输出）
+#   # columns:
+#   #   - expectOutput
+#   #   - featureUri
+#   #   - interfaceName
+#   #   - name
+#   #   - number
+#   #   - preparation
+#   #   - svnScriptPath
+#   #   - testStep
+#
+#   # REST 推送契约（dry-run 时可留空；--apply 前必须填完）
+#   api:
+#     base_url: https://cloudtest.example.com
+#     # 认证：CloudTest 走 Cookie + csrftoken（Django Session 风格）
+#     # 浏览器登录 CloudTest 后从 DevTools 复制；rotating，过期后需手动刷新。
+#     headers:
+#       Cookie: "sessionid=...; csrftoken=..."
+#       csrftoken: REPLACE_WITH_CSRF_TOKEN_VALUE
+#       X-Project-Id: your-project-id   # 如平台需要再加
+#     external_id_column: number          # CSV 列名，默认就是 number
+#     search_query_field: number          # 查询时用的 query 参数名
+#     case_search_path: /api/testcases    # GET 此地址 + ?search_query_field=xxx
+#     case_create_path: /api/testcases
+#     case_create_method: POST
+#     case_update_path: /api/testcases/{id}
+#     case_update_method: PUT
+#     # 默认 CSV 列已对齐创建用例接口参数；只有自定义 columns 时才需要 field_map
+#     # field_map 的 value 语义：
+#     #   - 若是 CSV 列名 → 取该行该列的值
+#     #   - 若不是任何列名 → 作为字面值原样写进 body（保留 YAML 类型：int / bool / null …）
+#     # 用后者来传 CSV 里没有的固定参数，例如 stage / type 之类的枚举值。
+#     field_map:
+#       expectOutput: expectOutput
+#       featureUri: featureUri
+#       interfaceName: interfaceName
+#       name: name
+#       number: number
+#       preparation: preparation
+#       svnScriptPath: svnScriptPath
+#       testStep: testStep
+#       stage: 2                  # 字面值示例：body 里发 "stage": 2（数字，不是 "2"）