CNWei/AppAutoTest
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat(docs,page_objects): 完善文档以及测试用例演示

Browse Source 
- 新增 AndroidSDK环境配置指南.md, 常用参数.md
- 更新 README.md
- 优化 wan_android_home.py, wan_android_project.py
- 其他优化
This commit is contained in:
CNWei
2026-02-27 16:44:00 +08:00
parent 52758940ed
commit 332deb3666
19 changed files with 562 additions and 239 deletions
Download Patch File Download Diff File Expand all files Collapse all files

217
README.md
View File

@@ -1,79 +1,176 @@
# AppAutoTest
# AppAutoTest - 基于 Python 的 App 自动化测试框架
## 设备能力配置 (Capabilities)
## 1. 简介
```python
ANDROID_CAPS = {
"platformName": "Android",
"automationName": "uiautomator2",
"deviceName": "Android",
"appPackage": "com.android.settings",
"appActivity": ".Settings",
"noReset": False
}
`AppAutoTest` 是一个基于 Python 构建的健壮且可扩展的移动应用自动化测试框架。它利用 Appium、Pytest 和 Allure 等行业标准工具，为测试
Android 和 iOS 应用提供了全面的解决方案。该框架采用页面对象模型 (POM) 设计，以提高可维护性和可扩展性，并包含一套实用工具以简化测试开发和执行。
## 2. 特性
- **跨平台支持**: 原生支持 Android (通过 `UiAutomator2`) 和 iOS (通过 `XCUITest`)。
- **页面对象模型 (POM)**: 强制分离 UI 元素定位器和测试逻辑，增强代码可读性和可维护性。
- **丰富的测试报告**: 与 Allure 框架无缝集成，生成包含测试步骤、截图、日志和环境信息的详细交互式报告。
- **自动服务管理**: 智能管理 Appium 服务器生命周期。如果本地服务器未运行，它可以自动启动，或者连接到现有的外部服务器。
- **强大的驱动引擎**: 包含核心驱动封装 (`CoreDriver`)，通过内置显式等待、流式 API、高级日志记录和健壮的错误处理简化 Appium
操作。
- **灵活配置**: 轻松管理设备能力 (`config/caps.yaml`)、特定环境参数和敏感数据 (`.env`)。
- **可自定义等待条件**: 扩展 Selenium 的标准预期条件，提供用于复杂场景（如等待 Toast 消息或特定元素计数）的自定义可重用等待。
- **高级日志与追踪**: 利用自定义装饰器 (`@step_trace`) 自动生成测试步骤的分层日志，包括执行时间、输入参数和状态。
- **自动截图**: 在测试失败时自动捕获截图，并允许在任何步骤轻松将截图附加到 Allure 报告中以便快速调试。
- **现代依赖管理**: 使用 `uv` (通过 `pyproject.toml`) 进行快速 Python 依赖解析，使用 `npm` (通过 `package.json`) 管理
Node.js 依赖。
## 3. 项目结构
框架遵循逻辑清晰且模块化的结构，以促进可扩展性和易于导航。
```text
AppAutoTest/
├── config/
│ └── caps.yaml # 不同平台的 Appium capabilities 配置。
├── core/
│ ├── base_page.py # 所有页面对象的抽象基类。
│ ├── config_loader.py # 加载配置文件 (caps, 环境设置)。
│ ├── custom_expected_conditions.py # 定义复杂 UI 状态的自定义等待条件。
│ ├── driver.py # 核心 Appium 驱动封装，增强了操作和等待。
│ ├── modules.py # 通用枚举定义 (如 AppPlatform, Locator)。
│ ├── run_appium.py # 处理 Appium 服务器的生命周期。
│ └── settings.py # 全局框架设置 (路径, 超时等)。
├── data/ # 数据驱动测试的示例测试数据。
├── docs/ # 文档和说明。
├── outputs/
│ ├── logs/ # 存储测试运行的日志文件。
│ └── screenshots/ # 存储测试期间捕获的截图。
├── page_objects/ # 对象类。
├── reports/ # 存储生成的 Allure HTML 报告。
├── temp/ # 原始 Allure 结果的临时目录。
├── test_cases/ # 测试脚本。
├── utils/
│ ├── decorators.py # 用于日志、截图等的自定义装饰器。
│ ├── dirs_manager.py # 确保所需目录存在的工具。
│ ├── finder.py # 定位策略转换工具。
│ └── report_handler.py # Allure 报告生成工具。
├── .env # 存储环境变量 (如凭据)。Git 忽略此文件。
├── conftest.py # Pytest 的核心配置文件，用于 fixtures 和 hooks。
├── main.py # 执行测试套件的主入口点。
├── package.json # 定义 Node.js 项目元数据和依赖 (Appium)。
├── pytest.ini # Pytest 配置文件 (日志, 标记, 路径)。
├── pyproject.toml # Python 项目元数据和依赖定义 (PEP 621)。
└── README.md # 项目说明。
```
| 字段名称 | 字段含义解释 | 示例值说明 |
|----------------|---------------------------------------------|---------------------------------------------------------------------------------------|
| platformName | 测试的平台/操作系统。这是必填项，告诉自动化框架（如Appium）目标是什么系统。 | "Android" 表示这是一个Android设备。如果是iOS设备，则为 "iOS"。 |
| automationName | 使用的自动化驱动引擎。指定底层用哪个工具来驱动设备进行UI交互。 | "uiautomator2" 是当前主流的Android驱动框架，比旧的 "UiAutomator" 更稳定和高效。 |
| deviceName | 设备标识/名称。用于在同时连接多台设备时指定目标。 | "Android" 是一个通用标识。在实际测试中，通常用 adb devices 获取的真实设备序列号（如 emulator-5554）来替换它，以确保连接到正确的设备。 |
| appPackage | 要测试的应用程序包名。这是应用的唯一标识，就像它在Android系统中的“身份证号”。 | "com.android.settings" 是Android系统“设置”应用的包名。测试你自己的应用时，需替换为你应用的包名。 |
| appActivity | 要启动的应用内具体页面。它指定了应用启动后打开的第一个界面（Activity）。 | ".Settings" 是“设置”应用的主界面。前面的点. 表示它是 appPackage 下的一个相对路径。 |
## 4. 前置条件
获取应用的 appPackage 有几种常用方法
- **Node.js**: 版本 20+ (如 `package.json` 中指定)。
- **Python**: 版本 3.11+ (如 `pyproject.toml` 中指定)。
- **Java JDK**: Appium 和 Android SDK 需要。
- **Android SDK**: 构建和与 Android 应用交互需要。
- **Allure Commandline**: 生成和查看 HTML 报告需要。
> 注意：[Android SDK 环境配置指南](docs/AndroidSDK环境配置指南.md)
## 5. 安装与运行指南
```shell
adb shell pm list packages | findstr your_package_name
# adb shell pm list packages -3 仅列出用户安装的第三方应用的包名
按照以下步骤搭建测试环境。
1. **克隆仓库:**
```bash
git clone <your-repository-url>
cd AppAutoTest
```
2. **安装 Node.js 依赖:**
此命令将在项目目录中本地安装 Appium 及其相关驱动，如 `package.json` 中所定义。
```bash
npm install
```
3. **安装 Python 依赖:**
使用 `uv` 进行 Python 依赖管理。
```bash
# 如果没有安装 uv，请先安装
# 使用 uv 安装项目依赖
uv sync
```
不使用 `uv`进行 Python 依赖管理。
```bash
#使用 pip 安装项目依赖
# 以可编辑模式安装（开发时推荐）
pip install -e .
# 或以普通模式安装
pip install .
```
## 6. 如何运行测试
框架提供了两种主要的测试执行方式。
### 方法 1: 使用主入口点 (推荐)
执行 `main.py` 脚本来运行整个测试套件。此脚本会自动处理所有运行前和运行后的任务。
```bash
python main.py
```
获取应用的 appActivity 有几种常用方法
此命令将：
```shell
# 1，使用 aapt 工具分析 APK 文件（需有安装包）/build-tools/{version}/aapt
aapt dump badging your_app.apk | findstr launchable-activity
# 输出结果：launchable-activity: name='com.example.myapp.MainActivity'
# name= 后面的值 'com.example.myapp.MainActivity' 就是你需要的主 Activity
1. 确保所有必要的输出目录已创建。
2. 归档上次运行的日志文件。
3. 启动 Appium 服务器 (或连接到现有的)。
4. 通过 Pytest 运行 `test_cases/` 目录下的所有测试。
5. 在 `reports/` 目录生成新的 Allure 报告。
# 2，通过 ADB 命令获取（需应用已安装）
adb shell dumpsys window | findstr mCurrentFocus
# 输出结果：mCurrentFocus=Window{... u0 com.example.myapp/com.example.myapp.MainActivity}
# / 后面的部分 com.example.myapp.MainActivity 就是当前 Activity
### 方法 2: 直接使用 Pytest
为了更精细的控制，您可以直接从命令行调用 `pytest`。`conftest.py` 中定义的 fixtures 仍将管理 Appium 服务器和驱动会话。
```bash
# 运行特定的测试文件并显示详细输出
pytest -v test_cases/test_wan_android_home.py
# 运行测试并在第一个失败处停止
pytest -x
# 覆盖默认平台并指定设备 UDID
pytest --platform IOS --udid <your_iphone_udid>
```
常用补充字段：
noReset：True/False。是否在会话开始前重置应用状态（例如清除应用数据）。设置为 True 可以避免每次测试都重新登录。
**可用的自定义命令行参数:**
platformVersion：指定设备的Android系统版本（如 "11.0"）。虽然不是必须，但指定后能增强兼容性。
- `--platform`: 目标平台 (`Android` 或 `IOS`)。默认为 `Android`。
- `--udid`: 目标设备的唯一设备标识符 (UDID)。
- `--host`: Appium 服务器的主机地址。默认为 `127.0.0.1`。
- `--port`: Appium 服务器的端口。默认为 `4723`。
unicodeKeyboard 和 resetKeyboard：用于处理中文输入等特殊字符输入。
> 注意：[其他常用参数](./docs/常用参数.md)
newCommandTimeout：设置Appium服务器等待客户端发送新命令的超时时间（秒），默认为60秒。在长时间操作中可能需要增加。
## 7. 测试报告
## allure核心属性表
测试运行后，原始 Allure 结果存储在 `temp/` 目录中。`main.py` 脚本会自动根据这些结果生成 HTML 报告。
| 属性 | 说明 | 用法示例 |
|---------------------|--------------------------------------|-------------|
| @allure.epic | 顶层分类（如：APP项目名称） | 定义在测试类/项目上 |
| @allure.feature | 功能模块（如：登录模块、交易模块） | 定义在测试类上 |
| @allure.story | 用户场景（如：成功登录、账号锁定） | 定义在测试方法上 |
| @allure.title | 测试用例标题（支持动态显示） | 替换方法名显示在报告中 |
| @allure.severity | "严重程度（BLOCKER, CRITICAL, NORMAL...）" | 用于筛选高优先级用例 |
| @allure.description | 详细描述（支持 Markdown） | 解释测试背景或前提条件 |
| @allure.link | 外部链接（Bug系统、需求文档） | 快速点击跳转 |
| @allure.issue | 缺陷链接（通常会自动带上 ISSUE 前缀） | 追踪已知 Bug |
要查看最新报告，可以使用 Allure 命令行工具启动服务：
Pytest 原生高频参数 和 你的自定义参数。
```bash
# 此命令将在默认 Web 浏览器中打开报告
allure serve temp/
```
| **分类** | **长参数** | **短参数/别名** | **作用说明** |
|-----------|------------------|------------|------------------------------------|
| **基础运行** | `--verbose` | `-v` | 打印详细运行过程（显示用例名称） |
| | (无) | `-s` | 允许在控制台打印代码里的 `print` 内容 |
| **调试控制** | `--exitfirst` | `-x` | 遇到第一个失败的用例就立即停止测试 |
| | `--maxfail=n` | (无) | 累计失败 `n` 个用例后停止运行 |
| | `--last-failed` | `--lf` | 只运行上次运行失败的用例 |
| **自定义参数** | **`--platform`** | **`-P`** | 指定运行平台 \[Android\/IOS\/别名\]\(可自定义) |
| | **`--udid`** | **`-U`** | 指定手机唯一标识 (可自定义) |
| | **`--host`** | **`-H`** | 指定 Appium 服务器地址 (可自定义) |
| **报告相关** | `--alluredir` | (无) | 指定 Allure 原始数据的存放路径 |
## 8. 核心概念解释
#### 页面对象模型 (POM)
- **`page_objects/`**: 此目录包含 POM 设计的核心。每个类 (例如 `HomePage`)
代表应用程序的一个屏幕或重要组件。它负责封装元素定位器和对这些元素执行操作的方法 (例如 `login(user, pwd)`)。
- **`core/base_page.py`**: 这是所有页面对象的父类。它提供共享功能，如页面间导航 (`go_to`)、将截图附加到报告 (
`attach_screenshot_bytes`) 以及实现通用断言 (`assert_text`)。
#### 驱动引擎
- **`core/driver.py`**: 此类是标准 Appium `webdriver.Remote` 的强大封装。它通过集成内置的显式等待增强了基本操作，使测试更稳定，更不容易出现竞争条件。它还为高级移动手势（如
`swipe()`、`long_press()` 和 `smart_scroll()`）提供了流畅的接口。
#### 自定义装饰器
- **`utils/decorators.py`**: 此模块包含装饰器，可在不干扰逻辑的情况下向测试和页面方法添加强大的横切关注点。
- `@step_trace()`: 自动记录任何被装饰函数的进入、退出、参数和执行时间，创建一个清晰的分层日志，这对调试非常有价值。
- `@action_screenshot()`: 一个简单但有效的装饰器，在方法成功执行后自动截图，在测试报告中提供可视化的审计跟踪。