Skip to content

[Documentation] Document implementation roadmap #32

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
JunchenMeteor merged 2 commits into from
May 12, 2026
Merged

[Documentation] Document implementation roadmap #32

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
3dd83e3
Document implementation roadmap
ConnorQi01 May 12, 2026
023b803
Document GitHub workflow rules
ConnorQi01 May 12, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
56 changes: 56 additions & 0 deletions AGENTS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -11,6 +11,62 @@ This repository is the companion test-code project for MeteorTest. It owns pytes
- Do not push directly to `main`; use a `dev/v-peq/<topic>` branch and open a PR against the mother repository.
- Prefer deterministic local validation before claiming behavior in public docs.

## GitHub Workflow Rules

Before creating a new work branch, sync the latest `main` first.

Branch names should use:

```text
dev/v-peq/<lowerCamelOrSnakeName>
```

When direct pushes to `main` are not allowed:

- Create a feature branch.
- Push the branch to the fork or writable remote.
- Create the issue and pull request in the upstream repository.
- Do not push directly to upstream `main`.

Issue and PR titles should start with one of the repository type prefixes below. Use the closest existing type instead of inventing a new prefix:

- `[Feature]` for new features, improvements, refactors, maintenance, and platform capability changes.
- `[Bug]` for defects and regressions.
- `[Test]` for test coverage, validation, fixtures, and CI test behavior.
- `[Documentation]` for README, architecture notes, setup guides, and agent instructions.
- `[Security]` for dependency or security hardening changes.
- `[Smoke test]` for smoke-test work.
- `[Known Issues]` for known issue tracking.

Use the same prefix family for the tracking issue and its PR when they describe the same work. If a change spans multiple areas, choose the dominant user-visible intent.

Add GitHub labels to issues according to the selected prefix when the authenticated account has permission:

- `[Feature]` issues must use `enhancement`.
- `[Bug]` issues must use `bug`.
- `[Test]` and `[Smoke test]` issues must use `test`.
- `[Documentation]` issues must use `documentation`.
- `[Security]` issues must use `security`.
- `[Known Issues]` issues must use `known issue`.

If label permission is missing, state that limitation in the handoff instead of silently claiming the rule was fully applied.

Issue and PR descriptions should use English. Use simple section headings such as `## Summary`, `## Proposed Changes`, and `## Test Plan`.

When an issue tracks the PR work, link it from the PR body with:

```text
Closes #<issue-number>
```

Place the `Closes #<issue-number>` line at the end of the PR description, after the test plan or validation section.

Do not add `Related PR: #<number>` to the issue body.

Use fresh GitHub data when checking issue or PR state. Prefer `gh api --cache 0s` or direct `gh api` calls before deciding whether an issue or PR already exists.

Do not add `Co-Authored-By` or AI attribution to commit messages.

## Synchronization Rule

When backend behavior, test behavior, interaction flow, environment variables, ports, commands, integration contracts, mock services, or capability/status claims change, update all affected surfaces in the same change:
Expand Down
160 changes: 160 additions & 0 deletions docs/implementation-roadmap.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,160 @@
# iOS-Automation-Framework Implementation Roadmap

本文合并并替代根目录临时草稿 `iOS-Automation-Framework-Optimization.md` 与 `iOS-Automation-Framework-WebUI.md`。它用于记录当前完成度、仍应保留的设计原则，以及近 / 中 / 远期实现方向。

## 当前结论

最新 `upstream/main` 已经完成原 Web UI 方案的大部分 MVP 内容：本地 FastAPI Web UI、文件浏览、环境检查、白名单测试执行、SSE 日志、Allure run 级报告、mock/Claude AI 问答、依赖声明、README 入口和 GitHub Actions API 测试都已经存在。

后续不应再按两份旧草稿从零实现 Web UI，而应把重点放在验证、补齐文档、降低运行风险、增强 AI 检索质量、完善 macOS UI 测试闭环和平台集成稳定性上。

## 已完成内容评估

