Metadata-Version: 2.4
Name: ai-ui-testing
Version: 0.2.0
Summary: AI 驱动的 Web UI 自动化测试框架（基于 Playwright + pytest 封装）
Author: my_idea
License-Expression: MIT
Keywords: ui-testing,playwright,pytest,ai,automation
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: playwright>=1.40
Requires-Dist: pytest>=8.0
Requires-Dist: pytest-rerunfailures>=14.0
Requires-Dist: PyYAML>=6.0
Requires-Dist: pydantic>=2.5
Provides-Extra: allure
Requires-Dist: allure-pytest>=2.13; extra == "allure"
Provides-Extra: openai
Requires-Dist: openai>=1.30; extra == "openai"
Provides-Extra: parallel
Requires-Dist: pytest-xdist>=3.5; extra == "parallel"
Provides-Extra: dev
Requires-Dist: pytest-cov>=4.1; extra == "dev"
Requires-Dist: ruff>=0.4; extra == "dev"
Dynamic: license-file

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

## 快速开始

```bash
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/）

| 文档 | 内容 |
|---|---|
| [docs/01-快速开始.md](docs/01-快速开始.md) | 安装、跑通示例、看报告、接入自家系统 |
| [docs/02-POM编写指南.md](docs/02-POM编写指南.md) | 页面对象模型编写规范、Element/BasePage API |
| [docs/03-AI能力详解.md](docs/03-AI能力详解.md) | 定位器/自动修复/失败分析/用例生成的原理与用法 |
| [docs/04-CLI参考.md](docs/04-CLI参考.md) | `ai-ui` 命令与环境变量 |
| [docs/05-配置参考.md](docs/05-配置参考.md) | config.yaml 全字段说明 |
| [docs/06-FAQ.md](docs/06-FAQ.md) | 常见问题与排查 |
| [docs/07-对话式开发.md](docs/07-对话式开发.md) | 用自然语言对话开发用例：描述需求 → AI 编写 → 运行验证 → 迭代修复 |
| [docs/08-登录态复用.md](docs/08-登录态复用.md) | 登录一次、用例复用 cookies/localStorage（绕开 SSO/扫码/验证码） |
| [docs/09-CI持续集成.md](docs/09-CI持续集成.md) | GitHub Actions / Jenkins / 凭据管理 / 报告与排障 |
| [docs/10-自建CI指南.md](docs/10-自建CI指南.md) | 自建 CI 三种方案（cron/GitLab/Docker）、关键坑、框架配置 |
| [docs/11-分发与使用.md](docs/11-分发与使用.md) | 打包 wheel / 私有源 / git 依赖、使用者流程、安全红线、版本管理 |
| [docs/12-外部AI驱动使用.md](docs/12-外部AI驱动使用.md) | inspect/act/login 能力命令、外部 AI 对话流、登录态会话管理、模块化用例 |

## CLI 速查

| 命令 | 说明 |
|---|---|
| `ai-ui init [-f]` | 生成项目骨架 |
| `ai-ui run [--headed] [--browser X] [--provider X] [路径]` | 运行测试 |
| `ai-ui gen <规格.yaml> --module 模块名` | 自然语言规格 → 按模块生成用例（描述+代码配对） |
| `ai-ui inspect <url>` | 探查页面（输出元素快照 JSON，供 AI 使用） |
| `ai-ui act '<动作JSON>' [--save-auth]` | 执行浏览器动作序列（自然语言定位元素） |
| `ai-ui login <url> --user ... --pwd ...` | 自动识别登录表单并登录，保存登录态 |
| `ai-ui index` | 生成/刷新用例索引 `TEST_INDEX.md`（gen 后自动刷新） |
| `ai-ui analyze --last` | 查看最近失败的 AI 分析 |

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

## 开发与质量保障

```bash
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 用例直接执行，不写代码）
