feat(docs,page_objects): 完善文档以及测试用例演示
- 新增 AndroidSDK环境配置指南.md, 常用参数.md - 更新 README.md - 优化 wan_android_home.py, wan_android_project.py - 其他优化
This commit is contained in:
106
docs/AndroidSDK环境配置指南.md
Normal file
106
docs/AndroidSDK环境配置指南.md
Normal file
@@ -0,0 +1,106 @@
|
||||
# Android SDK 环境配置指南
|
||||
|
||||
本指南将引导您完成 Appium for Android 测试所需的基础环境——Android SDK 的安装与配置。
|
||||
|
||||
## 1. 创建 SDK 目录
|
||||
|
||||
首先，在您的电脑上选择一个合适的位置（例如 `D:\`），创建一个新目录作为 Android SDK 的根目录。
|
||||
|
||||
```
|
||||
D:\android_sdk
|
||||
```
|
||||
|
||||
## 2. 安装命令行工具 (Command Line Tools)
|
||||
|
||||
1. 访问 Android Studio [官方下载页面](https://developer.android.google.cn/studio?hl=zh-cn#command-line-tools-only)
|
||||
，在页面底部找到 **"仅命令行工具"** 部分，下载适用于您操作系统的软件包（例如 `commandlinetools-win-xxxxxxx_latest.zip`）。
|
||||
|
||||
2. 解压下载的 `zip` 文件。
|
||||
|
||||
3. 将解压后得到的 `cmdline-tools` 目录移动到您在第一步创建的 `android_sdk` 目录中。
|
||||
|
||||
4. 进入 `android_sdk/cmdline-tools` 目录，在内部创建一个名为 `latest` 的新目录。
|
||||
|
||||
5. 将 `cmdline-tools` 目录内的所有内容（包括 `bin` 目录、`lib` 目录、`NOTICE.txt` 和 `source.properties` 文件）移动到刚刚创建的
|
||||
`latest` 目录中。
|
||||
|
||||
完成后的目录结构应如下所示：
|
||||
|
||||
```
|
||||
android_sdk/
|
||||
├── cmdline-tools/
|
||||
│ └── latest/ ← 必须有这个 'latest' 目录
|
||||
│ ├── bin/
|
||||
│ │ └── sdkmanager
|
||||
│ ├── lib/
|
||||
│ └── ...
|
||||
```
|
||||
|
||||
## 3. 安装平台工具 (Platform-Tools)
|
||||
|
||||
1. 访问 SDK
|
||||
平台工具版本说明页面，下载最新的[平台工具包](https://developer.android.google.cn/tools/releases/platform-tools?hl=zh-cn#downloads.html)
|
||||
（例如 `platform-tools-latest-windows.zip`）。
|
||||
|
||||
2. 解压下载的 `zip` 文件。
|
||||
|
||||
3. 将解压后得到的 `platform-tools` 目录整个移动到 `android_sdk` 根目录下。
|
||||
|
||||
此时，您的 `android_sdk` 目录结构应如下：
|
||||
|
||||
```
|
||||
android_sdk/
|
||||
├── cmdline-tools/
|
||||
├── platform-tools/
|
||||
└── ...
|
||||
```
|
||||
|
||||
## 4. 配置环境变量
|
||||
|
||||
为了让系统能够识别 `adb`、`sdkmanager` 等命令，需要配置以下环境变量：
|
||||
|
||||
1. **新建 `ANDROID_HOME`**:
|
||||
* 变量名: `ANDROID_HOME`
|
||||
* 变量值: `D:\android_sdk` (替换为您的实际路径)
|
||||
|
||||
2. **编辑 `Path` 变量**:
|
||||
在系统变量的 `Path` 中，追加以下两项：
|
||||
```
|
||||
%ANDROID_HOME%/tools
|
||||
%ANDROID_HOME%/tools/bin
|
||||
%ANDROID_HOME%/platform-tools
|
||||
%ANDROID_HOME%/cmdline-tools/latest/bin
|
||||
```
|
||||
|
||||
|
||||
|
||||
> **提示**: 关于环境变量的更多详细设置，请参阅
|
||||
> Android [官方文档](https://developer.android.google.cn/tools/variables?hl=zh-cn)。
|
||||
|
||||
## 5. 验证安装
|
||||
|
||||
打开一个新的命令行窗口（CMD 或 PowerShell），输入以下命令：
|
||||
|
||||
```sh
|
||||
adb --version
|
||||
```
|
||||
|
||||
如果成功显示 Android Debug Bridge 的版本信息，则说明 `platform-tools` 已配置成功。
|
||||
|
||||
## 6. (可选) 配置 Bundletool
|
||||
|
||||
`bundletool` 是 Google 用于处理 Android App Bundles (`.aab` 文件) 的工具。如果 `appium-doctor` 提示
|
||||
`bundletool.jar cannot be found` 警告，您可以按以下步骤处理：
|
||||
|
||||
1. **下载**: 从 bundletool GitHub Releases 页面下载最新的 `bundletool-all-x.x.x.jar` 文件。
|
||||
|
||||
2. **创建目录**: 在您的 `ANDROID_HOME` 目录下（例如 `D:\android_sdk`）创建一个名为 `bundle-tool` 的新文件夹。
|
||||
|
||||
3. **重命名并移动**: 将下载的 `.jar` 文件重命名为 `bundletool.jar`，然后将其移动到 `bundle-tool` 文件夹中。
|
||||
|
||||
4. **配置 PATH**: 将 `bundle-tool` 目录也添加到系统的 `Path` 环境变量中：
|
||||
```
|
||||
%ANDROID_HOME%\bundle-tool
|
||||
```
|
||||
|
||||
完成以上步骤后，重新运行 `appium-doctor`，相关警告应会消失。
|
||||
BIN
docs/assets/image-20260110141432210.png
Normal file
BIN
docs/assets/image-20260110141432210.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 218 KiB |
BIN
docs/assets/image-20260110142023709.png
Normal file
BIN
docs/assets/image-20260110142023709.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 164 KiB |
BIN
docs/assets/image-20260110144326458.png
Normal file
BIN
docs/assets/image-20260110144326458.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 6.9 KiB |
BIN
docs/assets/image-20260110144556568.png
Normal file
BIN
docs/assets/image-20260110144556568.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 29 KiB |
79
docs/常用参数.md
Normal file
79
docs/常用参数.md
Normal file
@@ -0,0 +1,79 @@
|
||||
# 常用参数说明
|
||||
|
||||
## 设备能力配置 (Capabilities)
|
||||
|
||||
```python
|
||||
ANDROID_CAPS = {
|
||||
"platformName": "Android",
|
||||
"automationName": "uiautomator2",
|
||||
"deviceName": "Android",
|
||||
"appPackage": "com.android.settings",
|
||||
"appActivity": ".Settings",
|
||||
"noReset": False
|
||||
}
|
||||
```
|
||||
|
||||
| 字段名称 | 字段含义解释 | 示例值说明 |
|
||||
|----------------|---------------------------------------------|---------------------------------------------------------------------------------------|
|
||||
| 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 下的一个相对路径。 |
|
||||
|
||||
获取应用的 appPackage 有几种常用方法
|
||||
|
||||
```shell
|
||||
adb shell pm list packages | findstr your_package_name
|
||||
# adb shell pm list packages -3 仅列出用户安装的第三方应用的包名
|
||||
```
|
||||
|
||||
获取应用的 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
|
||||
|
||||
# 2，通过 ADB 命令获取（需应用已安装）
|
||||
adb shell dumpsys window | findstr mCurrentFocus
|
||||
# 输出结果：mCurrentFocus=Window{... u0 com.example.myapp/com.example.myapp.MainActivity}
|
||||
# / 后面的部分 com.example.myapp.MainActivity 就是当前 Activity
|
||||
```
|
||||
|
||||
常用补充字段：
|
||||
noReset：True/False。是否在会话开始前重置应用状态（例如清除应用数据）。设置为 True 可以避免每次测试都重新登录。
|
||||
|
||||
platformVersion：指定设备的Android系统版本（如 "11.0"）。虽然不是必须，但指定后能增强兼容性。
|
||||
|
||||
unicodeKeyboard 和 resetKeyboard：用于处理中文输入等特殊字符输入。
|
||||
|
||||
newCommandTimeout：设置Appium服务器等待客户端发送新命令的超时时间（秒），默认为60秒。在长时间操作中可能需要增加。
|
||||
|
||||
## allure核心属性表
|
||||
|
||||
| 属性 | 说明 | 用法示例 |
|
||||
|---------------------|--------------------------------------|-------------|
|
||||
| @allure.epic | 顶层分类（如：APP项目名称） | 定义在测试类/项目上 |
|
||||
| @allure.feature | 功能模块（如：登录模块、交易模块） | 定义在测试类上 |
|
||||
| @allure.story | 用户场景（如：成功登录、账号锁定） | 定义在测试方法上 |
|
||||
| @allure.title | 测试用例标题（支持动态显示） | 替换方法名显示在报告中 |
|
||||
| @allure.severity | "严重程度（BLOCKER, CRITICAL, NORMAL...）" | 用于筛选高优先级用例 |
|
||||
| @allure.description | 详细描述（支持 Markdown） | 解释测试背景或前提条件 |
|
||||
| @allure.link | 外部链接（Bug系统、需求文档） | 快速点击跳转 |
|
||||
| @allure.issue | 缺陷链接（通常会自动带上 ISSUE 前缀） | 追踪已知 Bug |
|
||||
|
||||
Pytest 原生高频参数 和 你的自定义参数。
|
||||
|
||||
| **分类** | **长参数** | **短参数/别名** | **作用说明** |
|
||||
|-----------|------------------|------------|------------------------------------|
|
||||
| **基础运行** | `--verbose` | `-v` | 打印详细运行过程（显示用例名称） |
|
||||
| | (无) | `-s` | 允许在控制台打印代码里的 `print` 内容 |
|
||||
| **调试控制** | `--exitfirst` | `-x` | 遇到第一个失败的用例就立即停止测试 |
|
||||
| | `--maxfail=n` | (无) | 累计失败 `n` 个用例后停止运行 |
|
||||
| | `--last-failed` | `--lf` | 只运行上次运行失败的用例 |
|
||||
| **自定义参数** | **`--platform`** | **`-P`** | 指定运行平台 \[Android\/IOS\/别名\]\(可自定义) |
|
||||
| | **`--udid`** | **`-U`** | 指定手机唯一标识 (可自定义) |
|
||||
| | **`--host`** | **`-H`** | 指定 Appium 服务器地址 (可自定义) |
|
||||
| **报告相关** | `--alluredir` | (无) | 指定 Allure 原始数据的存放路径 |
|
||||
Reference in New Issue
Block a user