Metadata-Version: 2.4
Name: ai-ui-testing
Version: 0.1.0
Summary: AI 驱动的 Web UI 自动化测试框架（基于 Playwright + pytest 封装）
Author: my_idea
License: MIT License
        
        Copyright (c) 2026 my_idea
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
        
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 依赖、使用者流程、安全红线、版本管理 |

## CLI 速查

| 命令 | 说明 |
|---|---|
| `ai-ui init [-f]` | 生成项目骨架 |
| `ai-ui run [--headed] [--browser X] [--provider X] [路径]` | 运行测试 |
| `ai-ui gen <规格.yaml> [-o 目录]` | 自然语言规格 → pytest 用例 |
| `ai-ui analyze --last` | 查看最近失败的 AI 分析 |

## 目录结构

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

## Roadmap

- [ ] 并行执行（pytest-xdist）与 Allure 历史趋势
- [ ] 连接外部浏览器实例复用登录态（CDP 协议 / ego-lite 等）：用例直接跑在已登录会话上，绕开 SSO、扫码登录、验证码等登录前置成本（适合本地/冒烟；CI 仍需自行处理登录）
- [ ] 截图对比（视觉回归）+ AI 差异分析
- [ ] 页面对象类 AI 一键生成（输入 URL → 生成 POM）
- [ ] 定位器学习缓存的版本管理（按 URL/提交关联）
- [ ] 关键字驱动（YAML 用例直接执行，不写代码）
