From 949d11d6701f31d370a2cde88c39fd887f7505dc Mon Sep 17 00:00:00 2001 From: ConnorQi01 Date: Thu, 7 May 2026 12:13:32 +0800 Subject: [PATCH] Add bilingual README and MeteorTest contract --- README.md | 629 ++++++++++++---------------- README.zh-CN.md | 366 ++++++++++++++++ docs/platform-integration.md | 10 +- test-platform.yml => meteortest.yml | 0 4 files changed, 644 insertions(+), 361 deletions(-) create mode 100644 README.zh-CN.md rename test-platform.yml => meteortest.yml (100%) diff --git a/README.md b/README.md index e7c006c..822009c 100644 --- a/README.md +++ b/README.md @@ -1,241 +1,233 @@ -# 🧪 iOS-Automation-Framework +# iOS-Automation-Framework + +

+ An iOS automation test project for API, UI, performance, reporting, and platform integration +

+ +

+ Python + Appium + pytest + Allure +
+ Related MeteorTest + Issues + Roadmap +
+ Docs English + Docs 中文 +

+ +iOS-Automation-Framework is a complete mobile automation test project for the Yunlu Mall iOS app. It combines API tests, iOS UI tests, performance tests, Allure reports, CI configuration, and a local demo Web UI. + +In the broader platform system, this repository is the test-code carrier and first integration sample. It owns how tests are written and executed: pytest/Appium cases, Page Objects, test data, assertions, and report output. A platform such as [MeteorTest](https://github.com/JunchenMeteor/MeteorTest) owns scheduling, executor status, task metadata, and result collection. + +## Table of Contents + +- [Background](#background) +- [Core Capabilities](#core-capabilities) +- [Execution Loop](#execution-loop) +- [Architecture](#architecture) +- [Project Structure](#project-structure) +- [Quick Start](#quick-start) +- [Platform Integration](#platform-integration) +- [Local Demo Console](#local-demo-console) +- [Test Coverage](#test-coverage) +- [Implementation Notes](#implementation-notes) +- [Validation and CI](#validation-and-ci) +- [Roadmap](#roadmap) +- [License](#license) +- [Maintainer](#maintainer) + +## Background + +Mobile automation projects often start as simple scripts, then gradually become hard to maintain: + +- UI locators are scattered across test cases. +- API, UI, and performance tests use different conventions. +- Test data, environment configuration, and report output are not standardized. +- CI can run tests, but local debugging and report inspection are inconvenient. +- A central platform can schedule work, but each test repository still needs a clear contract for suites and commands. + +This project addresses those problems by keeping test implementation, local demo tooling, and platform integration metadata in one repository. + +## Core Capabilities + +- Page Object Model for iOS UI automation. +- Data-driven API tests using YAML data and pytest parametrization. +- API, UI, and performance test suites in one test repository. +- Allure report output for local runs, CI runs, and platform-triggered runs. +- GitHub Actions and Fastlane/Jenkins configuration examples. +- Local Web UI for code browsing, controlled test execution, real-time logs, Allure reports, and AI Q&A. +- Platform integration contract through `meteortest.yml`. + +## Execution Loop -> **基于云鹿商城的移动端自动化测试框架** | Appium + pytest + Allure + GitHub Actions + Web UI - -![Python](https://img.shields.io/badge/Python-3.9+-blue.svg) -![Framework](https://img.shields.io/badge/Framework-Appium+pytest-green.svg) -![License](https://img.shields.io/badge/License-MIT-yellow.svg) - ---- - -## 📋 项目简介 - -本项目是一个完整的 **iOS 移动端自动化测试工程**，以**云鹿商城 App** 为测试对象，实现了 **UI 自动化测试**、**接口自动化测试**、**性能测试** 三位一体的测试解决方案。 - -它在通用测试平台体系中的定位是：**测试代码载体和第一个接入样板**。本仓库负责“怎么测”，例如 pytest/Appium 用例、Page Object、测试数据、断言和报告输出；通用平台和 Local Agent 负责“谁来调度、在哪里执行、如何回传结果”。 - -内置的 `tools/webui` 仅作为单项目本地 Demo 控制台，用于浏览代码、执行测试、查看实时日志和 Allure 报告，不承担平台中心或通用 Agent 职责。 - -### 核心特性 - -| 特性 | 说明 | -|------|------| -| 🎯 **Page Object 模式** | UI 层与业务逻辑解耦，易于维护 | -| 📊 **数据驱动测试** | YAML 管理测试数据，支持多环境切换 | -| 🔌 **接口/UI 联动** | 统一框架同时支持 API 和 UI 测试 | -| 📈 **Allure 报告** | 可视化测试报告，支持历史趋势 | -| 🔄 **GitHub Actions CI** | 自动化流水线，PR 触发执行 | -| ⚡ **性能测试** | 基于 Locust 的压力测试脚本 | -| 🌐 **本地 Demo 控制台** | 本地 Web UI，支持代码浏览、测试执行、AI 问答 | -| 🔗 **平台接入协议** | 通过 `test-platform.yml` 描述套件、命令、依赖和产物路径 | - ---- +```mermaid +flowchart LR + Contract[meteortest.yml
suite metadata] + Platform[MeteorTest / Local Agent
task scheduling] + Pytest[pytest execution
API / UI / Performance] + Reports[Reports
logs / Allure / screenshots] + Feedback[Analysis
local UI / platform reports] + + Contract --> Platform + Platform --> Pytest + Pytest --> Reports + Reports --> Feedback +``` -## 🏗️ 技术架构 +## Architecture ```mermaid -graph TD - A[🧪 pytest 测试执行层] - A --> B[📱 UI_Automation
Appium + XCUITest] - A --> C[🔌 API_Automation
Requests + pytest] - A --> D[⚡ Performance
Locust] - - B & C & D --> E[🛠️ 基础设施层
Config / Logger / Utils] - E --> F[🚀 CI/CD 层
GitHub Actions / Fastlane] - E --> G[🌐 本地 Demo 控制台
FastAPI + Alpine.js] +flowchart TB + Pytest[pytest execution layer] + + subgraph Suites[Test suites] + UI[UI_Automation
Appium + XCUITest] + API[API_Automation
requests + pytest] + Perf[Performance
Locust] + end + + subgraph Infra[Infrastructure] + Config[config
env settings] + Utils[utils
logging / HTTP / assertions / screenshots] + Reports[Reports
Allure output] + end + + subgraph Tooling[Tooling] + CI[CI
GitHub Actions / Fastlane / Jenkins] + WebUI[Local demo console
FastAPI + Alpine.js] + Contract[meteortest.yml
platform suite contract] + end + + Pytest --> UI + Pytest --> API + Pytest --> Perf + UI --> Infra + API --> Infra + Perf --> Infra + Infra --> CI + Infra --> WebUI + Contract --> Pytest + Pytest --> Reports ``` ---- +## Project Structure -## 📁 项目结构 - -``` +```text iOS-Automation-Framework/ -├── README.md # Project documentation -├── test-platform.yml # TestPlatform suite contract -├── requirements.txt # Python dependencies -├── pytest.ini # pytest configuration -├── conftest.py # Global fixtures -│ -├── config/ # Configuration layer -│ ├── __init__.py -│ ├── settings.py # Global settings -│ ├── environments.yaml # Multi-env config -│ └── local.yml.example # Local config template -│ -├── utils/ # Utility layer -│ ├── __init__.py -│ ├── log_util.py # Logger (loguru) -│ ├── request_util.py # HTTP client -│ ├── assertion_util.py # Assertions -│ └── screenshot_util.py # Screenshot helper -│ -├── UI_Automation/ # UI tests (Appium + XCUITest) -│ ├── Pages/ # Page Object Model -│ │ ├── __init__.py -│ │ ├── base_page.py # Base page class -│ │ ├── login_page.py # Login page -│ │ ├── home_page.py # Home page -│ │ ├── category_page.py # Category page -│ │ ├── search_page.py # Search page -│ │ ├── product_detail_page.py # Product detail -│ │ ├── cart_page.py # Cart page -│ │ └── order_page.py # Order page -│ ├── Tests/ # UI test cases -│ │ ├── __init__.py -│ │ ├── test_login.py # Login tests -│ │ ├── test_home.py # Home tests -│ │ ├── test_search.py # Search tests -│ │ ├── test_cart.py # Cart tests -│ │ └── test_order.py # Order flow tests -│ ├── __init__.py -│ └── conftest.py # UI fixtures -│ -├── API_Automation/ # API tests -│ ├── api/ # API wrappers -│ │ ├── __init__.py -│ │ ├── base_api.py # Base API class -│ │ ├── user_api.py # User API -│ │ ├── product_api.py # Product API -│ │ ├── cart_api.py # Cart API -│ │ └── order_api.py # Order API -│ ├── cases/ # API test cases -│ │ ├── __init__.py -│ │ ├── test_user.py # User tests -│ │ ├── test_product.py # Product tests -│ │ ├── test_cart.py # Cart tests -│ │ └── test_order.py # Order tests -│ └── data/ # Test data (YAML) -│ ├── user_data.yaml -│ ├── product_data.yaml -│ └── order_data.yaml -│ -├── Performance/ # Performance tests -│ └── locust_scripts/ -│ └── locustfile.py # Locust entry point -│ -├── CI/ # CI/CD config -│ ├── jenkins/ -│ │ └── Jenkinsfile # Jenkins pipeline -│ └── fastlane/ -│ └── Fastfile # Fastlane config -│ -├── Reports/ # Test report output (git-ignored) -│ └── webui-runs/ # Web UI 每次运行的独立报告目录 -│ └── {run_id}/ -│ ├── logs.txt # pytest 输出（已脱敏） -│ ├── allure-results/ # Allure 原始数据 -│ └── allure-report/ # Allure HTML 报告 -│ -├── tools/ # 工具目录 -│ └── webui/ # 本地 Demo 控制台 -│ ├── app.py # FastAPI 主入口 -│ ├── config.py # 配置（读取环境变量） -│ ├── models.py # Run 任务模型 -│ ├── .env.example # 配置模板 -│ ├── services/ -│ │ ├── ai_service.py # AI 问答（mock / Claude） -│ │ ├── allure_service.py # Allure 报告生成 -│ │ ├── env_service.py # 环境检查 -│ │ ├── file_service.py # 文件树/内容（白名单） -│ │ ├── run_service.py # 测试执行（subprocess） -│ │ └── sanitize.py # 日志脱敏 -│ └── static/ -│ └── index.html # Alpine.js 单页前端 -│ -└── docs/ # Documentation - ├── design.md # Design notes - └── platform-integration.md # TestPlatform integration notes +├── API_Automation/ +├── UI_Automation/ +├── Performance/ +├── config/ +├── utils/ +├── tools/webui/ +├── docs/ +├── CI/ +├── Reports/ +├── meteortest.yml +├── requirements.txt +├── pytest.ini +└── conftest.py ``` -| 目录 | 说明 | -|------|------| -| `config/` | 多环境配置，支持 dev / staging / prod | -| `utils/` | 日志、HTTP、断言、截图等公共工具 | -| `UI_Automation/` | Appium UI 自动化，Page Object 模式 | -| `API_Automation/` | 接口自动化，数据与用例分离 | -| `Performance/` | Locust 性能压测脚本 | -| `CI/` | GitHub Actions / Fastlane 配置 | -| `Reports/` | Allure 报告输出目录，webui-runs/ 存放 Web UI 运行记录 | -| `test-platform.yml` | 平台接入协议：声明项目、套件、命令、依赖和产物路径 | -| `tools/webui/` | 本地 Demo 控制台：代码浏览、测试执行、AI 问答 | -| `docs/platform-integration.md` | 与 TestPlatform / Local Agent 的职责边界和接入说明 | +By responsibility: ---- +- `API_Automation/`: API wrappers, test cases, and YAML test data. +- `UI_Automation/`: Appium UI automation using Page Object Model and XCUITest. +- `Performance/`: Locust performance test scripts. +- `config/`: environment configuration, local settings template, and global settings. +- `utils/`: logging, HTTP client, assertions, and screenshot utilities. +- `tools/webui/`: local demo console for browsing files, running tests, viewing logs, and opening reports. +- `docs/`: design notes and platform integration documentation. +- `CI/`: Jenkins and Fastlane examples. +- `Reports/`: generated reports and run artifacts; this directory is git-ignored. +- `meteortest.yml`: suite contract for MeteorTest or another Local Agent. -## 🚀 快速开始 +## Quick Start -### 环境要求 +### Requirements -- **Python**: 3.9+ -- **Node.js**: 18+ (Appium 2.x 需要) -- **Appium**: 2.x (`npm install -g appium && appium driver install xcuitest`) -- **Xcode**: 14+ (iOS 模拟器) +- Python 3.9+ +- Node.js 18+ for Appium 2.x +- Appium 2.x +- Xcode 14+ for iOS simulators +- Allure command line tool, optional but recommended for report generation -### 安装步骤 +Install Appium and the XCUITest driver: ```bash -# 1. 克隆项目 -git clone https://github.com/your-username/iOS-Automation-Framework.git +npm install -g appium +appium driver install xcuitest +``` + +### Install + +```bash +git clone https://github.com/JunchenMeteor/iOS-Automation-Framework.git cd iOS-Automation-Framework -# 2. 创建虚拟环境 python -m venv venv -source venv/bin/activate # macOS/Linux -# 或 venv\Scripts\activate # Windows +source venv/bin/activate -# 3. 安装依赖 pip install -r requirements.txt +cp config/local.yml.example config/local.yml +``` -# 4. 安装 Appium -npm install -g appium -appium driver install xcuitest +On Windows: -# 5. 配置本地环境 -cp config/local.yml.example config/local.yml -# 编辑 local.yml，填入你的设备名、App 路径和测试账号 +```powershell +python -m venv venv +.\venv\Scripts\activate +pip install -r requirements.txt +copy config\local.yml.example config\local.yml ``` -### 运行测试 +Edit `config/local.yml` with your device name, app path, and test account settings. + +### Run API Tests ```bash -# ====== 接口自动化测试（并发执行）====== pytest API_Automation/cases -v --alluredir=./Reports/api-results - -# 运行指定模块 pytest API_Automation/cases/test_user.py -v - -# 生成 Allure 报告 allure generate ./Reports/api-results -o ./Reports/api-report --clean allure open ./Reports/api-report +``` + +### Run iOS UI Tests + +Start Appium in a separate terminal: -# ====== UI 自动化测试（串行，需要真机/模拟器）====== -# 1. 启动 Appium Server（新终端） +```bash appium +``` -# 2. 运行 UI 测试（-n 0 覆盖 pytest.ini 的并发设置） +Run UI tests serially: + +```bash pytest UI_Automation/Tests -v -n 0 --alluredir=./Reports/ui-results +``` + +### Run Performance Tests -# ====== 性能测试 ====== +```bash cd Performance/locust_scripts locust -f locustfile.py --host=https://api-dev.yunlu.com ``` -### 平台接入执行 +## Platform Integration -通用平台或 Local Agent 应读取仓库根目录的 `test-platform.yml`，根据任务选择 suite 并执行其中的命令。 +A platform or Local Agent should read `meteortest.yml` at the repository root, select a suite from a task, and run the declared command. -示例： +Example: ```bash -# 平台任务 task_id=local-demo-001 时，API 全量套件可写入固定产物目录 python -m pytest API_Automation/cases -v --alluredir=Reports/platform/local-demo-001/allure-results - -# UI 套件由 Local Agent 负责准备 Appium、设备和 ipa/app 包路径 python -m pytest UI_Automation/Tests -v -n 0 --alluredir=Reports/platform/local-demo-001/allure-results ``` -平台触发的运行建议统一输出到： +Platform-triggered runs should write artifacts under: ```text Reports/platform/{task_id}/ @@ -245,205 +237,130 @@ Reports/platform/{task_id}/ └── screenshots/ ``` -被测 `.ipa` / `.app` 包应作为平台任务参数传入，例如 `app_path` 或 `app_url`。本仓库不负责构建 App，也不负责通用任务调度。 +The tested `.ipa` or `.app` should be passed by the platform task as `app_path` or `app_url`. This repository does not build the app and does not own general-purpose task scheduling. ---- +## Local Demo Console -## 🌐 本地 Demo 控制台 +The repository includes a local Web UI for debugging and demonstration. It is useful for browsing code, running whitelisted tests, viewing real-time logs, opening Allure reports, and trying project-aware AI Q&A. -内置本地 Web UI，无需命令行即可浏览代码、执行测试、查看实时日志和 Allure 报告。它只用于本仓库本地调试和演示，不是通用测试平台。 +It is not a general test platform and is not intended for production deployment. -### 启动 +Start it with: ```bash python -m uvicorn tools.webui.app:app --host 127.0.0.1 --port 8000 -# 访问 http://127.0.0.1:8000 ``` -### 配置 +Open: -复制配置模板并按需修改： +```text +http://127.0.0.1:8000 +``` + +Prepare local settings: ```bash cp tools/webui/.env.example tools/webui/.env ``` -关键配置项： +Important settings: -| 变量 | 默认值 | 说明 | -|------|--------|------| -| `AI_PROVIDER` | `mock` | `mock` 或 `claude`（需配合 `AI_API_KEY`） | -| `AI_MODEL` | `claude-sonnet-4-6` | AI 模型 ID，可替换为其他模型 | -| `AI_API_KEY` | 空 | Claude API Key，mock 模式下不需要 | -| `ALLURE_BIN` | `allure` | allure 命令路径 | -| `MAX_CONCURRENT_RUNS` | `1` | 最大并发任务数 | +| Variable | Default | Description | +|---|---|---| +| `AI_PROVIDER` | `mock` | `mock` or `claude` | +| `AI_MODEL` | `claude-sonnet-4-6` | AI model ID | +| `AI_API_KEY` | empty | Claude API key, not needed in mock mode | +| `ALLURE_BIN` | `allure` | Allure command path | +| `MAX_CONCURRENT_RUNS` | `1` | Maximum concurrent runs | -### 功能说明 +## Test Coverage -| 功能 | 说明 | -|------|------| -| 文件树浏览 | 只展示白名单文件，敏感文件不可访问 | -| 代码查看 | 只读，单文件最大 200KB | -| AI 问答 | 基于项目文件检索回答，mock 模式无需 API Key | -| 测试执行 | 固定模块白名单，不支持任意命令输入 | -| 实时日志 | SSE 推送，日志自动脱敏（token、密码等） | -| Allure 报告 | 每次运行独立目录，需安装 allure 命令 | -| 环境检查 | 自动检测 Python/pytest/Allure/Appium/Xcode 状态 | +Current sample coverage is organized around Yunlu Mall. -### 运行记录 +### UI Automation -每次执行测试会在 `Reports/webui-runs/{run_id}/` 生成： +| Module | Scope | Cases | +|---|---|---:| +| Login | phone login, verification code, password login | 15 | +| Home | banner, category navigation, recommended products | 12 | +| Category | category list, filtering, sorting, product cards | 10 | +| Product Detail | image preview, spec selection, add to cart | 18 | +| Cart | quantity update, delete, checkout | 14 | +| Order | submit order, payment, order list | 20 | +| **Total** | | **89** | -``` -{run_id}/ -├── logs.txt # pytest 完整输出（已脱敏） -├── allure-results/ # Allure 原始数据 -└── allure-report/ # Allure HTML 报告（需 allure 命令） -``` +### API Automation + +| Module | APIs | Cases | +|---|---:|---:| +| User | 8 | 32 | +| Product | 12 | 48 | +| Cart | 6 | 24 | +| Order | 10 | 40 | +| **Total** | **36** | **144** | + +## Implementation Notes + +### Why Page Object Model? -### 注意事项 - -- iOS UI 测试需要 **macOS + Xcode + Appium**，Windows/Linux 下 UI 模块自动禁用 -- Web UI 仅供本地单用户 Demo 使用，不适合生产部署 -- 通用 Local Agent 应放在 TestPlatform 侧，本仓库只暴露测试套件和执行命令 -- 接入真实 AI 需设置 `AI_PROVIDER=claude` 和 `AI_API_KEY` - -### 为什么选择 Page Object 模式？ - -**问题**：传统线性脚本的维护成本极高，UI 变更需要修改大量测试代码。 - -**方案**：Page Object 模式将每个页面抽象为一个对象： -- **元素定位**集中在 Page 类中 -- **业务操作**封装为 Page 方法 -- **测试用例**只关注业务流程，不关心元素细节 - -**优势**：UI 变更只需修改对应的 Page 类，不影响测试用例。 - -### 为什么选择 Appium + pytest？ - -| 维度 | 选择 | 理由 | -|------|------|------| -| UI 框架 | Appium | 跨平台、生态成熟、社区活跃 | -| 测试框架 | pytest | fixture 强大、参数化便捷、插件丰富 | -| 报告系统 | Allure | 可视化好、支持历史对比、便于分享 | -| 数据驱动 | YAML + parametrize | 数据与代码分离，非技术人员可维护 | - -### 如何保证测试稳定性？ - -1. **显式等待**：替代 `sleep()` 和隐式等待，使用 `WebDriverWait` 精确控制 -2. **多策略元素定位**：优先 Accessibility ID → XPath → Predicate → Class Chain -3. **重试机制**：`pytest-rerunfailures` 失败自动重试 -4. **失败截图**：每次失败自动截图 + 日志记录 -5. **数据隔离**：每条用例独立数据，避免状态污染 - ---- - -## 📊 测试覆盖范围 - -### UI 自动化（云鹿商城） - -| 模块 | 功能点 | 用例数 | -|------|--------|--------| -| 登录模块 | 手机号登录、验证码、密码登录 | 15 | -| 首页 | Banner 轮播、分类导航、推荐商品 | 12 | -| 分类 | 分类列表、筛选排序、商品卡片 | 10 | -| 商品详情 | 图片预览、规格选择、加入购物车 | 18 | -| 购物车 | 数量修改、删除、结算 | 14 | -| 订单 | 提交订单、支付、订单列表 | 20 | -| **合计** | | **89** | - -### 接口自动化 - -| 模块 | 接口数 | 用例数 | -|------|--------|--------| -| 用户模块 | 8 | 32 | -| 商品模块 | 12 | 48 | -| 购物车模块 | 6 | 24 | -| 订单模块 | 10 | 40 | -| **合计** | **36** | **144** | - ---- - -## 🔧 核心代码示例 - -### Page Object 示例 - -```python -# UI_Automation/Pages/login_page.py -class LoginPage(BasePage): - """云鹿商城 - 登录页""" - - # 元素定位 - _PHONE_INPUT = (MobileBy.ACCESSIBILITY_ID, "phone_input") - _CODE_INPUT = (MobileBy.ACCESSIBILITY_ID, "code_input") - _LOGIN_BTN = (MobileBy.ACCESSIBILITY_ID, "login_button") - _AGREE_CHECKBOX = (MobileBy.XPATH, "//XCUIElementTypeSwitch") - - def input_phone(self, phone: str): - """输入手机号""" - self.wait_and_input(self._PHONE_INPUT, phone) - return self - - def input_code(self, code: str): - """输入验证码""" - self.wait_and_input(self._CODE_INPUT, code) - return self - - def click_login(self): - """点击登录按钮""" - self.wait_and_click(self._LOGIN_BTN) - return HomePage(self.driver) - - def login(self, phone, code): - """完整登录流程""" - return (self.input_phone(phone) - .input_code(code) - .click_login()) +Page Object Model keeps UI locators and page operations in page classes, while test cases focus on business flow. When UI changes, the corresponding page class can be updated without rewriting every test case. + +### Why Appium + pytest? + +| Area | Choice | Reason | +|---|---|---| +| UI automation | Appium | mature ecosystem, XCUITest support, cross-platform option | +| Test framework | pytest | fixtures, parametrization, plugins | +| Reports | Allure | visual reports, trends, shareable artifacts | +| Data-driven testing | YAML + pytest parametrization | separates data from test logic | + +### Stability Practices + +- Prefer explicit waits over `sleep()`. +- Use multiple locator strategies: Accessibility ID, XPath, Predicate, and Class Chain. +- Retry flaky failures with `pytest-rerunfailures`. +- Capture screenshots and logs on failure. +- Keep test data isolated between cases. + +## Validation and CI + +Install dependencies: + +```bash +pip install -r requirements.txt ``` -### 数据驱动测试示例 - -```yaml -# API_Automation/data/user_data.yaml -login_cases: - - name: 正常手机号登录 - phone: "13800138000" - code: "123456" - expected_code: 0 - expected_msg: "success" - - - name: 错误的手机号格式 - phone: "123" - code: "123456" - expected_code: 1001 - expected_msg: "手机号格式错误" - - - name: 错误验证码 - phone: "13800138000" - code: "000000" - expected_code: 1002 - expected_msg: "验证码错误" +Run focused validation: + +```bash +python -m pytest API_Automation/cases -q +python -m pytest UI_Automation/Tests -q -n 0 +python -m pytest Performance -q ``` ---- +CI examples live under: +```text +.github/ +CI/ +``` -## 🤝 贡献指南 +## Roadmap -1. Fork 本仓库 -2. 创建特性分支 (`git checkout -b feature/amazing-feature`) -3. 提交更改 (`git commit -m 'Add amazing feature'`) -4. 推送到分支 (`git push origin feature/amazing-feature`) -5. 开启 Pull Request +```mermaid +flowchart LR + MVP[MVP
API / UI / performance suites] + Platform[Platform integration
meteortest.yml / Local Agent] + WebUI[Local demo console
logs / reports / AI Q&A] + Stable[Stability
fixtures / retry / device handling] ---- + MVP --> Platform --> WebUI --> Stable +``` -## 📄 License +## License MIT License © 2024 ---- - -## 👨‍💻 作者 +## Maintainer -iOS 开发工程师，关注工程质量与交付效率。本项目源于对移动端自动化测试体系的系统性思考——从 Page Object 设计、接口分层到 CI/CD 落地，记录完整的工程实践过程。 +Maintained by **Meteor**. This project records a practical mobile automation engineering workflow, from Page Object design and API layering to CI/CD and platform integration. diff --git a/README.zh-CN.md b/README.zh-CN.md new file mode 100644 index 0000000..613e2f9 --- /dev/null +++ b/README.zh-CN.md @@ -0,0 +1,366 @@ +# iOS-Automation-Framework + +

+ 面向 API、UI、性能、报告和平台接入的 iOS 自动化测试工程 +

+ +

+ Python + Appium + pytest + Allure +
+ Related MeteorTest + Issues + Roadmap +
+ Docs English + Docs 中文 +

+ +iOS-Automation-Framework 是一个面向云鹿商城 iOS App 的完整移动端自动化测试工程，覆盖 API 测试、iOS UI 测试、性能测试、Allure 报告、CI 配置和本地 Demo 控制台。 + +在更大的平台体系中，本仓库是测试代码载体和第一个接入样板。它负责“测试怎么写、怎么执行”：pytest/Appium 用例、Page Object、测试数据、断言和报告输出。像 [MeteorTest](https://github.com/JunchenMeteor/MeteorTest) 这样的通用平台负责调度、执行器状态、任务元数据和结果收集。 + +## 目录 + +- [背景](#背景) +- [核心能力](#核心能力) +- [执行闭环](#执行闭环) +- [技术架构](#技术架构) +- [项目结构](#项目结构) +- [快速开始](#快速开始) +- [平台接入](#平台接入) +- [本地 Demo 控制台](#本地-demo-控制台) +- [测试覆盖范围](#测试覆盖范围) +- [实现说明](#实现说明) +- [验证和 CI](#验证和-ci) +- [路线规划](#路线规划) +- [License](#license) +- [维护者](#维护者) + +## 背景 + +移动端自动化项目常常从简单脚本开始，但后续会逐渐难以维护： + +- UI 元素定位散落在测试用例中。 +- API、UI、性能测试使用不同约定。 +- 测试数据、环境配置和报告输出缺少标准化。 +- CI 可以执行测试，但本地调试和报告查看不够方便。 +- 中心化平台可以调度任务，但测试仓库仍需要清晰声明 suite 和执行命令。 + +这个项目把测试实现、本地 Demo 工具和平台接入元数据放在同一个仓库中，便于作为完整样板维护。 + +## 核心能力 + +- 面向 iOS UI 自动化的 Page Object Model。 +- 使用 YAML 数据和 pytest 参数化的数据驱动 API 测试。 +- 在同一个测试仓库中组织 API、UI 和性能测试套件。 +- 支持本地运行、CI 运行和平台触发运行的 Allure 报告输出。 +- 提供 GitHub Actions、Fastlane、Jenkins 配置示例。 +- 提供本地 Web UI，用于浏览代码、受控执行测试、查看实时日志、打开 Allure 报告和体验 AI 问答。 +- 通过 `meteortest.yml` 暴露平台接入协议。 + +## 执行闭环 + +```mermaid +flowchart LR + Contract[meteortest.yml
suite metadata] + Platform[MeteorTest / Local Agent
任务调度] + Pytest[pytest 执行
API / UI / Performance] + Reports[Reports
日志 / Allure / 截图] + Feedback[分析反馈
本地 UI / 平台报告] + + Contract --> Platform + Platform --> Pytest + Pytest --> Reports + Reports --> Feedback +``` + +## 技术架构 + +```mermaid +flowchart TB + Pytest[pytest 执行层] + + subgraph Suites[测试套件] + UI[UI_Automation
Appium + XCUITest] + API[API_Automation
requests + pytest] + Perf[Performance
Locust] + end + + subgraph Infra[基础设施] + Config[config
环境配置] + Utils[utils
日志 / HTTP / 断言 / 截图] + Reports[Reports
Allure 输出] + end + + subgraph Tooling[工具链] + CI[CI
GitHub Actions / Fastlane / Jenkins] + WebUI[本地 Demo 控制台
FastAPI + Alpine.js] + Contract[meteortest.yml
平台 suite 协议] + end + + Pytest --> UI + Pytest --> API + Pytest --> Perf + UI --> Infra + API --> Infra + Perf --> Infra + Infra --> CI + Infra --> WebUI + Contract --> Pytest + Pytest --> Reports +``` + +## 项目结构 + +```text +iOS-Automation-Framework/ +├── API_Automation/ +├── UI_Automation/ +├── Performance/ +├── config/ +├── utils/ +├── tools/webui/ +├── docs/ +├── CI/ +├── Reports/ +├── meteortest.yml +├── requirements.txt +├── pytest.ini +└── conftest.py +``` + +按职责看： + +- `API_Automation/`：API 封装、测试用例和 YAML 测试数据。 +- `UI_Automation/`：基于 Appium、XCUITest 和 Page Object Model 的 UI 自动化。 +- `Performance/`：Locust 性能测试脚本。 +- `config/`：环境配置、本地配置模板和全局设置。 +- `utils/`：日志、HTTP 客户端、断言和截图工具。 +- `tools/webui/`：本地 Demo 控制台，用于浏览文件、执行测试、查看日志和打开报告。 +- `docs/`：设计说明和平台接入文档。 +- `CI/`：Jenkins 和 Fastlane 示例。 +- `Reports/`：生成的报告和运行产物，已加入 git ignore。 +- `meteortest.yml`：MeteorTest 或其他 Local Agent 使用的 suite 协议。 + +## 快速开始 + +### 环境要求 + +- Python 3.9+ +- Node.js 18+，用于 Appium 2.x +- Appium 2.x +- Xcode 14+，用于 iOS 模拟器 +- Allure 命令行工具，可选但建议安装 + +安装 Appium 和 XCUITest driver： + +```bash +npm install -g appium +appium driver install xcuitest +``` + +### 安装 + +```bash +git clone https://github.com/JunchenMeteor/iOS-Automation-Framework.git +cd iOS-Automation-Framework + +python -m venv venv +source venv/bin/activate + +pip install -r requirements.txt +cp config/local.yml.example config/local.yml +``` + +Windows： + +```powershell +python -m venv venv +.\venv\Scripts\activate +pip install -r requirements.txt +copy config\local.yml.example config\local.yml +``` + +编辑 `config/local.yml`，填入设备名、App 路径和测试账号配置。 + +### 运行 API 测试 + +```bash +pytest API_Automation/cases -v --alluredir=./Reports/api-results +pytest API_Automation/cases/test_user.py -v +allure generate ./Reports/api-results -o ./Reports/api-report --clean +allure open ./Reports/api-report +``` + +### 运行 iOS UI 测试 + +在单独终端启动 Appium： + +```bash +appium +``` + +串行执行 UI 测试： + +```bash +pytest UI_Automation/Tests -v -n 0 --alluredir=./Reports/ui-results +``` + +### 运行性能测试 + +```bash +cd Performance/locust_scripts +locust -f locustfile.py --host=https://api-dev.yunlu.com +``` + +## 平台接入 + +平台或 Local Agent 应读取仓库根目录的 `meteortest.yml`，根据任务选择 suite，并执行声明的命令。 + +示例： + +```bash +python -m pytest API_Automation/cases -v --alluredir=Reports/platform/local-demo-001/allure-results +python -m pytest UI_Automation/Tests -v -n 0 --alluredir=Reports/platform/local-demo-001/allure-results +``` + +平台触发运行建议统一写入： + +```text +Reports/platform/{task_id}/ +├── logs.txt +├── allure-results/ +├── allure-report/ +└── screenshots/ +``` + +被测 `.ipa` 或 `.app` 应由平台任务以 `app_path` 或 `app_url` 传入。本仓库不负责构建 App，也不负责通用任务调度。 + +## 本地 Demo 控制台 + +仓库内置一个本地 Web UI，用于调试和演示。它可以浏览代码、执行白名单内测试、查看实时日志、打开 Allure 报告，并尝试项目上下文 AI 问答。 + +它不是通用测试平台，也不适合生产部署。 + +启动： + +```bash +python -m uvicorn tools.webui.app:app --host 127.0.0.1 --port 8000 +``` + +打开： + +```text +http://127.0.0.1:8000 +``` + +准备本地配置： + +```bash +cp tools/webui/.env.example tools/webui/.env +``` + +关键配置： + +| 变量 | 默认值 | 说明 | +|---|---|---| +| `AI_PROVIDER` | `mock` | `mock` 或 `claude` | +| `AI_MODEL` | `claude-sonnet-4-6` | AI 模型 ID | +| `AI_API_KEY` | 空 | Claude API Key，mock 模式不需要 | +| `ALLURE_BIN` | `allure` | Allure 命令路径 | +| `MAX_CONCURRENT_RUNS` | `1` | 最大并发任务数 | + +## 测试覆盖范围 + +当前样例覆盖围绕云鹿商城组织。 + +### UI 自动化 + +| 模块 | 范围 | 用例数 | +|---|---|---:| +| 登录 | 手机号登录、验证码、密码登录 | 15 | +| 首页 | Banner、分类导航、推荐商品 | 12 | +| 分类 | 分类列表、筛选排序、商品卡片 | 10 | +| 商品详情 | 图片预览、规格选择、加入购物车 | 18 | +| 购物车 | 数量修改、删除、结算 | 14 | +| 订单 | 提交订单、支付、订单列表 | 20 | +| **合计** | | **89** | + +### API 自动化 + +| 模块 | 接口数 | 用例数 | +|---|---:|---:| +| 用户 | 8 | 32 | +| 商品 | 12 | 48 | +| 购物车 | 6 | 24 | +| 订单 | 10 | 40 | +| **合计** | **36** | **144** | + +## 实现说明 + +### 为什么使用 Page Object Model？ + +Page Object Model 将 UI 元素定位和页面操作放在 Page 类中，让测试用例专注业务流程。UI 变更时通常只需要修改对应 Page 类，不需要重写大量测试用例。 + +### 为什么选择 Appium + pytest？ + +| 维度 | 选择 | 理由 | +|---|---|---| +| UI 自动化 | Appium | 生态成熟，支持 XCUITest，并保留跨平台可能性 | +| 测试框架 | pytest | fixture、参数化和插件能力完善 | +| 报告系统 | Allure | 可视化报告、趋势展示、便于分享 | +| 数据驱动 | YAML + pytest 参数化 | 测试数据和测试逻辑分离 | + +### 稳定性实践 + +- 优先使用显式等待，避免依赖 `sleep()`。 +- 使用多种元素定位策略：Accessibility ID、XPath、Predicate、Class Chain。 +- 使用 `pytest-rerunfailures` 对失败用例重试。 +- 失败时自动截图并记录日志。 +- 用例之间保持测试数据隔离。 + +## 验证和 CI + +安装依赖： + +```bash +pip install -r requirements.txt +``` + +运行聚焦验证： + +```bash +python -m pytest API_Automation/cases -q +python -m pytest UI_Automation/Tests -q -n 0 +python -m pytest Performance -q +``` + +CI 示例位于： + +```text +.github/ +CI/ +``` + +## 路线规划 + +```mermaid +flowchart LR + MVP[MVP
API / UI / 性能测试套件] + Platform[平台接入
meteortest.yml / Local Agent] + WebUI[本地 Demo 控制台
日志 / 报告 / AI 问答] + Stable[稳定性
fixtures / retry / 设备管理] + + MVP --> Platform --> WebUI --> Stable +``` + +## License + +MIT License © 2024 + +## 维护者 + +由 **Meteor** 维护。本项目记录一个移动端自动化测试工程实践，从 Page Object 设计、接口分层到 CI/CD 和平台接入。 diff --git a/docs/platform-integration.md b/docs/platform-integration.md index bb8b0f8..0c49079 100644 --- a/docs/platform-integration.md +++ b/docs/platform-integration.md @@ -1,4 +1,4 @@ -# Test Platform Integration +# MeteorTest Platform Integration This repository is a test project, not the test platform itself. @@ -12,7 +12,7 @@ This repository owns: - iOS UI automation tests under `UI_Automation/`. - Performance scripts under `Performance/`. - Test data, page objects, fixtures, and assertions. -- `test-platform.yml`, which describes executable suites and required capabilities. +- `meteortest.yml`, which describes executable suites and required capabilities. This repository does not own: @@ -26,15 +26,15 @@ This repository does not own: ## Execution Model ```text -TestPlatform +MeteorTest -> creates a task with project, suite, environment, and optional app artifact Local Agent - -> reads test-platform.yml + -> reads meteortest.yml -> downloads or locates the ipa/app artifact when needed -> runs the selected suite command -> collects logs, screenshots, and Allure results - -> uploads results back to TestPlatform + -> uploads results back to MeteorTest iOS-Automation-Framework -> contains the test code and produces test outputs diff --git a/test-platform.yml b/meteortest.yml similarity index 100% rename from test-platform.yml rename to meteortest.yml