Paseo 移动端原生弹层与 Sheet 手势回归测试:基于 agent-device 的 Android 端到端方案

原创2026-09-20 18:16:101,357 阅读

Paseo 移动端原生弹层与 Sheet 手势回归测试:基于 agent-device 的 Android 端到端方案

本指南围绕 packages/app/e2e/mobile/modal-sheet/README.md 展开,完整讲解 Paseo 在 Android 上对原生弹层(Modal)与底部 Sheet 手势的端到端回归测试:包括紧凑布局下的插件弹层手势旅程、模型表单嵌套弹层旅程,以及平板宽屏下的模型选择弹层旅程。读完本文,你将掌握这四支 .ad 脚本的测试目标、运行前置条件(模拟器规格、隔离 daemon、插件安装、环境变量)与逐步骤手势断言细节,并了解它们为何独立于默认移动端测试套件之外运行。

测试背景:为什么 Sheet 手势需要原生端到端验证

Paseo 在移动端大量使用底部 Sheet 承载弹层内容,例如模型选择器、插件示例、工作区新建表单等。这类 UI 的核心交互不是"点按钮",而是手势:向下拖拽正文以关闭弹层、向上拖拽以展开、在展开后滚动长列表、横向切换 Tab。这些行为依赖 @gorhom/bottom-sheet 与 React Native 原生手势系统(见 adaptive-modal-sheet.tsx),JS 层单测无法覆盖真实触摸事件与动画时序,因此必须用真实设备/模拟器录制回放验证。

Paseo 的移动端 E2E 采用 agent-device 格式(.ad 脚本):Agent 先交互式探索出一条可用流程并保存为"逐字键入的计划",回放 runner 再在本地或 CI 上执行同一计划。相关工具链与套件约定见 mobile testing 文档。而本 README 描述的四支脚本因依赖已安装的示例插件与显式连接的 host,被排除在默认移动套件(npm run test:e2e:mobile)之外,需要按本指南手动驱动。

测试环境与前置准备

紧凑布局(Compact Sheet)环境

紧凑 Sheet 旅程使用 Android 模拟器,1080×1920,density 420,并加载当前 checkout 的 native app bundle(APP_ID=sh.paseo.debug,即 debug 开发客户端)。准备工作:

  1. 连接隔离 daemon:让 app 连接到一个隔离的 daemon(不与日常开发 daemon 混用),避免 host 连接状态干扰测试。
  2. 启用插件并安装示例:在 app 中启用 plugins,并在该 host 上安装 plugin-examples/modal-ui(示例插件,ID 为 modal-ui-example)。安装方式:paseo plugin install npm:@getpaseo/plugin-example-modal-ui@0.1.1,或在 host Settings → Plugins 粘贴同一 npm: 标识作为 Plugin source(详见 plugin-examples/modal-ui/README.md)。
  3. 设置 server ID:将 SHEET_QA_SERVER_ID 设为该 host 的 server ID,用于拼接深链。

示例插件通过 plugin.addSurface("main", ModalExamples) 注册了 main 表面与侧边栏/工作区入口(见 plugin-examples/modal-ui/index.client.tsx),因此可以用 paseo://h/<serverId>/plugin/modal-ui-example/surface/main 这类深链直达。

平板(Tablet)环境

平板旅程使用 1600×2560、density 320(即 800dp)的英文系统 Android 平板,同样需要当前 checkout 的 JavaScript 与已连接的隔离 daemon。如果使用 Pixel Tablet AVD,需显式旋转为竖屏——其自然横屏方向会把这款锁定竖屏的 app 信箱化(letterbox)进紧凑布局,从而测不到宽屏弹层:

adb -s "$ANDROID_SERIAL" shell settings put system accelerometer_rotation 0
adb -s "$ANDROID_SERIAL" shell settings put system user_rotation 1
adb -s "$ANDROID_SERIAL" shell wm density 320

三条命令分别:关闭自动旋转、强制旋转 90°(竖屏)、把屏幕密度设为 320dp。

紧凑 Sheet 手势旅程(gestures.android.ad)

在仓库根目录运行:

agent-device test packages/app/e2e/mobile/modal-sheet/gestures.android.ad \
  --env EXAMPLES_URL="paseo://h/${SHEET_QA_SERVER_ID}/plugin/modal-ui-example/surface/main" \
  --record-video --artifacts-dir .dev/sheet-qa/plugin

