summary-tool 1.1.0

Compare testdetails tables from HTML reports and generate diff/summary HTML reports.

XTS Summary Tool

简介

summary_tool 是一个用于提取、比较文本或 HTML 内容并生成差异报告的 Python 包。它可以帮助对比两套文档（如稿件、翻译稿等），并生成可视化的 HTML 报告以及汇总页面。

---

环境要求

• Python 3.11 或以上
• 运行环境：Linux (已在 Docker 镜像中测试)

---

安装步骤

1. 克隆或下载代码库（已在本目录下）。
2. 安装依赖：

   pip install -r requirements.txt
   

3. （可选）如果希望以命令行入口使用，推荐以可编辑方式安装：

   pip install -e .
   

   这会在 PATH 中添加 summary-tool 命令。

---

使用示例

以AATS实际目录，ex：

交互模式:

summary-tool -i http://12.22.193.246/AATS_XTS_REPORTS/_ANR16/DB28
在远程路径下发现以下子目录:
  1. /AATS_XTS_REPORTS/_ANR16
  2. 20251203_140
  3. 20251209_146
  4. 20251218_153
  5. 20251230_162
  6. 20260102_171
  7. 20260106_177
请选择目录编号:
  - 输入单个编号 → 生成该目录里XTS的汇总报告
  - 输入两个编号,用逗号分隔 → 生成两目录里XTS的对比报告
编号: 5,6
INFO: No testdetails for subdir 'gts', generating summary-only diff.
INFO: No testdetails for subdir 'sts', generating summary-only diff.
INFO: Merged diff report written to xts-diff_summary.html

summary-tool -i http://12.22.193.246/AATS_XTS_REPORTS/_ANR16/DB28
在远程路径下发现以下子目录:
  1. /AATS_XTS_REPORTS/_ANR16
  2. 20251203_140
  3. 20251209_146
  4. 20251218_153
  5. 20251230_162
  6. 20260102_171
  7. 20260106_177
请选择目录编号:
  - 输入单个编号 → 生成该目录里XTS的汇总报告
  - 输入两个编号,用逗号分隔 → 生成两目录里XTS的对比报告
编号: 6
INFO: Merged diff report written to xts_summary.html

单参数： summary-tool http://12.22.193.246/AATS_XTS_REPORTS/_ANR16/DB2881/20260102_171/

• 会把171版本下面所有的报告汇总到xts_summary.html，单列显示

双参数： summary-tool summary-tool http://12.22.193.246/AATS_XTS_REPORTS/287P_ANR14/DB23/20251130_667/ http://10.22.193.246/AATS_XTS_REPORTS/287P_ANR14/DB23/20251205_672/

• 会把667、672下面所有报告汇总，然后比对生成xts-diff_summary.html，双列显示

---

交互式模式（-i / --interactive）

summary-tool -i <根URL>

• 脚本会列出根 URL 下的子目录列表。
• 输入 单个 编号 → 生成该子目录的 单列 汇总报告（xts_summary.html）。
• 输入 两个 编号（用逗号分隔） → 对这两个子目录生成 对比 报告（xts-diff_summary.html），并递归搜索子目录中的所有 test_result_failures_suite.html 文件。
• 交互完成后，工具会自动进入原有的单列或双列流程，无需额外参数。

---

单列模式（单参数）

单列模式仅提供左侧路径（目录或 HTML 文件），工具会递归搜索 test_result_failures_suite.html（或首个 HTML）并生成单独的汇总报告。

# 左侧为本地目录，自动递归搜索子目录
python -m summary_tool.cli /path/to/left_root -s cts,gts -o xts_summary.html

# 左侧为远程 URL（目录）
python -m summary_tool.cli https://example.com/reports -r -o remote_summary.html

• -s：不指定之目录，就会递归搜索所有的子目录下的test_result_failures_suite.html。
• -r/--recursive：在单列模式下强制递归搜索（可选，默认若左路径是目录且包含目标文件也会递归）。
• 输出默认 xts_summary.html（未指定 -o 时）。

---

双列模式（双参数）

双列模式同时提供左、右路径，用于两套报告的对比，生成差异报告。

# 本地目录对比
python -m summary_tool.cli /path/to/left_root /path/to/right_root -s cts,gts -o xts-diff_summary.html

# 本地文件对比（单个子目录）
python -m summary_tool.cli /path/to/left.html /path/to/right.html -o diff.html

# 远程 URL 对比
python -m summary_tool.cli https://example.com/left https://example.com/right -s sts -o remote_diff.html

• -s：不指定之目录，就会递归搜索所有的子目录下的test_result_failures_suite.html。
• 输出默认 xts-diff_summary.html（未指定 -o 时）。
• 若只提供左侧路径，则进入单列模式，上述示例可省略右侧参数。

---

使用已安装的 CLI 命令（若已执行 pip install -e .）

summary-tool -a path/to/first -b path/to/second -o reports

运行后会在指定的输出目录生成以下文件， 默认缓存文件输出目录tmp_diff_reports：

• *_1.html、*_2.html：原始文本的 HTML 展示
• *-diff.html：对比后的差异报告 项目根目录：
• xts_summary.html、xts-diff_summary.html：整体汇总页面

---

常见错误及解决办法

错误信息	可能原因	解决方案
ModuleNotFoundError: No module named 'xxx'	依赖未安装或虚拟环境不匹配	确认已在当前环境执行 pip install -r requirements.txt，或使用 python -m venv venv && source venv/bin/activate 再安装。
FileNotFoundError: [Errno 2] No such file or directory	提供的路径不存在或拼写错误	检查 --source-a、--source-b 参数，确保路径正确且文件可读。
UnicodeDecodeError	输入文件编码不是 UTF-8	在 extractor.py 中添加 encoding='utf-8'，或先将文件转换为 UTF-8 编码。
git status 报 “detected dubious ownership”	在容器中挂载的目录所有权不被 Git 认可	执行 git config --global --add safe.directory <repo_path>（已在项目根目录做过此设置）。
空的 diff 报告	两个输入的内容完全相同或提取阶段出错	打印 extractor 的日志（utils.py 中的 logger），确认文本已被正确读取。

---

开发 & 贡献

Continue CLI