ai-ui-testing

AI 驱动的 Web UI 自动化测试框架 —— 基于 Playwright + pytest 封装，用 AI 解决传统 UI 自动化两大痛点：定位器维护 和 失败分析。

特色

• 开箱即用：ai-ui init 生成骨架 → ai-ui run 跑用例 → 自动出 Allure 报告
• AI 定位器：自然语言描述元素（"登录按钮"），AI 生成并在真实页面校验的定位器
• 定位器自动修复：元素找不到时 AI 分析页面快照自动修复，写入学习缓存，前端改版不再抓狂
• AI 失败分析：失败自动采集截图 + DOM 快照 + traceback，AI 给出根因与修复建议
• 自然语言用例生成：YAML 描述用例意图 → AI 生成可直接运行的 pytest 代码
• Mock 降级模式：无 API Key 也能完整跑通、演示、写用例
• 登录态复用：登录一次保存 cookies/localStorage，用例间复用，绕开 SSO/扫码/验证码
• POM + 稳定性内置：页面对象模型、失败重试、trace 录制、失败产物归档
• CI 友好：GitHub Actions 开箱即用

架构

┌─ CLI（ai-ui init/run/gen/analyze）
├─ pytest 插件（失败截图 / 重试 / AI 分析 / Allure 附加）
├─ 核心：Driver · BasePage · Element · Config
├─ AI：client（openai/ollama/mock）· snapshot · locator · repair · failure_analysis · test_gen
└─ 底座：Playwright（chromium/firefox/webkit） + LLM

快速开始

python -m venv .venv
# Windows: .venv\Scripts\activate   |   macOS/Linux: source .venv/bin/activate
pip install -e ".[allure]"
playwright install chromium
ai-ui run --provider mock        # 5 个示例用例全部通过，无需 API Key

Windows 可一键运行 scripts/run_tests.ps1，macOS/Linux 运行 scripts/run_tests.sh。

文档（docs/）

CLI 速查

inspect / act / login 输出 JSON，供外部 AI 工具（如 DeepSeek harness）编排， 完成「探查页面 → 登录 → 保存登录态 → 按模块生成用例」的对话式开发（docs/12）。

目录结构

ai-ui-testing/
├── config/config.yaml          # 全局配置（字段带注释）
├── docs/                       # 使用手册（上表 6 篇）
├── src/ai_ui_testing/          # 框架源码
│   ├── driver / base_page / element / config
│   ├── ai/                     # client / snapshot / locator / repair / analysis / test_gen
│   ├── pytest_plugin.py        # fixtures + 失败处理钩子
│   ├── cli.py                  # ai-ui 命令
│   └── templates/              # ai-ui init 骨架
├── tests/                      # 开箱示例（demo 页面 + POM + 用例）
├── samples/nl_tests/           # 自然语言用例规格示例
├── scripts/                    # 一键安装运行脚本
└── .github/workflows/ci.yml    # GitHub Actions

开发与质量保障

pip install -e ".[dev]"          # 开发工具（ruff 等）
ruff check src tests/unit        # 静态检查（未用代码/import 排序等）
python -m pytest tests/unit      # 单元测试（纯逻辑，无需浏览器，34 个）
ai-ui run --provider mock        # 全量回归（真实浏览器）

Roadmap

• 并行执行（pytest-xdist）与 Allure 历史趋势
• 连接外部浏览器实例复用登录态（CDP 协议 / ego-lite 等）：用例直接跑在已登录会话上，绕开 SSO、扫码登录、验证码等登录前置成本（适合本地/冒烟；CI 仍需自行处理登录）
• 截图对比（视觉回归）+ AI 差异分析
• 页面对象类 AI 一键生成（输入 URL → 生成 POM）
• 定位器学习缓存的版本管理（按 URL/提交关联）
• 关键字驱动（YAML 用例直接执行，不写代码）