# 测试 Agent 说明 ## 测试布局 当前入库的自动化测试集中在 `backend/tests/`。以下命令从仓库根进入 `backend/` 后运行；其余文档中的命令也应按注明的工作目录执行： ```bash cd backend uv run pytest -q uv run pytest -q tests/ ``` 按用途分两类（目录内不按类再分层级）： - 后端单元回归：纯函数、连接池、数据格式、embedding、驱动兼容、分布式锁。 - 仓库守卫：SQL 转义、权限过滤、Host 校验、嵌入认证等安全修复；关键前端组件之间的错误传递和结构契约；supplier/model 配置一致性；i18n 键。这类测试常直接读取源码文本或用 AST 提取局部实现，路径从 `backend/tests/` 推到仓库根。 前端没有独立单测框架；`npm run build` 中的 `vue-tsc` 是类型验证，结构性契约由上述守卫测试保护。xpack 在独立仓库内先做 compileall 和静态 SDK 构建；完整集成在 SQLBot 后端环境中执行。 不要为了速度跳过与改动相关的层，也不要把所有历史失败当成当前变更造成的问题；先用目标测试定位边界。 ## 环境与证据 - 记录测试提交、命令、工作目录和必要的依赖版本/配置；不记录凭据。独立 worktree 复用环境时确认模块实际从当前 worktree 导入，避免测试到旧代码。 - `uv run` 可能解析、同步依赖；需要保留已准备环境或 editable 安装时使用 `uv run --no-sync`，并说明依赖来源。没有入库 lockfile 时，不能仅凭代码 SHA 宣称依赖可完全复现。 - 分别报告源码/静态检查、单元或守卫测试、真实接口/数据库、浏览器、镜像部署的覆盖；没有执行的层不能标为通过。AST/源码文本测试不能替代真实导入、路由和授权调用链验证。 - Bug 修复应有修复前失败、修复后通过的用例，或等价的前后行为证据，并覆盖相关边界。权限验证同时检查拒绝路径、合法操作对照、响应内容及持久化结果。 - 未登录、请求格式错误、服务未启动、依赖不可用等不满足复现前提的结果标为无效验证；不能把 401/422 或连接失败当作修复成功。有效前提下预期的认证拒绝仍可作为对应认证测试证据。 - 测试失败先区分环境问题、既有问题和本次回归。声称既有失败时，在相同配置的未修改基线上对照，或给出可核验的历史证据；无法确认时保留不确定性，不跳过失败后宣称全部通过。 ## 集成与产品验收 - 默认单元/守卫测试离线、可重复；真实数据库、LLM、网络和浏览器测试单独显式运行。新增集成用例应使用独立目录或明确的选择机制，默认收集不能因配置了凭据就意外访问外部服务；暂不规定仓库尚未实现的 marker 或运行器。 - 在授权的测试环境中使用独立数据库、schema、账号或有明确标识的测试记录；不覆盖业务数据。外部环境与凭据用途必须与任务一致，只传输必要数据，LLM 回归优先使用合成数据。 - UI 验收检查真实产品 DOM、交互与保存后状态；静态演示页或截图不能代替完整操作链。LLM 功能同时检查选表/上下文、生成 SQL、执行结果；预置结果不能证明模型行为。 - 记录本次启动的进程、端口和测试资源；结束时仅停止、清理本次拥有的临时资源。需要保留复现环境时说明入口和生命周期，不留下共享凭据或无主服务，不删除共享数据卷。 ## 新增测试约定 - 测试可隔离的纯逻辑或服务函数； - 用 `Mock`、`SimpleNamespace`、SQLite 或 AST 加载方式隔离外部数据库和驱动； - 默认单元/守卫测试不访问真实 LLM、外部数据库或互联网；需要这些依赖时遵循上面的集成验收约定； - 命名和断言风格跟随相邻测试。 `LOG_FORMAT` 只是 `logging.Formatter` 的百分号格式串模板，代码中没有 JSON 日志实现；若本机环境把它设成了非默认格式串导致 formatter 初始化失败，先检查进程环境与 dotenv 来源；`unset LOG_FORMAT` 后 dotenv 仍可能重新加载该值。可在单次测试命令中使用 `LOG_FORMAT='%(levelname)s %(message)s'`，不要为测试覆盖共享配置。 ## 守卫维护 修改守卫前先说明原断言保护的行为、新需求的依据以及替代覆盖。提交历史只能证明行为曾被改动，不能单独证明新行为正确。确认旧契约不再适用后，更新守卫以表达新契约；不要仅为消除失败删除断言、扩大白名单或降低安全约束。删除集成测试时说明失去的覆盖及保留/替代方式，不把缺少凭据时跳过描述为永久不可用。 ## 前端验证 ```bash cd frontend npm run build ``` - 类型、模板和打包验证由 `vue-tsc -b` 与 Vite 完成。 - 修改少量文件时可用 `npx eslint --fix`。 - 不要默认运行全量自动修复脚本。 - 当前不要自行引入 Vitest/Jest/Playwright 等新测试框架；若需要，先提出框架、运行成本和 CI 影响。 ## 图表渲染服务 修改 `g2-ssr/` 或后端图表配置时，验证命令与前后端字段契约见 `g2-ssr/AGENTS.md`。 ## Ruff 和类型检查 后端 Ruff 只针对改动文件运行，避免全仓库历史问题产生无关 diff： ```bash cd backend uv run ruff check uv run ruff format --check ``` `pyproject.toml` 配置了 mypy strict，但历史代码尚未建立全仓库通过基线。新代码应避免引入新的类型问题；是否运行 mypy 由改动范围和相邻模块现状决定，不要自动对全仓库执行大规模修复。 ## 测试选择标准 必须至少运行相关测试的情况： - 修复 bug：覆盖原始失败输入和边界输入； - 安全逻辑：覆盖攻击样本、拒绝路径和合法路径； - 数据格式/连接池/embedding：运行对应既有测试； - API 或前端结构契约：运行相关守卫测试； - i18n：确认五种语言键结构； - xpack 联调：使用 editable 安装并运行 SQLBot 后端测试。 完成标准： - 相关测试通过，或明确记录与本次改动无关的既有失败； - 新行为有回归测试或说明为什么不适用； - 没有为了通过测试削弱安全约束； - 默认测试不隐式访问外部服务；集成验证的环境、选择方式和限制已说明，提交中不含密钥； - 本次暂存和提交的 diff 只包含任务相关变更；用户原有无关改动保留原样。