ai-web-tester/README.md

# AI Web Tester

基于 AI 视觉模型的智能 Web 自动化测试框架。使用自然语言描述测试目标，AI 会自动分析页面并执行操作。

## ✨ 特性

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

## 🚀 快速开始

### 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 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']} 步骤")

# 断言验证
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:
    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}%")
```

### 4. 批量测试

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

# 并行执行
python tests/test_cases.py --parallel --workers 3

# 选择特定测试
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
```

## 🔧 环境变量

| 环境变量 | 默认值 | 说明 |
|----------|--------|------|
| `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/               # 测试规划和执行
│   │   ├── executor.py      # 语义化定位器
│   │   ├── explorer.py      # 智能探索
│   │   └── planner.py       # 测试规划
│   ├── reporter/            # HTML/JSON 报告生成
│   └── utils/               # 工具模块
├── tests/
│   ├── 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/               # 视觉基线截图
├── reports/                 # 测试报告（HTML + JSON）
├── .env.example             # 环境变量模板
└── requirements.txt
```

## 📊 测试报告

每次测试生成：
- **HTML 报告** - 包含步骤详情和嵌入截图
- **JSON 结果** - 结构化数据，便于分析
- **操作日志** - 详细的执行记录

## 🎯 最佳实践

### 1. 测试设计

- 使用清晰的自然语言描述测试目标
- 合理设置 `max_clicks` 和 `max_depth` 避免无限探索
- 利用 `focus_patterns` 引导 AI 关注重要功能

### 2. 元素定位

- 优先使用语义化描述（如"登录按钮"而非"蓝色按钮"）
- 对于复杂页面，使用配置文件精确定位
- 利用 `dangerous_patterns` 避免危险操作

### 3. 错误处理

- 查看测试报告中的截图分析失败原因
- 调整 `API_TIMEOUT` 应对网络问题
- 使用 `LOG_LEVEL=DEBUG` 获取详细日志

## 🚀 CI/CD

项目包含 GitHub Actions 配置。设置以下 Secrets 后自动运行测试：

- `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