| 原计划项 | 当前状态 | 证据 / 说明 |
|---|---|---|
| `pytest-xdist` 并发能力 | 已完成 | `requirements.txt` 包含 `pytest-xdist~=3.8.0`，`pytest.ini` 默认 `-n auto`。平台与 UI 命令使用 `-n 0` 保持稳定。 |
| Appium 2.x 明确化 | 已完成 | `requirements.txt` 注明 Appium 2.x，README 要求 Node.js 18+、Appium 2.x 和 XCUITest driver。 |
| 元素定位策略优化 | 部分完成 | Page Object 已大量使用 Accessibility ID、Predicate、Class Chain；但 README 仍提到 XPath，部分变量名仍为 `_XPATH` 但实际使用 Predicate，需要清理命名和文档。 |
| GitHub Actions API CI | 已完成基础版 | `.github/workflows/ci.yml` 会在 push / PR 运行 API 测试并上传 Allure/JUnit 结果；当前 `continue-on-error: true` 更像证据收集，不是严格质量门。 |
| 依赖版本明确 | 部分完成 | 多数依赖使用 `==` 或 `~=`；尚未引入 `pip-compile` 或锁文件。 |
| 一键启动脚本 | 已完成基础版 | `run_api.*` 和 `run_ui.*` 存在；但不支持参数化模块/环境，且 `run_ui.bat` 使用 `taskkill /f /im node.exe`，风险较高。 |
| Docker 支持 | 未完成 | 没有 `docker-compose.yml`。iOS UI 自动化依赖 macOS/Xcode，Docker 不适合作为完整 UI 执行方案。 |
| README 真实化 | 已完成基础版 | README 已覆盖结构、运行方式、Web UI、mock API、平台集成和限制；仍可继续补截图/GIF 和实测结果。 |
| Web UI 基础服务 | 已完成 | `tools/webui/app.py` 提供 FastAPI 入口、静态首页、健康检查和 API 路由。 |
| 文件树与安全读取 | 已完成基础版 | `file_service.py` 使用白名单、忽略目录、敏感文件/扩展名过滤和 200KB 限制。 |
| 环境检查 | 已完成基础版 | `env_service.py` 检查 Python、pytest、Allure、Appium、Xcode、API/UI 可运行性。 |
| 测试模块白名单 | 已完成 | `run_service.py` 固定 `api_all`、`api_smoke`、`api_regression`、`ui_all`、`ui_smoke`，不接受任意命令。 |
| 测试执行、日志、取消、超时 | 已完成基础版 | 使用 `asyncio.create_subprocess_exec`，SSE 推送日志，支持取消和超时。 |
| Allure run 级报告 | 已完成基础版 | 结果写入 `Reports/webui-runs/{run_id}`，避免覆盖固定目录。 |
| AI 问答 | 已完成基础版 | 支持 mock 答复和 Claude 可选接入；当前检索是关键词映射，不是完整索引。 |
| Web UI 前端 | 已完成基础版 | `tools/webui/static/index.html` 使用 Alpine.js，无前端构建链路。 |
| Windows API 验证 | 待持续执行 | 已具备 mock API 和 API smoke 路径；每次修改后仍应用本机命令重新验证。 |
| macOS UI 验证 | 未完成 | 需要 macOS + Xcode + Appium + iOS Simulator + `APP_PATH`。 |

## 保留的设计原则

以下原则仍然有效，后续实现应继续遵守：

- Web UI 是本地单用户 demo console，不是生产级测试平台。
- 前端只传模块 ID，后端只执行白名单命令。
- 不使用 `shell=True` 执行测试命令。
- iOS UI 测试默认串行执行，固定 `-n 0`，避免设备/模拟器冲突。
- Windows/Linux 可以开发 Web UI 和运行 API 测试，但 iOS UI 执行必须明确提示需要 macOS + Xcode + Appium。
- 报告使用 run 级目录 `Reports/webui-runs/{run_id}`，不能覆盖 `Reports/api-report` 或 `Reports/ui-report`。
- 不读取 `.env`、`config/local.yml`、证书、密钥、profile 等敏感文件。
- 日志输出必须脱敏 token、Authorization、password、api_key、secret 等字段。
- AI 回答必须基于项目上下文；上下文不足时说明不确定，并给出建议查看的文件。
- 不让 Web UI 自动安装 Xcode/Appium/Allure。
- 如果后续需要自动启动 Appium，只能关闭自己启动的进程，不能杀全部 `node.exe`。

## 近期目标

近期目标用于把已落地功能从“能跑”推进到“可验证、可维护、可演示”。

1. 补齐 Web UI 专属文档。
- 新增或完善 `tools/webui/README.md`。
- 说明启动命令、环境变量、mock AI、Claude 可选接入、报告目录、Windows/macOS 边界。

2. 固化 Windows API 验证流程。
- 使用 `tools.mock_api.server` 启动本地 mock API。
- 设置 `API_BASE_URL=http://127.0.0.1:8010`。
- 验证 `api_smoke` 在 CLI 和 Web UI 中都能执行并产生报告。
- 将实测命令和结果写入 README 或 Web UI README。

3. 修正 pytest timeout 配置。
- `pytest.ini` 已配置 `timeout`，但 `requirements.txt` 当前未显式包含 `pytest-timeout`。
- 二选一：加入 `pytest-timeout`，或移除无效配置并改由 Web UI 超时控制负责。

