# suixinkan UI Tests

本目录包含 App 的 XCUITest 回归套件，通过 **api-test 真实接口** 验证页面可达性与关键业务流程。

## 约束

- 测试代码仅位于 `suixinkanUITests/`，App 侧仅扩展 `suixinkan/App/` 基础设施（如 `AppUITestLaunchState`）。
- **不修改** `Features/`、`Core/` 业务代码，不在 App 内注入 Mock 网络。
- DEBUG 构建下通过「我的 → 首页调试」批量覆盖首页路由。

## 环境变量

在 Scheme **Environment Variables** 或 `xcodebuild` 中配置：

| 变量 | 必填 | 说明 |
| --- | --- | --- |
| `SUI_TEST_PHONE` | 是 | 登录手机号 |
| `SUI_TEST_PASSWORD` | 是 | 登录密码 |
| `SUI_TEST_ACCOUNT_NAME` | 否 | 多账号选择页要点的账号展示名 |

**本机快捷配置（推荐）：** 在 `suixinkanUITests/UITestCredentials.local.plist` 中配置 `SUI_TEST_PHONE`、`SUI_TEST_PASSWORD` 和可选的 `SUI_TEST_ACCOUNT_NAME`。该文件已加入 `.gitignore`，不会提交到 Git。环境变量优先级高于本地 plist。

缺少账号时，需要登录的用例会自动 `XCTSkip`。

已登录用例通过 `UITestSession` 全套件共享一次登录；每条首页路由会注册为独立 `testHomeRoute_<菜单名>` 用例，并通过 `-suixinkan-ui-tests-open-menu` 直达目标页。`LoginSmokeUITests` 会清空本地状态并使共享会话失效。

## 测试数据约定（api-test）

以下数据建议为 UI Test 专用账号预置，否则部分「列表 → 详情」用例会跳过：

- 至少 1 条门店订单、1 条核销订单
- 至少 1 条任务、项目、打卡点、押金订单（可选）
- 账号需有景区/门店上下文

## 运行命令

```bash
# 仅跑 UI Tests（需先配置环境变量）
xcodebuild test \
  -workspace suixinkan.xcworkspace \
  -scheme suixinkan \
  -destination 'platform=iOS Simulator,name=iPhone 17' \
  -only-testing:suixinkanUITests

# 带环境变量示例
SUI_TEST_PHONE=13800138000 \
SUI_TEST_PASSWORD='your-password' \
xcodebuild test \
  -workspace suixinkan.xcworkspace \
  -scheme suixinkan \
  -destination 'platform=iOS Simulator,name=iPhone 17' \
  -only-testing:suixinkanUITests
```

## 启动参数

UI Test 进程会自动传入：

- `-suixinkan-ui-tests`：主开关，App 侧跳过推送注册与排队 WebSocket
- `-suixinkan-ui-tests-reset-state`：冷启动清理 Keychain / UserDefaults
- `-suixinkan-ui-tests-open-menu <菜单标题>`：登录后直达首页调试目录中的页面
- `-suixinkan-ui-tests-open-profile <路由名>`：登录后直达个人中心二级页（如 `settings`）

## 目录结构

```
suixinkanUITests/
  Support/          # 启动配置、登录、导航、断言
  Auth/             # 登录冒烟与完整登录流
  Shell/            # 主 Tab
  Home/             # 首页调试菜单全路由
  Profile/          # 我的二级页
  Orders/           # 订单深层流
  Modules/          # 各业务模块交互
```

## 降级 / 跳过项

以下场景在模拟器 UI Test 中仅验证「可打开 / 可关闭」，不做完整硬件或上传闭环：

- 真机摄像头扫码内容识别
- 直播推流预览与音视频专项
- 高德地图完整选点
- OSS 真实文件上传（可选只验证选图 Sheet）

## 新增页面时

1. 在 `Support/UITestHomeMenuCatalog.swift` 补充调试菜单覆盖项（如有首页入口）。
2. 在对应 `Modules/*UITests.swift` 增加关键交互用例。
3. 优先使用已有 `accessibilityIdentifier`、导航栏标题和稳定文案定位，不修改 Features 视图。