feat: 增强测试框架功能

主要改进: - 新增统一测试器 (universal_tester.py) 支持多种测试模式 - 优化测试报告生成器，支持汇总报告和操作截图 - 增强探索器 DFS 算法和状态指纹识别 - 新增智能测试配置 (smart_test.yaml) - 改进 AI 模型集成 (GLM/Gemini 支持) - 添加开发调试工具和文档
2026-01-05 20:23:02 +08:00
parent 3447ea340a
commit 1f1cc4db9a
31 changed files with 4631 additions and 770 deletions
--- a/README.md
+++ b/README.md
@@ -6,12 +6,15 @@

 - 🤖 **AI 驱动** - 使用 Claude/GPT-4V 视觉模型理解页面内容
 - 📝 **自然语言** - 用自然语言描述测试目标，无需编写选择器
+- 🌐 **通用测试** - 支持测试任意网站，不局限于特定系统
+- 🎯 **智能定位** - 语义化定位器，自动识别元素
 - 📊 **自动报告** - 生成嵌入截图的 HTML 报告 + JSON 结果
- 🔧 **可配置** - 支持多种 AI 模型和 API 代理
+- 🔧 **灵活配置** - 支持 JSON/YAML 配置文件
+- 🚀 **多种模式** - 探索模式、目标模式、混合模式
 - 🔄 **自动重试** - 指数退避重试机制
 - 👁️ **视觉回归** - 基线对比检测 UI 变化
 - ⚡ **并行执行** - 多线程运行测试用例
- 🚀 **CI/CD** - GitHub Actions 集成
+- 📦 **开箱即用** - 简单命令行即可开始测试

 ## 🚀 快速开始

@@ -41,35 +44,131 @@ LOG_LEVEL=INFO                                 # 日志级别

 > ⚠️ **注意**：`BASE_URL` 不要包含 `/v1` 后缀，SDK 会自动添加。

-### 3. 运行测试
+### 3. 开始测试
+
+#### 最简单的测试方式

 ```bash
-python example.py
+# 测试任意网站
+python tests/quick_test.py https://github.com
+
+# 使用其他 AI 模型
+python tests/quick_test.py https://github.com --model glm
+
+# 无头模式（不显示浏览器）
+python tests/quick_test.py https://github.com --headless
+```
+
+#### 使用配置文件测试
+
+```bash
+# 使用 JSON 配置
+python tests/universal_tester.py --config tests/configs/github_example.json
+
+# 使用 YAML 配置
+python tests/universal_tester.py --config tests/configs/enterprise_system.yaml
+```
+
+#### 需要登录的测试
+
+```bash
+python tests/quick_test.py https://example.com --login --username user@example.com --password yourpassword
 ```

 ## 📖 使用方法

-### 基础用法
+### 方式一：快速测试（推荐新手）
+
+```bash
+# 基础用法
+python tests/quick_test.py <URL>
+
+# 完整参数
+python tests/quick_test.py <URL> --model claude --headless --max-clicks 50
+```
+
+### 方式二：配置文件测试（推荐复杂场景）
+
+创建配置文件 `my_test.json`：
+
+```json
+{
+  "name": "我的测试",
+  "url": "https://example.com",
+  "mode": "explore",
+  "login": {
+    "username": "user@example.com",
+    "password": "password"
+  },
+  "explore_config": {
+    "max_depth": 10,
+    "max_clicks": 50,
+    "focus_patterns": ["管理", "设置"],
+    "dangerous_patterns": ["删除", "退出"]
+  }
+}
+```
+
+运行测试：
+
+```bash
+python tests/universal_tester.py --config my_test.json
+```
+
+### 方式三：编程接口（推荐开发者）

 ```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']}")
+
+# 智能探索
+with WebTester() as tester:
+    tester.goto("https://example.com")
+    result = tester.explore({
+        "max_depth": 5,
+        "max_clicks": 30,
+        "focus_patterns": ["重要功能"]
+    })
 ```

-### 视觉回归测试
+## 🔧 高级功能
+
+### 1. 表单智能填充
+
+自动检测并填充表单：
+
+```python
+# AI 会自动识别表单字段并填充
+tester.test("填写注册表单并提交")
+```
+
+### 2. 业务流程测试
+
+配置多步骤流程：
+
+```yaml
+steps:
+  - action: goal
+    goal: "点击登录按钮"
+  - action: explore
+    config:
+      max_clicks: 20
+  - action: verify
+    target: "显示用户信息"
+```
+
+### 3. 视觉回归测试

 ```python
 with WebTester() as tester:
@@ -84,23 +183,83 @@ with WebTester() as tester:
        print("✅ 视觉匹配")
    else:
        print(f"❌ 差异: {result['diff_percent']*100:.1f}%")
-        print(f"   差异图: {result['diff_image']}")
 ```

