Auto VTable — Hoolinks UI/API 自动化测试平台

一套面向 SCM 系统的 UI / 接口自动化基建。技术栈：

• Python 3.14 · uv 包管理
• DrissionPage（UI）· httpx（API）· ddddocr（验证码）
• pydantic v2 · pydantic-settings v2（配置）
• pytest 8 · ruff（lint+format）· ty（类型检查）· pre-commit

目录结构

src/auto_vtable/
├── config.py          # pydantic-settings v2，读取 .env
├── exceptions.py      # 类型化异常
├── logging.py         # loguru 统一配置
├── core/              # VTable 助手 + 抽离的 JS 模板
├── auth/              # SCM 登录（OCR + cookie）
├── browser/           # Chromium / tab / iframe 工厂
├── api/               # httpx 客户端骨架
└── pages/             # Page Object（如 SalesReportPage）
tests/
├── unit/              # 不依赖浏览器
└── ui/                # @pytest.mark.ui，依赖浏览器
examples/
└── demo_vtable.py     # 等价于原 vtable_tester.main()

一次性初始化

# 1. 同步依赖（含 dev）
uv sync --extra dev

# 2. 拷贝配置模板并填写真实值
Copy-Item .env.example .env

# 3. 安装 pre-commit hooks（可选）
uv run pre-commit install

如果安装 ty 报错，临时降级到 mypy 即可：从 pyproject.toml 的 [project.optional-dependencies].dev 中移除 "ty>=..."。ty 目前是 Astral 的 alpha 版，命令行接口仍在迭代。

常用命令

操作	命令
安装依赖	uv sync --extra dev
跑全部单元测试	uv run pytest tests/unit
跑 UI 测试	uv run pytest tests/ui -m ui
跑 demo	uv run python examples/demo_vtable.py
Lint	uv run ruff check .
Format	uv run ruff format .
类型检查	uv run ty check
pre-commit 全量	uv run pre-commit run --all-files

配置项（.env）

变量	说明
HL_BASE_URL	SCM 系统根地址
HL_USERNAME / HL_PASSWORD	登录账号 / 密码
HL_CHROMIUM_INI	DrissionPage 的 ChromiumOptions ini 路径
HL_LOG_LEVEL	日志级别（默认 INFO，可选 TRACE/DEBUG/INFO/SUCCESS/WARNING/ERROR/CRITICAL）
HL_LOG_DIR	滚动日志文件目录（默认 ./logs，自动创建）

关键设计

1. 职责分层：core/ 只放技术能力，pages/ 放业务语义，auth/ 与 browser/ 各管各的副作用。任何 page 都不应直接 import httpx。
2. Page Object + 组合：SalesReportPage 持有 FastVTableHelper，链式 调用 open().search_by_date(...) 表达业务流程。
3. JS 抽离：src/auto_vtable/core/js/*.js 作为资源文件加载，IDE 高 亮 / 格式化都能用上。新增 JS 时仅需 _load("xxx.js")。
4. 类型化异常：VTableBindError / VTableEditError / LoginError / BrowserError 分别对应不同失败模式，pytest 可精确断言。
5. 配置外置：账号、URL、ini 路径全部走 .env，源码零硬编码。
6. 统一日志：auto_vtable.logging.configure_logging() 单入口管三个 sink——彩色终端（紧凑单行 + 级别图标 + 模块路径缩短）、滚动全量文件 （10MB/7d/zip）、ERROR 专用文件；自动过滤 httpx / DrissionPage 等第三方 INFO 噪音；diagnose=False 防止账号密码泄漏到日志栈。

后续路线图

• 接口测试用例：在 tests/api/ 下扩展 ApiClient 用法。
• CI：补 GitHub Actions / GitLab CI 配置（先确认平台）。
• Allure / 失败截图自动归档（待量级到了再上）。
• 评估迁移到 Playwright（DrissionPage 仍是当前主力）。

旧脚本

历史探索脚本（vtable_tester.py、set_LoginAuth.py、fast_vtable_helper.py、 testVtable.py、test_ui*.py 以及对应的 markdown / json / png / xlsx）已统一搬到 本地 legacy/ 目录。该目录已加入 .gitignore，不会被提交到远端，也不参与 lint / 类型检查 / 测试，仅作本地参考。新代码请统一写在 src/auto_vtable/ 下； 如果 legacy/ 里某段逻辑仍有价值，请移植到对应的子包再用。