diff --git a/.gitignore b/.gitignore
index fbf1cef..b22ab4a 100644
--- a/.gitignore
+++ b/.gitignore
@@ -20,6 +20,7 @@ Reports/allure-results/
Reports/allure-report/
Reports/api-results/
Reports/ui-results/
+Reports/platform/
Reports/logs/
UI_Automation/screenshots/
*.log
@@ -58,7 +59,12 @@ allure-results-history/
config/local.yml
# ==================== Web UI 运行产物 ====================
+Reports/webui-runs/
Reports/webui-runs/*/logs.txt
Reports/webui-runs/*/allure-results/
Reports/webui-runs/*/allure-report/
tools/webui/.env
+
+# ==================== Local Playwright probes ====================
+recon.py
+test_basic.py
diff --git a/README.md b/README.md
index d26ec4c..e7c006c 100644
--- a/README.md
+++ b/README.md
@@ -10,7 +10,11 @@
## 📋 项目简介
-本项目是一个完整的 **iOS 移动端自动化测试框架**，以**云鹿商城 App** 为测试对象，实现了 **UI 自动化测试**、**接口自动化测试**、**性能测试** 三位一体的测试解决方案，并内置 **Web 控制台**，支持在浏览器中浏览代码、执行测试、查看实时日志和 Allure 报告。
+本项目是一个完整的 **iOS 移动端自动化测试工程**，以**云鹿商城 App** 为测试对象，实现了 **UI 自动化测试**、**接口自动化测试**、**性能测试** 三位一体的测试解决方案。
+
+它在通用测试平台体系中的定位是：**测试代码载体和第一个接入样板**。本仓库负责“怎么测”，例如 pytest/Appium 用例、Page Object、测试数据、断言和报告输出；通用平台和 Local Agent 负责“谁来调度、在哪里执行、如何回传结果”。
+
+内置的 `tools/webui` 仅作为单项目本地 Demo 控制台，用于浏览代码、执行测试、查看实时日志和 Allure 报告，不承担平台中心或通用 Agent 职责。
### 核心特性
@@ -22,7 +26,8 @@
| 📈 **Allure 报告** | 可视化测试报告，支持历史趋势 |
| 🔄 **GitHub Actions CI** | 自动化流水线，PR 触发执行 |
| ⚡ **性能测试** | 基于 Locust 的压力测试脚本 |
-| 🌐 **Web 控制台** | 本地 Web UI，支持代码浏览、测试执行、AI 问答 |
+| 🌐 **本地 Demo 控制台** | 本地 Web UI，支持代码浏览、测试执行、AI 问答 |
+| 🔗 **平台接入协议** | 通过 `test-platform.yml` 描述套件、命令、依赖和产物路径 |
---
@@ -37,7 +42,7 @@ graph TD
B & C & D --> E[🛠️ 基础设施层
Config / Logger / Utils]
E --> F[🚀 CI/CD 层
GitHub Actions / Fastlane]
- E --> G[🌐 Web 控制台
FastAPI + Alpine.js]
+ E --> G[🌐 本地 Demo 控制台
FastAPI + Alpine.js]
```
---
@@ -47,6 +52,7 @@ graph TD
```
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
@@ -122,7 +128,7 @@ iOS-Automation-Framework/
│ └── allure-report/ # Allure HTML 报告
│
├── tools/ # 工具目录
-│ └── webui/ # Web 控制台
+│ └── webui/ # 本地 Demo 控制台
│ ├── app.py # FastAPI 主入口
│ ├── config.py # 配置（读取环境变量）
│ ├── models.py # Run 任务模型
@@ -138,7 +144,8 @@ iOS-Automation-Framework/
│ └── index.html # Alpine.js 单页前端
│
└── docs/ # Documentation
- └── design.md # Design notes
+ ├── design.md # Design notes
+ └── platform-integration.md # TestPlatform integration notes
```
| 目录 | 说明 |
@@ -150,7 +157,9 @@ iOS-Automation-Framework/
| `Performance/` | Locust 性能压测脚本 |
| `CI/` | GitHub Actions / Fastlane 配置 |
| `Reports/` | Allure 报告输出目录，webui-runs/ 存放 Web UI 运行记录 |
-| `tools/webui/` | Web 控制台：代码浏览、测试执行、AI 问答 |
+| `test-platform.yml` | 平台接入协议：声明项目、套件、命令、依赖和产物路径 |
+| `tools/webui/` | 本地 Demo 控制台：代码浏览、测试执行、AI 问答 |
+| `docs/platform-integration.md` | 与 TestPlatform / Local Agent 的职责边界和接入说明 |
---
@@ -212,11 +221,37 @@ cd Performance/locust_scripts
locust -f locustfile.py --host=https://api-dev.yunlu.com
```
+### 平台接入执行
+
+通用平台或 Local Agent 应读取仓库根目录的 `test-platform.yml`，根据任务选择 suite 并执行其中的命令。
+
+示例：
+
+```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
+```
+
+平台触发的运行建议统一输出到：
+
+```text
+Reports/platform/{task_id}/
+├── logs.txt
+├── allure-results/
+├── allure-report/
+└── screenshots/
+```
+
+被测 `.ipa` / `.app` 包应作为平台任务参数传入，例如 `app_path` 或 `app_url`。本仓库不负责构建 App，也不负责通用任务调度。
+
---
-## 🌐 Web 控制台
+## 🌐 本地 Demo 控制台
-内置本地 Web UI，无需命令行即可浏览代码、执行测试、查看实时日志和 Allure 报告。
+内置本地 Web UI，无需命令行即可浏览代码、执行测试、查看实时日志和 Allure 报告。它只用于本仓库本地调试和演示，不是通用测试平台。
### 启动
@@ -270,6 +305,7 @@ cp tools/webui/.env.example tools/webui/.env
- iOS UI 测试需要 **macOS + Xcode + Appium**，Windows/Linux 下 UI 模块自动禁用
- Web UI 仅供本地单用户 Demo 使用，不适合生产部署
+- 通用 Local Agent 应放在 TestPlatform 侧，本仓库只暴露测试套件和执行命令
- 接入真实 AI 需设置 `AI_PROVIDER=claude` 和 `AI_API_KEY`
### 为什么选择 Page Object 模式？
diff --git a/docs/platform-integration.md b/docs/platform-integration.md
new file mode 100644
index 0000000..bb8b0f8
--- /dev/null
+++ b/docs/platform-integration.md
@@ -0,0 +1,64 @@
+# Test Platform Integration
+
+This repository is a test project, not the test platform itself.
+
+It provides the automation code and suite metadata that a platform-side Local Agent can execute. The platform is responsible for task creation, scheduling, executor management, report indexing, and AI analysis.
+
+## Responsibilities
+
+This repository owns:
+
+- API automation tests under `API_Automation/`.
+- 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.
+
+This repository does not own:
+
+- Multi-project management.
+- Platform authentication or authorization.
+- Platform database tables.
+- Generic task scheduling.
+- Generic Local Agent implementation.
+- Long-term executor lifecycle management.
+
+## Execution Model
+
+```text
+TestPlatform
+ -> creates a task with project, suite, environment, and optional app artifact
+
+Local Agent
+ -> reads test-platform.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
+
+iOS-Automation-Framework
+ -> contains the test code and produces test outputs
+```
+
+## App Artifacts
+
+UI suites can test an app package passed by the platform as:
+
+- `app_path`: local `.ipa` or `.app` path.
+- `app_url`: remote artifact URL downloaded by the Local Agent.
+
+The test code should read the final local app path from local configuration or environment variables prepared by the Local Agent.
+
+## Output Convention
+
+Platform-triggered runs should write outputs under:
+
+```text
+Reports/platform/{task_id}/
+├── logs.txt
+├── allure-results/
+├── allure-report/
+└── screenshots/
+```
+
+The Local Agent owns log capture and upload. This repository only needs to make sure suite commands can write deterministic report paths.
diff --git a/test-platform.yml b/test-platform.yml
new file mode 100644
index 0000000..99d9973
--- /dev/null
+++ b/test-platform.yml
@@ -0,0 +1,100 @@
+schema_version: 1
+
+project:
+ key: yunlu-ios
+ name: Yunlu iOS automation tests
+ description: API, iOS UI, and performance automation suites for Yunlu Mall.
+ type: mobile_app_tests
+
+repository:
+ role: test_repository
+ framework:
+ - pytest
+ - appium
+ - locust
+ - allure
+ platform:
+ - ios
+
+artifacts:
+ default_root: Reports/platform
+ allure_results: Reports/platform/{task_id}/allure-results
+ allure_report: Reports/platform/{task_id}/allure-report
+ logs: Reports/platform/{task_id}/logs.txt
+ screenshots: Reports/platform/{task_id}/screenshots
+
+parameters:
+ app_path:
+ description: Local ipa/app path or downloaded artifact path used by UI suites.
+ required: false
+ app_url:
+ description: Remote ipa/app artifact URL. The Local Agent should download it before running UI suites.
+ required: false
+ environment:
+ description: Target test environment, such as dev, staging, or prod.
+ required: true
+ default: staging
+
+suites:
+ - id: api_smoke
+ name: API smoke tests
+ type: api
+ command: python -m pytest API_Automation/cases -v -m smoke --alluredir=Reports/platform/{task_id}/allure-results
+ report:
+ allure: true
+ outputs:
+ allure_results: Reports/platform/{task_id}/allure-results
+
+ - id: api_all
+ name: API full regression
+ type: api
+ command: python -m pytest API_Automation/cases -v --alluredir=Reports/platform/{task_id}/allure-results
+ report:
+ allure: true
+ outputs:
+ allure_results: Reports/platform/{task_id}/allure-results
+
+ - id: ios_ui_smoke
+ name: iOS UI smoke tests
+ type: ui
+ command: python -m pytest UI_Automation/Tests -v -n 0 -m smoke --alluredir=Reports/platform/{task_id}/allure-results
+ requires:
+ - macos
+ - xcode
+ - appium
+ - ios_device_or_simulator
+ accepts_artifact:
+ - ipa
+ - app
+ report:
+ allure: true
+ outputs:
+ allure_results: Reports/platform/{task_id}/allure-results
+ screenshots: Reports/platform/{task_id}/screenshots
+
+ - id: ios_ui_all
+ name: iOS UI full regression
+ type: ui
+ command: python -m pytest UI_Automation/Tests -v -n 0 --alluredir=Reports/platform/{task_id}/allure-results
+ requires:
+ - macos
+ - xcode
+ - appium
+ - ios_device_or_simulator
+ accepts_artifact:
+ - ipa
+ - app
+ report:
+ allure: true
+ outputs:
+ allure_results: Reports/platform/{task_id}/allure-results
+ screenshots: Reports/platform/{task_id}/screenshots
+
+ - id: performance_all
+ name: Performance tests
+ type: performance
+ command: locust -f Performance/locust_scripts/locustfile.py --headless
+ requires:
+ - network
+ report:
+ allure: false