SQLBot/docs/agents/testing.md

测试 Agent 说明

测试布局

当前入库的自动化测试集中在 backend/tests/。以下命令从仓库根进入 backend/ 后运行；其余文档中的命令也应按注明的工作目录执行：

cd backend
uv run pytest -q
uv run pytest -q tests/<relevant-test.py>

按用途分两类（目录内不按类再分层级）：

• 后端单元回归：纯函数、连接池、数据格式、embedding、驱动兼容、分布式锁。
• 仓库守卫：SQL 转义、权限过滤、Host 校验、嵌入认证等安全修复；关键前端组件之间的错误传递和结构契约；supplier/model 配置一致性；i18n 键。这类测试常直接读取源码文本或用 AST 提取局部实现，路径从 backend/tests/ 推到仓库根。

前端没有独立单测框架；npm run build 中的 vue-tsc 是类型验证，结构性契约由上述守卫测试保护。xpack 在独立仓库内先做 compileall 和静态 SDK 构建；完整集成在 SQLBot 后端环境中执行。

不要为了速度跳过与改动相关的层，也不要把所有历史失败当成当前变更造成的问题；先用目标测试定位边界。

环境与证据

Codex 开发用 MCP 的离线回归位于 backend/tests/test_codex_mcp_runtime.py。 从仓库根运行 python3 -B backend/tests/test_codex_mcp_runtime.py，只需 Python 标准库， 使用临时配置和模拟进程启动，不连接 TAPD、浏览器或数据库；也可用上述 pytest 命令执行该文件。

• 记录测试提交、命令、工作目录和必要的依赖版本/配置；不记录凭据。独立 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'，不要为测试覆盖共享配置。

守卫维护

修改守卫前先说明原断言保护的行为、新需求的依据以及替代覆盖。提交历史只能证明行为曾被改动，不能单独证明新行为正确。确认旧契约不再适用后，更新守卫以表达新契约；不要仅为消除失败删除断言、扩大白名单或降低安全约束。删除集成测试时说明失去的覆盖及保留/替代方式，不把缺少凭据时跳过描述为永久不可用。

前端验证

cd frontend
npm run build

• 类型、模板和打包验证由 vue-tsc -b 与 Vite 完成。
• 修改少量文件时可用 npx eslint <changed-file...> --fix。
• 不要默认运行全量自动修复脚本。
• 当前不要自行引入 Vitest/Jest/Playwright 等新测试框架；若需要，先提出框架、运行成本和 CI 影响。

图表渲染服务

修改 g2-ssr/ 或后端图表配置时，验证命令与前后端字段契约见 g2-ssr/AGENTS.md。

Ruff 和类型检查

后端 Ruff 只针对改动文件运行，避免全仓库历史问题产生无关 diff：

cd backend
uv run ruff check <changed-file.py...>
uv run ruff format --check <changed-file.py...>

pyproject.toml 配置了 mypy strict，但历史代码尚未建立全仓库通过基线。新代码应避免引入新的类型问题；是否运行 mypy 由改动范围和相邻模块现状决定，不要自动对全仓库执行大规模修复。

测试选择标准

必须至少运行相关测试的情况：

• 修复 bug：覆盖原始失败输入和边界输入；
• 安全逻辑：覆盖攻击样本、拒绝路径和合法路径；
• 数据格式/连接池/embedding：运行对应既有测试；
• API 或前端结构契约：运行相关守卫测试；
• i18n：确认五种语言键结构；
• xpack 联调：使用 editable 安装并运行 SQLBot 后端测试。

完成标准：

• 相关测试通过，或明确记录与本次改动无关的既有失败；
• 新行为有回归测试或说明为什么不适用；
• 没有为了通过测试削弱安全约束；
• 默认测试不隐式访问外部服务；集成验证的环境、选择方式和限制已说明，提交中不含密钥；
• 本次暂存和提交的 diff 只包含任务相关变更；用户原有无关改动保留原样。