4. 清理 UI locator 命名和文档。
- 将实际使用 Predicate 的 `_XPATH` 变量改名为 `_PREDICATE` 或 `_FALLBACK`。
- README 中“XPath”改为“XPath 仅作为最后兜底”，与当前实现一致。
- 保留定位优先级：Accessibility ID > Predicate > Class Chain > XPath。

5. 降低一键 UI 脚本风险。
- 避免 `run_ui.bat` 中 `taskkill /f /im node.exe` 杀掉所有 Node 进程。
- 改成记录自己启动的 Appium 进程并只关闭该进程，或要求用户手动启动 Appium。

6. 调整 CI 质量门策略。
- 明确 `.github/workflows/ci.yml` 中 `continue-on-error: true` 是证据收集还是临时容错。
- 如果目标是 PR 质量门，应让 API smoke 失败时阻断合并。

7. 补充 Web UI 基础测试。
- 覆盖文件白名单、敏感路径拒绝、模块白名单、日志脱敏、run metadata 恢复。
- 优先用 pytest 测服务层，不急于做浏览器自动化。

## 中期目标

中期目标用于增强 Web UI 和平台集成能力，但仍保持本地 demo 的边界。

1. 增强 AI 检索。
- 从关键词映射升级为轻量分块检索。
- 回答引用文件路径，最好能定位到行号。
- 支持对 README、pytest.ini、Page Object、API case、config 的优先检索。

2. 完善任务运行模型。
- 区分“测试失败”和“Allure 报告生成失败”。
- 记录 report generation 状态和错误信息。
- 为取消任务补齐子进程组处理，避免 Windows/macOS 行为不一致。

3. 增强 Web UI 交互。
- 日志自动滚动可暂停。
- 历史 run 更清晰地展示状态、耗时、模块和报告链接。
- 环境不满足时提供明确的修复建议，而不仅是禁用按钮。

4. 与 `meteortest.yml` 保持一致。
- Web UI 模块和 `meteortest.yml` suite 不应长期分叉。
- 后续可从 `meteortest.yml` 读取安全 suite 列表，再附加 Web UI 运行约束。

5. macOS UI 测试验证。
- 在 macOS 上验证 `ui_smoke`。
- 检查 Xcode、simctl、Appium Server、XCUITest driver、`APP_PATH` 的真实状态。
- 把 macOS 验证步骤写入 README 和 Web UI README。

6. 依赖锁定策略。
- 如果项目需要可重复安装，评估 `pip-tools`。
- 生成并维护 `requirements.lock.txt` 或等价锁文件。

## 远期目标

远期目标只有在本地 demo 稳定后再推进，避免过早扩大复杂度。

1. 运行趋势和历史分析。
- 基于 `Reports/webui-runs` 汇总通过率、失败模块、耗时和 flaky 倾向。
- 保留最近 N 次运行并提供清理策略。

2. 更完整的 AI 助手。
- 建立文件索引或符号索引。
- 支持基于失败日志、Allure 结果、测试代码的失败分析。
- 生成建议时明确引用证据，不编造项目状态。

3. 性能测试入口。
- 第一阶段只展示 Locust 目录和文档。
- 后续如加入 `perf_locust_headless`，必须固定参数、默认小流量、明确风险，不能让前端传任意压测目标和并发。

4. Docker / Dev Container。
- Docker 可以用于 API 测试、mock API、Web UI 的开发环境。
- 不应承诺 Docker 能完整运行 iOS UI 自动化，因为 Xcode 和 iOS Simulator 依赖 macOS。

5. 多用户和远程执行。
- 当前 Web UI 不做多用户权限、云端设备池或分布式队列。
- 如果未来需要，应优先由 MeteorTest 平台承担调度、权限、审计和执行器管理，而不是把本仓库 Web UI 扩展成生产平台。

## 不再保留的旧表述

以下旧草稿内容不应继续作为真实状态引用：

- “Web UI 待从零实现”的描述：当前 `tools/webui` 已存在。
- “当前最新提交为 a0175e6”的描述：这是旧扫描结果，不能作为当前仓库状态。
- “步骤 1-16 全部完成”的笼统表述：应拆成本文的具体完成度表，避免掩盖验证缺口。
- “添加 docker-compose 一条命令启动 Appium + 测试环境”的完整承诺：iOS UI 自动化不能被 Docker 一条命令完整覆盖。
- “补充真实截图/GIF 演示”作为高优先级实现项：可以作为文档增强，但不应优先于验证和安全边界。

## 推荐下一步

优先做近期目标 1 到 3：

1. 补 `tools/webui/README.md`。
2. 跑通 Windows mock API + Web UI `api_smoke` 实测并记录。
3. 处理 `pytest-timeout` 配置与依赖不一致。

这三项能把当前已实现的 Web UI 从代码状态推进到可复现演示状态，收益最高，风险最低。
Loading