# 跨端 E2E 测试 — 货运全流程

## 概述

`tests/cross_end/` 目录包含跨越多个端（管理端 Web + 司机安卓 APP）的端到端自动化测试，
验证从"发布货源"到"平台打款"的**完整业务闭环**。

```
  [管理端 Web]                    [司机安卓 APP]
       │                                │
  ① 发布货源 ──────────────────────────→│
       │                          ② 接单 │
       │                          ③ 装货 │
       │                          ④ 卸货 │
       │←────────────────────────────── │
  ⑤ 核算运单                            │
  ⑥ 核算审核                            │
  ⑦ 货主打款                            │
  ⑧ 平台打款给司机                      │
```

## 前置条件

### 管理端

```bash
# 1. 保存管理员登录态 (仅需一次)
python tests/web/admin/save_auth.py --role super_admin --browser chromium
```

### 司机安卓 APP

| 条件 | 说明 |
|---|---|
| Appium Server | 启动: `appium` (默认 http://localhost:4723) |
| Android 模拟器/真机 | 已启动并通过 `adb devices` 确认 |
| 司机 APP | 已安装，包名 `com.arpa.ynchenggangdriver` |
| 登录态 | 在设备上**手动登录一次** (后续 `noReset=true` 自动复用) |

### Python 依赖

```bash
pip install playwright appium-python-client
playwright install chromium
```

## 运行

```bash
# 运行跨端测试
pytest tests/cross_end/ -m cross_end -v -s

# 仅收集测试（不执行，验证 fixture 链正确）
pytest tests/cross_end/ --collect-only

# 排除跨端测试（常规运行不影响）
pytest tests/ -m "not cross_end"
```

## 测试文件结构

```
tests/cross_end/
├── conftest.py                           # 双 driver fixture (admin_page + app_driver)
├── pages/
│   ├── admin/
│   │   ├── freight_source_page.py        # 发布货源 Page Object
│   │   ├── waybill_management_page.py    # 运单核算 + 审核 Page Object
│   │   └── settlement_page.py           # 货主打款 + 平台打款 Page Object
│   └── app/
│       ├── driver_home_page.py           # 司机首页 (复用现有)
│       ├── driver_order_list_page.py     # 订单列表 + 接单 Page Object
│       └── driver_transport_page.py     # 装货 + 卸货 Page Object
├── tests/
│   └── test_freight_full_flow.py        # 主测试: 8 步全流程
└── README.md
```

## 选择器 `⚠️` 标记

所有新 Page Object 中的定位器 (CSS 选择器 / accessibility_id) 都标有 `# ⚠️`，
因为无法从代码静态分析中确定实际 DOM 结构或 APP 元素 ID。

**替换步骤：**

### Web 管理端选择器

1. 启动管理端并登录
2. 打开浏览器 DevTools (F12)
3. 逐个导航到对应页面（货源管理、运单管理、承运结算）
4. 检查每个表单输入框的 `placeholder`、按钮的 `text`、弹窗的 CSS class
5. 替换 Page Object 中对应的 `# ⚠️` 选择器

### APP 端 accessibility_id

1. 启动 Appium Desktop 并连接到设备
2. 使用 Inspector 功能捕获屏幕元素
3. 找到每个按钮/输入框的 `accessibility-id` 或 `resource-id`
4. 替换 Page Object 中对应的 `# ⚠️` 选择器

## 配置

所有环境配置从 `tests/config/test_config.yaml` 读取，跨端测试使用的 section:

| Section | 用途 |
|---|---|
| `admin` | 管理端 base_url, viewport, timeout, 登录态路径 |
| `driver_android` | Appium host, device_name, app_package, no_reset |
| `accounts.super_admin` | 管理员手机号/密码 |
| `accounts.driver` | 司机手机号/密码 |

不需要新增配置项。

## 故障排查

| 现象 | 可能原因 | 解决方案 |
|---|---|---|
| `pytest.skip: Playwright 未安装` | 环境缺少 playwright | `pip install playwright && playwright install chromium` |
| `pytest.skip: Appium-Python-Client 未安装` | 环境缺少 appium | `pip install appium-python-client` |
| 登录态已过期 | storage_state 过期 | `python tests/web/admin/save_auth.py --role super_admin` |
| APP 在登录页 | noReset 未生效或首次运行 | 在设备上手动登录一次 |
| 无法连接到 Appium server | Appium 未启动 | 终端执行 `appium` |
| AdbError / 设备未找到 | 模拟器未启动 | `adb devices` 确认设备在线 |
| 订单在 APP 中找不到 | 订单同步延迟 | 在 Page Object 中增加 retry 轮询逻辑 |
| `# ⚠️` 选择器错误 | 未更新实际选择器 | 按照上方步骤替换选择器 |

## 已知限制

- **仅 chromium**: 管理端不跑 browser matrix，固定使用 chromium
- **仅 Android**: APP 端目前固定为 `driver_android`，不跑 iOS
- **创建真实数据**: 测试会在环境中创建真实订单，需定期清理或使用测试环境
- **无 API 清理**: 测试失败后不会自动取消/删除订单，需手动处理
- **同时需要两个环境**: 管理端 + Appium + Android 设备必须同时可用，缺一则 skip