q792602257
78ce788e2f
Tests / Test passed: 624
Archives the completed android-driver change (16/16 tasks). Promotes the driver_type="uiautomator2" scenario into the canonical driver-registry spec and moves the change artifacts to openspec/changes/archive/2026-07-13-android-driver/.
4.1 KiB
4.1 KiB
Why
docs/MACOS_IPHONE_SETUP.md 明确记录了当前的架构缺口："当前仓库只内置了 wda Driver……Android 只是架构上的未来目标，当前 driver/registry.py 没有注册 Android Driver，因此仅安装 Android SDK/ADB 还不能让本项目控制 Android 手机。" Hexagonal + DDD 分层治理架构（driver 层的 Driver Registry 扩展点模式）从一开始就是为了让新增一个设备平台只需要在 driver/ 包内添加代码，driver/wda_driver.py 已经把这条路径验证了一遍。现在补上 Android 驱动是把这个既定扩展点落地到第二个真实平台，不是新设计。
What Changes
- 新增
driver/android_driver.py：AndroidDriverConfig（dataclass）+AndroidDriver(Driver)，通过 Appium Python Client 的 UiAutomator2 driver 连接 Android 设备（真机或模拟器均可，Appium/adb 本身对两者透明），实现driver/base.py::Driver抽象基类的全部方法（connect/disconnect/screenshot/tap/swipe/input/launch/terminate/tree/home/lock/unlock）。 driver/registry.py：新增build_android_driver_factory，注册到SUPPORTED_DRIVER_TYPES["uiautomator2"]（key 用自动化后端名而非平台名，与现有"wda"的命名惯例对称）。- 新增
AndroidDriver的 mock 单元测试（mockappium.webdriver.Remote），覆盖连接失败、未连接时调用、各操作异常包装为DriverError/DeviceOfflineError的路径——这是比WDADriver现有测试覆盖更完整的增量，WDADriver目前只有一个真机门控的集成测试。 - 新增
tests/test_android_integration.py：结构镜像tests/test_wda_integration.py，@pytest.mark.integration门控，依赖APEX_ANDROID_SERVER_URL/APEX_ANDROID_UDID/APEX_ANDROID_DEVICE_NAME环境变量，无真机环境时 skip。 - 订正
docs/MACOS_IPHONE_SETUP.md第 1 节中"Android 未注册"的过时表述，改为准确描述 Android 驱动已注册、真机安装手册留待后续变更（不在本次新增）。 - 不引入新依赖：根
pyproject.toml已声明Appium-Python-Client>=5.1.1，.venv已安装appium.options.android.uiautomator2。
Capabilities
New Capabilities
(无。沿用现有惯例：单个驱动实现的具体行为不单独建 spec capability——driver/wda_driver.py 落地时也没有为它建一个 wda-driver spec，openspec/specs/ 里只有 driver-registry 这一个与驱动相关的 capability，负责 registry 机制本身。为 Android 单独建一个对称的 capability 会与既有惯例不一致。)
Modified Capabilities
driver-registry：为"Building a factory for a known driver type"这条既有 Requirement 补一个driver_type="uiautomator2"的 Scenario，与既有driver_type="wda"的示例场景对称，证明这条已声明为 driver_type 无关的机制对第二个真实驱动类型同样成立。不新增强约束，只是示例覆盖的完整性。
Impact
- 新增代码：
driver/android_driver.py；tests/test_android_integration.py；新增覆盖AndroidDriver的 mock 单元测试文件。 - 修改代码：
driver/registry.py（新增一个注册项，纯增量，不改动现有"wda"行为）；docs/MACOS_IPHONE_SETUP.md（订正第 1 节一句过时表述）。 - 依赖：无新增，复用已声明的
Appium-Python-Client。 - 不涉及：
api/、device/、tools/、runtime/任一层——已用 grep 核实这些层当前不含任何"wda"字面量硬编码，driver-registry既有 Requirement（"Adding a driver type requires no changes outside the driver layer"）保证新增驱动类型无需改动这些层。 - Non-Goals（本次明确不做）：不新增
docs/ANDROID_SETUP.md或同等深度的 Android SDK/adb 真机安装手册（用户已确认，留到驱动落地、有真机可验证后再开后续变更）；不支持 Appium 的 Espresso driver（与 WDA 只做 XCUITest、不支持其他 iOS 后端对称）；不做APEX_WDA_*→DEVICE_RUNTIME_WDA_*环境变量重命名（文档中记录的独立遗留事项，与本次无关）。