该脚本(gestures.android.ad,context platform=android timeout=120000 retries=0)按顺序覆盖以下断言组,手势坐标面向 1080×1920@420 模拟器:

  1. 正文拖拽关闭(body dismissal):打开 "Open ScrollView" 示例后,从坐标 (540, 980) 向下拖 820px(gesture pan 540 980 0 820 500),断言弹层关闭并回到入口(wait "label=\"Open ScrollView\"")。
  2. 重新打开与展开:再次打开 ScrollView,向上拖 600px 展开弹层,断言能看到 "Row 10";随后 scroll bottom 滚动到底部,断言 "Row 100" 可达,点选后关闭,断言选中回显 Selected: Row 100。这验证的是宿主(author-owned)ScrollView 在展开后可达最后一行。
  3. FlatList 同构验证:FlatList 同样支持正文拖拽关闭;重新打开后向上拖 750px 展开,点 Jump to last row 验证展开后的编程式滚动(ref 可用),再验证"列表已滚动时向下拖是滚动列表而非关闭弹层"(gesture pan 540 650 0 900 500 后仍断言 Close 可见)。
  4. 横向 Tab 手势:打开 "Open Horizontal" 示例,横向拖拽(gesture pan 960 980 -880 0 500)切换到 "System logs" Tab 并选中,验证宿主拥有的纵向 body 内,横向手势仍被正确路由到横向 Tab。

该旅程覆盖 README 中列举的:body dismissal、重新打开、展开与最后一行可达性(SDK ScrollView 与 FlatList)、展开后的编程式滚动、向下滚动列表、以及横向 Tab 选择。

模型表单嵌套弹层旅程(model.android.ad)

agent-device test packages/app/e2e/mobile/modal-sheet/model.android.ad \
  --env FORM_URL="paseo://new?serverId=${SHEET_QA_SERVER_ID}" \
  --record-video --artifacts-dir .dev/sheet-qa/model

脚本(model.android.ad)通过 paseo://new?serverId=... 深链打开 New workspace 表单,验证:

  • 打开 combined-model-selector(组合模型选择器),向下拖拽关闭,再重新打开;
  • 打开嵌套的模型浏览弹层(agent-controls-model),向下拖拽让嵌套弹层返回其父层而不选中任何模型、不提交 prompt;
  • 再次向下拖拽关闭恢复的父弹层,回到表单。

README 明确说明:该旅程不断言目录内容(不校验模型目录是否填充),只校验弹层的关闭/嵌套返回语义。

录制验证与基线回归结果

README 记录了该轮验证的实测结果(Android API 35、1080×1920@420、开发二进制 0.7.2 搭配当前 checkout 的 JavaScript,插件测试使用隔离 daemon):

项 结果
基线 dismissal 回归 failed at step 6: wait timed out for selector: label="Open ScrollView"(当前界面停留在 handle/Close/Row 1)
修复后 dismissal 回归 1 passed (6.47s)
完整插件手势旅程 1 passed (44.3s)
模型弹层关闭/重开旅程 1 passed (13.7s)
浏览器插件弹层旅程(plugin-modal-body.spec.ts) 1 passed (33.4s)
根目录 typecheck / lint / format passed

修复前后的正文拖拽录像存放于 evidence/android-before.mp4 与 evidence/android-after.mp4;browser.webm 覆盖宽屏与紧凑尺寸下既有的插件弹层旅程(对应 e2e/browser/plugin-modal-body.spec.ts)。

已知限制(如实记录):模型表单的目录在 debug app 中一直停留在 "Loading…",尽管隔离 daemon 的 provider API 已返回模型列表;因此只验证了该弹层的关闭/重开,未验证填充后的模型选择。iOS 与 Electron 均未在本轮验证中执行。这意味着本文描述的能力目前仅在 Android 上经过实测。

平板模型选择回归(model-tablet / model-tablet-agent)

两脚本均深入一个已填充的 provider、选择真实模型、断言触发器文本更新、重开并用 Android Back 关闭,且不提交 prompt(符合 docs/mobile-testing.md 中"新建工作区断言必须证明重定向完成"之外的宽松约定——这里只关心弹层行为)。

两脚本的分工

  • model-tablet.android.ad:练习 New workspace 弹层(popover)。宽屏下表单使用桌面风格的弹层容器(脚本中等待 id="combobox-desktop-container")。额外验证:超出短列表视口时,拖拽必须滚动列表而不是选中行或关闭弹层(gesture pan 1000 1850 0 -700 600 后仍停在 compact-model-list),随后 gesture fling down 甩回顶部,最后用 Android Back 关闭整个弹层且不改变已记住的选择(断言触发器仍为 Select model (${MODEL_LABEL}))。
  • model-tablet-agent.android.ad:练习宽设备上既有 agent 窄 composer 所用的 AdaptiveModalSheet。前提是侧边栏被固定(pinned),使 composer 保持窄布局;脚本打开 AGENT_URL 深链,等待 AGENT_TITLE 出现,选择模型后重开并 Back 关闭。

准备:通过 createAgent API 预置空闲 agent

平板旅程需要一个空闲 agent:通过 daemon 公开的 createAgent API 创建,配置真实 provider/model、无初始 prompt。创建后设置:

