feat: 实现AI驱动的Web自动化测试框架

主要功能: - 纯视觉元素定位 + DOM辅助的混合方案 - 解决 mouse.click() 与 Vue 页面交互问题 - 使用 elementFromPoint + JS click/focus 实现可靠点击 - 智能元素定位: 根据描述生成CSS选择器获取精确坐标 - 区域扫描作为后备定位方案 - 完整的测试报告生成 (HTML+JSON) - 截图记录每个操作步骤技术改进: - controller.py: 改进 click_at 使用 JavaScript 交互 - executor.py: 添加 _find_element_by_description 智能定位 - planner.py: 增强 prompt 传入视口尺寸 - main.py: 获取实际视口大小传给 planner
2025-12-28 15:34:22 +08:00
commit a67ad26a52
24 changed files with 2137 additions and 0 deletions
--- a/README.md
+++ b/README.md
@@ -0,0 +1,153 @@
+# AI Web Tester
+
+基于 AI 视觉模型的智能 Web 自动化测试框架。使用自然语言描述测试目标，AI 会自动分析页面并执行操作。
+
+## ✨ 特性
+
+- 🤖 **AI 驱动** - 使用 Claude/GPT-4V 视觉模型理解页面内容
+- 📝 **自然语言** - 用自然语言描述测试目标，无需编写选择器
+- 📊 **自动报告** - 生成嵌入截图的 HTML 报告 + JSON 结果
+- 🔧 **可配置** - 支持多种 AI 模型和 API 代理
+- 🔄 **自动重试** - 指数退避重试机制
+- 👁️ **视觉回归** - 基线对比检测 UI 变化
+- ⚡ **并行执行** - 多线程运行测试用例
+- 🚀 **CI/CD** - GitHub Actions 集成
+
+## 🚀 快速开始
+
+### 1. 安装依赖
+
+```bash
+pip install -r requirements.txt
+playwright install chromium
+```
+
+### 2. 配置环境变量
+
+```bash
+cp .env.example .env
+```
+
+编辑 `.env` 文件：
+
+```bash
+ANTHROPIC_API_KEY=your_api_key_here
+ANTHROPIC_BASE_URL=https://api.anthropic.com  # 可选，用于代理
+ANTHROPIC_MODEL=claude-sonnet-4-20250514      # 可选
+API_TIMEOUT=60                                 # API 超时（秒）
+API_MAX_RETRIES=3                              # 最大重试次数
+LOG_LEVEL=INFO                                 # 日志级别
+```
+
+> ⚠️ **注意**：`BASE_URL` 不要包含 `/v1` 后缀，SDK 会自动添加。
+
+### 3. 运行测试
+
+```bash
+python example.py
+```
+
+## 📖 使用方法
+
+### 基础用法
+
+```python
+from src import WebTester
+
+with WebTester(model="claude") as tester:
+    tester.goto("https://example.com")
+    result = tester.test("点击 'More information' 链接")
+    print(f"完成: {result['steps']} 步骤")
+```
+
+### 断言验证
+
+```python
+with WebTester() as tester:
+    tester.goto("https://example.com")
+    result = tester.verify("页面包含 'Example Domain' 文字")
+    print(f"验证: {'✅' if result['passed'] else '❌'} {result['reason']}")
+```
+
+### 视觉回归测试
+
+```python
+with WebTester() as tester:
+    tester.goto("https://example.com")
+    
+    # 首次运行：保存基线
+    tester.save_baseline("homepage")
+    
+    # 后续运行：对比基线
+    result = tester.compare_visual("homepage", threshold=0.01)
+    if result["match"]:
+        print("✅ 视觉匹配")
+    else:
+        print(f"❌ 差异: {result['diff_percent']*100:.1f}%")
+        print(f"   差异图: {result['diff_image']}")
+```
+
+### 批量测试
+
+```bash
+# 串行执行
+python tests/test_cases.py
+
+# 并行执行（3 个线程）
+python tests/test_cases.py --parallel --workers 3
+
+# 无头模式
+python tests/test_cases.py --headless
+```
+
+## 🔧 配置项
+
+| 环境变量 | 默认值 | 说明 |
+|----------|--------|------|
+| `ANTHROPIC_API_KEY` | - | Claude API 密钥（必填） |
+| `ANTHROPIC_BASE_URL` | 官方地址 | API 代理地址 |
+| `ANTHROPIC_MODEL` | `claude-sonnet-4-20250514` | 模型名称 |
+| `API_TIMEOUT` | `60` | API 超时（秒） |
+| `API_MAX_RETRIES` | `3` | 最大重试次数 |
+| `LOG_LEVEL` | `INFO` | 日志级别 |
+| `LOG_FILE` | - | 日志文件路径 |
+
+## 📁 项目结构
+
+```
+ai-web-tester/
+├── src/
+│   ├── main.py              # WebTester 主类
+│   ├── vision/              # AI 视觉模型
+│   ├── browser/             # Playwright 浏览器控制
+│   ├── agent/               # 测试规划和执行
+│   ├── reporter/            # HTML/JSON 报告生成
+│   └── utils/               # 工具模块
+│       ├── logging_config.py    # 日志配置
+│       └── visual_regression.py # 视觉回归
+├── tests/
+│   └── test_cases.py        # 测试用例模板
+├── .github/workflows/
+│   └── test.yml             # CI/CD 配置
+├── baselines/               # 视觉基线截图
+├── reports/                 # 测试报告（HTML + JSON）
+├── .env.example             # 环境变量模板
+└── requirements.txt
+```
+
+## 📋 测试报告
+
+每次测试生成：
+- **HTML 报告** - 包含步骤详情和嵌入截图
+- **JSON 结果** - 结构化数据，便于分析
+
+## 🚀 CI/CD
+
+项目包含 GitHub Actions 配置。设置以下 Secrets 后自动运行测试：
+
+- `ANTHROPIC_API_KEY`
+- `ANTHROPIC_BASE_URL`（可选）
+
+## 📄 License
+
+MIT