AI Web Tester

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

✨ 特性

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

🚀 快速开始

1. 安装依赖

pip install -r requirements.txt
playwright install chromium

2. 配置环境变量

cp .env.example .env

编辑 .env 文件：

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. 开始测试

最简单的测试方式

# 测试任意网站
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

使用配置文件测试

# 使用 JSON 配置
python tests/universal_tester.py --config tests/configs/github_example.json

# 使用 YAML 配置
python tests/universal_tester.py --config tests/configs/enterprise_system.yaml

需要登录的测试

python tests/quick_test.py https://example.com --login --username user@example.com --password yourpassword

📖 使用方法

方式一：快速测试（推荐新手）

# 基础用法
python tests/quick_test.py <URL>

# 完整参数
python tests/quick_test.py <URL> --model claude --headless --max-clicks 50

方式二：配置文件测试（推荐复杂场景）

创建配置文件 my_test.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": ["删除", "退出"]
  }
}

运行测试：

python tests/universal_tester.py --config my_test.json

方式三：编程接口（推荐开发者）

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. 表单智能填充

自动检测并填充表单：

# AI 会自动识别表单字段并填充
tester.test("填写注册表单并提交")

2. 业务流程测试

配置多步骤流程：

steps:
  - action: goal
    goal: "点击登录按钮"
  - action: explore
    config:
      max_clicks: 20
  - action: verify
    target: "显示用户信息"

3. 视觉回归测试

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. 批量测试

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

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

# 选择特定测试
python tests/test_cases.py --case "登录功能测试"

📋 配置详解

测试模式

模式	说明	适用场景
explore	AI 自主探索	了解新网站功能
goal	执行特定目标	单一任务测试
hybrid	混合模式	复杂业务流程

配置文件示例

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 格式

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（可选）

示例工作流：

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