环境变量 含义
MODEL_QA_AGENT_ID 该空闲 agent 的 ID(用于 AGENT_URL 深链)
MODEL_QA_AGENT_TITLE agent 标题(用于路由加载断言)
MODEL_QA_METRO_PORT 当前 checkout 的 Metro 端口(传给 --metro-port)
MODEL_QA_MODEL_ID / MODEL_QA_MODEL_LABEL provider 第一页可见的真实模型:先记住该模型(手机布局在坏基线下可用),关闭选择器后再取;MODEL_LABEL 是展示名
MODEL_QA_LAST_MODEL_ID 初始在屏外的最后一个模型 ID;配合短溢出目录(本轮验证为 6 行)做基于坐标的 pan/fling 回归
SHEET_QA_SERVER_ID 连接的 host server ID
ANDROID_SERIAL 平板设备序列号

运行命令

agent-device test packages/app/e2e/mobile/modal-sheet/model-tablet.android.ad \
  packages/app/e2e/mobile/modal-sheet/model-tablet-agent.android.ad \
  --serial "$ANDROID_SERIAL" --metro-port "$MODEL_QA_METRO_PORT" \
  --env FORM_URL="paseo://new?serverId=${SHEET_QA_SERVER_ID}" \
  --env AGENT_URL="paseo://h/${SHEET_QA_SERVER_ID}/agent/${MODEL_QA_AGENT_ID}" \
  --env AGENT_TITLE="$MODEL_QA_AGENT_TITLE" \
  --env PROVIDER_ID=codex --env MODEL_ID="$MODEL_QA_MODEL_ID" \
  --env MODEL_LABEL="$MODEL_QA_MODEL_LABEL" --env LAST_MODEL_ID="$MODEL_QA_LAST_MODEL_ID" \
  --artifacts-dir /tmp/paseo-model-tablet-qa

注意脚本内部硬编码 env PROVIDER_ID=codex,因此 provider 选择器定位为 model-provider-codex、行定位为 model-row-codex-${MODEL_ID}。

运行纪律(README 明确要求)

  • 每次运行开始时不要有任何已打开的弹层:一次失败的 provider 点击会让弹层残留,需先关闭再跑下一轮;
  • 这些 host 相关旅程与紧凑 Sheet 旅程一样,留在默认移动套件之外;
  • 生成的截图、录像与运行日志存放在仓库之外(示例中 --artifacts-dir /tmp/paseo-model-tablet-qa),避免污染 checkout(与 docs/mobile-testing.md 中 Maestro 截图应输出到临时目录的约定一致)。

源码侧支撑:弹层是如何被手势驱动的

  • 自适应弹层容器:核心实现在 packages/app/src/components/adaptive-modal-sheet.tsx(共 742 行),组合 @gorhom/bottom-sheet 的 BottomSheetBackdrop、useBottomSheetInternal、IsolatedBottomSheetModal 与 GestureHandlerRootView,并通过 useIsolatedBottomSheetVisibility 管理显隐;布局辅助(可见内容高度、安全区 padding)在 adaptive-modal-sheet-layout 中。README 的 tablet 旅程正是用 AdaptiveModalSheet 承载窄 composer 的模型选择。
  • 插件弹层宿主:插件侧通过 @getpaseo/plugin/client/react-native 暴露 Modal、ScrollView、FlatList、copyText、useToast 等受控组件(见 plugin-examples/modal-ui/client/examples.tsx),示例生成 100 行列表(rows = Array.from({length: 100}, ...))与 5 个横向 Tab(Overview/Configuration/Activity/Permissions/System logs),与 gestures.android.ad 中的 Row 100、System logs 断言一一对应。宿主 ScrollView/FlatList 的 ref(Jump to last row)即 README 所说"展开后的编程式滚动"的底层对象。
  • 浏览器对照回归:同一示例插件还有浏览器侧回归 plugin-modal-body.spec.ts(在隔离 daemon 中安装本示例后,于 packages/app 下运行 npx playwright test e2e/browser/plugin-modal-body.spec.ts --project=browser --workers=1),用于宽屏/紧凑尺寸下的插件弹层对照,即 browser.webm 的录制来源。

收尾:何时使用这套方案

当改动涉及移动端底部 Sheet/弹层的手势语义(body 拖拽关闭、展开、嵌套弹层返回、宽屏 popover 滚动、横向 Tab 路由)时,应补充或重跑本文的四支脚本。它们无法进入默认套件的根本原因写得很清楚:需要已安装的示例插件与显式连接的 host。实操前请先阅读 mobile testing 文档 完成设备/agent-device 配置,并严格遵循"每次运行从无弹层状态开始、产物留在仓库外"两条纪律;若需复现"紧凑 Sheet 关闭回归",可直接对照 evidence/android-before.mp4 与 evidence/android-after.mp4 的差异。

登录后查看全文
paseo