# auto_ui_test_framework

**Repository Path**: evening-li/auto_ui_test_framework

## Basic Information

- **Project Name**: auto_ui_test_framework
- **Description**:  基于 Playwright + pytest 的 UI 自动化测试框架骨架：采用 PO（PageObject）模式，支持数据驱动测试、语义化元素定位、失败自动截图与统一日志。
- **Primary Language**: Unknown
- **License**: MulanPSL-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-09-14
- **Last Updated**: 2026-09-14

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# UI 自动化测试框架

基于 **Playwright + pytest** 的 UI 自动化测试框架，采用 **PO 模式**（Page Object）设计，支持数据驱动测试。

> 本仓库为**通用骨架模板**：只包含框架基础设施与一个最小示例模块，不含任何具体被测系统的业务数据。
> 接入实际系统时，参照 `business/demo_business/` 新增业务模块即可。

## 特性

- **PO 模式**：元素定位与业务逻辑分离，元素配置集中在 `*_elements.yaml`
- **语义定位优先**：`get_by_role` / `get_by_text` / `get_by_placeholder` / `get_by_label`，避免脆弱的动态 ID
- **数据驱动**：统一的数据加载器，支持 YAML / CSV / Excel
- **统一日志**：控制台 + 文件双输出
- **失败自动截图**：测试失败时自动截图并写入 HTML 报告
- **配置外置**：被测地址与账号通过配置文件 / 环境变量注入，不写死在代码里

## 目录结构

```
auto_ui_test_framework_public/
├── conftest.py                  # 全局 fixtures（browser/context/page）与钩子
├── pytest.ini                   # pytest 配置与自定义 markers
├── requirements.txt             # 依赖
├── LICENSE                      # 木兰宽松许可证 v2
│
├── config/                      # 配置层
│   ├── config.py                # 配置管理类（读取 settings.yaml，支持环境变量覆盖）
│   ├── browser.py               # 浏览器管理类（BrowserManager）
│   └── settings.example.yaml    # 配置模板（复制为 settings.yaml 使用）
│
├── utils/                       # 工具层
│   ├── findelement.py           # 元素定位工具（读取 business/ 下元素配置）
│   ├── read_data.py             # 多格式数据读取（TestDataLoader）
│   ├── logger_utils.py          # 日志工具（LogManager / get_logger）
│   └── base_utils.py            # 基础工具（时间戳、截图路径等）
│
├── business/                    # 业务层（PO）
│   ├── base_business.py         # BaseBusiness / CommonBusiness / CrudBusiness
│   ├── common_elements.yaml     # 跨模块公共元素
│   └── demo_business/           # 最小示例模块
│       ├── demo_business.py
│       └── demo_elements.yaml
│
├── data/                        # 测试数据（YAML / CSV / Excel）
│   └── example_data.yaml
│
├── test_case/                   # 测试用例层
│   └── test_demo.py
│
├── reports/                     # 测试报告与截图（运行时生成，已忽略）
└── logs/                        # 日志（运行时生成，已忽略）
```

## 快速开始

### 1. 安装依赖

```bash
pip install -r requirements.txt
playwright install
```

### 2. 配置

复制配置模板并按需修改：

```bash
cp config/settings.example.yaml config/settings.yaml
```

`config/settings.yaml` 已加入 `.gitignore`，不会被提交。

关键配置项：

```yaml
browser:
  type: chromium
  headless: true      # 调试时可设为 false
  slow_mo: 50
  timeout: 30000

base_url: "https://example.com"   # 被测系统基地址

login:                            # 登录账号（按角色）
  default:
    username: "your_username"
    password: "your_password"
    tenant: ""
```

也支持环境变量覆盖，便于 CI：

| 环境变量 | 覆盖项 |
|----------|--------|
| `AUT_SETTINGS` | 配置文件路径 |
| `AUT_BASE_URL` | `base_url` |
| `AUT_USERNAME` / `AUT_PASSWORD` / `AUT_TENANT` | `login.<role>` 账号信息 |

### 3. 运行测试

```bash
# 运行全部测试
pytest test_case/ -v

# 冒烟测试
pytest test_case/ -m smoke -v

# 数据驱动测试
pytest test_case/ -m data_driven -v

# 生成 HTML 报告（默认已开启）
pytest test_case/ -v --html=reports/report.html

# 并行执行
pytest test_case/ -n auto
```

## 编写测试

### PO 模式：新增一个业务模块

1. 在 `business/` 下新建模块目录，例如 `business/login_business/`
2. 编写元素配置 `login_elements.yaml`：

```yaml
login:
  tenant_selector:
    by: role
    value: "combobox"
    timeout: 15000
    description: "租户选择下拉框"

  username_input:
    by: placeholder
    value: "请输入账号"
    timeout: 10000
    description: "账号输入框"
```

3. 编写业务类：

```python
from business.base_business import BaseBusiness


class LoginBusiness(BaseBusiness):
    PAGE_NAME = 'login'

    def login(self, username: str, password: str) -> bool:
        self.fe.fill(self.PAGE_NAME, 'username_input', username)
        # ...
        return True
```

4. 在 `business/__init__.py` 中导出，测试用例即可 `from business import LoginBusiness`

**元素定位配置格式**：

| 字段 | 说明 |
|------|------|
| `by` | 定位方式：`role` / `text` / `label` / `placeholder` / `xpath` / `test_id` / css |
| `value` | 定位值（`role` 时为 role 类型） |
| `name` | 仅 `role` 使用，作为 name 过滤条件 |
| `timeout` | 超时时间（毫秒） |
| `description` | 说明 |

### 数据驱动

```python
import pytest
from utils.read_data import TestDataLoader

loader = TestDataLoader()

@pytest.mark.parametrize('case', loader.read_yaml('example_data.yaml', key='demo_cases'))
def test_example(case):
    assert case['name']
```

## 日志与报告

- 日志：`logs/`（统一输出到 `logs/test_run.log`）
- 报告：`reports/report.html`
- 失败截图：`reports/screenshots/`

## 全局 Fixtures

| Fixture | 作用域 | 说明 |
|---------|--------|------|
| `browser` | session | 浏览器实例 |
| `context` | function | 浏览器上下文（测试隔离） |
| `page` | function | 页面对象 |

需要登录前置的用例，可在项目内自行定义 `logged_in_page` fixture，复用业务层登录方法。

## 自定义 Markers

`smoke` / `regression` / `data_driven` / `workflow`

## 许可证

[木兰宽松许可证，第 2 版](LICENSE)