-### 批量测试
+### 4. 批量测试

 ```bash
-# 串行执行
+# 运行所有测试用例
 python tests/test_cases.py

-# 并行执行（3 个线程）
+# 并行执行
 python tests/test_cases.py --parallel --workers 3

-# 无头模式
-python tests/test_cases.py --headless
+# 选择特定测试
+python tests/test_cases.py --case "登录功能测试"
 ```

-## 🔧 配置项
+## 📋 配置详解
+
+### 测试模式
+
+| 模式 | 说明 | 适用场景 |
+|------|------|----------|
+| `explore` | AI 自主探索 | 了解新网站功能 |
+| `goal` | 执行特定目标 | 单一任务测试 |
+| `hybrid` | 混合模式 | 复杂业务流程 |
+
+### 配置文件示例
+
+#### JSON 格式
+
+```json
+{
+  "name": "测试名称",
+  "url": "https://example.com",
+  "mode": "explore",
+  "model": "claude",
+  "headless": true,
+  "login": {
+    "username": "user@example.com",
+    "password": "password",
+    "submit_button": "登录"
+  },
+  "explore_config": {
+    "max_depth": 20,
+    "max_clicks": 100,
+    "focus_patterns": ["管理", "设置"],
+    "dangerous_patterns": ["删除", "退出"]
+  },
+  "verifications": [
+    {"type": "url_contains", "value": "/dashboard"},
+    {"type": "element_exists", "value": ".user-profile"}
+  ]
+}
+```
+
+#### YAML 格式
+
+```yaml
+name: 企业系统测试
+url: https://your-system.com
+mode: hybrid
+login:
+  username: test@company.com
+  password: password
+
+steps:
+  - action: goal
+    goal: 点击登录按钮
+  - action: explore
+    config:
+      max_clicks: 20
+
+verifications:
+  - type: url_contains
+    value: /dashboard
+```
+
+## 🔧 环境变量

 | 环境变量 | 默认值 | 说明 |
 |----------|--------|------|
@@ -121,12 +280,23 @@ ai-web-tester/
 │   ├── vision/              # AI 视觉模型
 │   ├── browser/             # Playwright 浏览器控制
 │   ├── agent/               # 测试规划和执行
+│   │   ├── executor.py      # 语义化定位器
+│   │   ├── explorer.py      # 智能探索
+│   │   └── planner.py       # 测试规划
 │   ├── reporter/            # HTML/JSON 报告生成
 │   └── utils/               # 工具模块
-│       ├── logging_config.py    # 日志配置
-│       └── visual_regression.py # 视觉回归
 ├── tests/
-│   └── test_cases.py        # 测试用例模板
+│   ├── test_cases.py        # 原始测试用例
+│   ├── universal_tester.py  # 通用测试框架
+│   ├── quick_test.py        # 快速测试工具
+│   ├── configs/             # 配置文件示例
+│   │   ├── github_example.json
+│   │   └── enterprise_system.yaml
+│   └── README.md            # 测试框架使用说明
+├── config/
+│   └── test_strategies.yaml # 测试策略配置
+├── docs/
+│   └── strategies.py        # 策略文档
 ├── .github/workflows/
 │   └── test.yml             # CI/CD 配置
 ├── baselines/               # 视觉基线截图
@@ -135,11 +305,32 @@ ai-web-tester/
 └── requirements.txt
 ```

-## 📋 测试报告
+## 📊 测试报告

 每次测试生成：
 - **HTML 报告** - 包含步骤详情和嵌入截图
 - **JSON 结果** - 结构化数据，便于分析
+- **操作日志** - 详细的执行记录
+
+## 🎯 最佳实践
+
+### 1. 测试设计
+
+- 使用清晰的自然语言描述测试目标
+- 合理设置 `max_clicks` 和 `max_depth` 避免无限探索
+- 利用 `focus_patterns` 引导 AI 关注重要功能
+
+### 2. 元素定位
+
+- 优先使用语义化描述（如"登录按钮"而非"蓝色按钮"）
+- 对于复杂页面，使用配置文件精确定位
+- 利用 `dangerous_patterns` 避免危险操作
+
+### 3. 错误处理
+
+- 查看测试报告中的截图分析失败原因
+- 调整 `API_TIMEOUT` 应对网络问题
+- 使用 `LOG_LEVEL=DEBUG` 获取详细日志

 ## 🚀 CI/CD

@@ -148,6 +339,30 @@ ai-web-tester/
 - `ANTHROPIC_API_KEY`
 - `ANTHROPIC_BASE_URL`（可选）

+示例工作流：
+
+```yaml
+name: AI Web Test
+on: [push, pull_request]
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v2
+      - name: Setup Python
+        uses: actions/setup-python@v2
+        with:
+          python-version: '3.9'
+      - name: Install dependencies
+        run: |
+          pip install -r requirements.txt
+          playwright install chromium
+      - name: Run tests
+        run: python tests/universal_tester.py --config tests/configs/ci_test.json
+        env:
+          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
+```
+
 ## 📄 License

 MIT