weapp-devtools-e2e-best-practices

weapp-devtools-e2e-best-practices

用途

WeChat DevTools のランタイム E2E の記述方法と検証順序を統一し、automator の重複起動、脆弱なナビゲーション、不安定な IDE 自動化を避けます。

いつ使うか

• ユーザーが e2e/ide/** を追加または変更する場合。
• ユーザーが miniprogram-automator で実際のランタイムをアサートする場合。
• ユーザーが launchAutomator をどう再利用すればよいか尋ねる場合。
• ユーザーが miniProgram.reLaunch(...) を使うべきか尋ねる場合。
• ユーザーが E2E を screenshot / compare / logs と連携させて受け入れフローを構築する場合。
• ユーザーが MCP の weapp_devtools_* / weapp_runtime_* ツールで実際のランタイムページを確認する場合。
• ユーザーが同じ provider-compatible なシナリオを devtools と headless で実行する場合、または両者の観測可能な差異を修正する場合。

適用しない場面

このスキルは DevTools ランタイム E2E に焦点を当てています。

• CLI の設計とコマンドの振り分け：weapp-vite-best-practices を使用します。
• ビルド設定：weapp-vite-best-practices を使用します。
• wevu のランタイムセマンティクス：wevu-best-practices を使用します。

基本フロー

1. ほかのリポジトリレベルの E2E、automator、watch、またはローカル検証サービスがテストリソースを使用していないことを先に確認します。手動で開かれた DevTools、または所有者が不明な DevTools はそのままにしてから、環境の前提条件を確認します：
   • デフォルトでは、ローカルにインストール済みの最新 Stable を解決し、実際のメタデータと接続先ホストを確認します。RC/nightly は明示的に選択された場合にのみ実行します。公式情報の照会はヒントとレポートにのみ使用し、厳密にチェックするのは --require-official-latest を指定した場合だけです。
   • 今回の CLI は自動的に固定されます。また、WEAPP_VITE_E2E_DEVTOOLS_CLI_PATH またはチャネル／バージョンのパラメーターで明示的に選択できます。エントリーポイントはそのパスを今回のプロセスの WEAPP_IDE_CLI_PATH に渡し、プリフライト、共通 CLI、MCP のサブ呼び出し、起動、ビルド、復旧で同じインストールを使います。ユーザーのグローバル CLI 設定は書き換えません。
   • 日常開発と E2E では、ログイン済みの同じ Stable ホストと 1 つの WeChat アカウントを再利用します。複数のプロジェクトでそのホストを共有できます。アカウントが通常どおり期限切れになった場合は再ログインします。異なるインストール間でログインチケットを同期しません。
   • サーバーポートが開いていること。
   • 対象アプリで実際の AppID を使用していること。
2. 同じ e2e-app は、同じ suite 内では automator を一度だけ起動し、describe レベルで共有します。
3. 複数のシナリオでは、ページを切り替えるために DevTools を繰り返し再起動せず、miniProgram.reLaunch(route) を優先します。
4. アサーションでは、ページレベル、構造レベルで、安定して再利用できるランタイムコレクターを優先します。スクリーンショットによる確認は、ルートが安定してから行います。
   • MCP のシナリオでは、まず weapp_devtools_connect を使用し、続いて weapp_devtools_route / weapp_runtime_find_node / weapp_devtools_console を使用します。
5. ページを追加する場合は、以下も合わせて更新します：
   • project.private.config.json の condition.miniprogram.list
   • project.config.json の実際の AppID
6. 次の順序で検証します：
   • node --import tsx scripts/check-e2e-ide-shared-launch.ts
   • 対象の IDE E2E ファイル
   • ビジュアルリグレッションが必要な場合にのみ、wv screenshot --json、wv compare --json、wv ide logs --open を追加します。
7. 変更したシナリオでは、WEAPP_VITE_E2E_RUNTIME_PROVIDER=devtools|headless による再利用を優先します。直接再利用できない場合は、mpcore の所有パッケージに unit/integration と browser e2e を追加し、公開型を変更する場合は type-contract test も追加します。
8. DevTools と headless のセマンティクスが一致しない場合は、安定して再現できる実際の DevTools の動作を基準にします。実際のアサーションを弱めず、mpcore を修正します。
9. queueMicrotask、Web API、DOM/Node のグローバル、または新しい組み込み機能を追加する場合は、対応する注入を有効にしていないネイティブ AppService fixture で typeof と最小限の呼び出しセマンティクスを確認し、DevTools、SDK、renderer、platform を記録します。Node、ブラウザー、型宣言、headless の結果を、その証拠の代わりにしてはいけません。

环境治理与已知边界

• 全面真实 IDE suite 固定在仓库根目录的 main 工作树执行，包括 pnpm e2e:ide:gate、pnpm e2e:ide:full、pnpm e2e:ide:full:exhaustive 以及直接调用 DevTools 的完整 Vitest suite。启动前同步 origin/main，确认 HEAD == origin/main 且工作树干净；suite 运行期间不得切分支或修改源码。.codex-tmp 与其他分支用于 issue 修复、最小复现、headless 和局部诊断，修复合并并重建后回到 main 做正式 IDE 验收。这样可使 WEAPP_VITE_E2E_TRUST_PROJECTS 的路径前缀稳定对应主仓库，避免微信开发者工具因 worktree 路径漂移再次显示项目授权提示；主线约束不改变全机串行、机器租约、宿主身份、端口归属和清理要求。
• 仓库级 E2E 入口通过同机、同用户、跨 worktree 的机器租约互斥运行，包含 headless、CI、直接 Vitest 和聚合脚本；项目租约、端口租约与同一 suite 的多会话仍保留。改变 WEAPP_AGENT_STATE_DIR 不会隔离机器租约。
• 遇到 Runtime busy 时由任务调度层等待持有者完成后再试，不自动抢占、删除锁或构造跳过环境变量。受控子进程只在磁盘 owner token 与 PID 活性核验通过后借用父租约；借用方仅释放自己的登记，不能释放父租约。父进程退出后仍有活子任务或归属未知时保留占用。
• 登录、启动、构建和其他宿主变更操作共用机器租约边界；普通已建立的多项目连接不会为了整个会话长期独占宿主。headless 参与互斥调度，但不应读取或更改真实 IDE 登录状态。
• 启动前检查进程，只释放本任务明确登记且仍持有的 DevTools、automator、watch 和验证服务资源。其他任务等待，手动 IDE 与归属未知的实例保留。
• 启动失败不是全局清理授权。禁止按进程名、命令行子串或 Windows 镜像名终止所有 IDE；不得删除全局 session、port-lease、登录数据和用户缓存。恢复、超时、重试与 teardown 共用幂等 disposer；不将已退出的 CLI PID 当成宿主 PID。
• 安装版本读取应用自身元数据，不能用 Electron 版本代替；连接时复核实际宿主的安装身份、监听端口归属以及 toolInfo() 返回的 IDE/基础库版本。显式指定端口也必须核对归属，不按其他安装最近写入的端口文件猜测目标。
• 共享连接和持久化会话必须匹配安装身份。旧记录缺少身份或目标不匹配时停止复用并诊断，保留未知归属资源；测试不得自动安装、换版、退出账号、复制凭据或清登录缓存。诊断只记录安装、版本、端口归属与登录布尔状态，不输出账号票据或租约 token。
• 默认使用本机已安装的最新 Stable；从官方渠道查询更新提示和报告证据，仅显式严格模式要求匹配官方最新版本，不把默认安装路径、已登录状态或较大版本号当作渠道证明。报告记录查询时间、来源、实际 IDE 及基础库版本；不要长期硬编码某个版本为“最新”。
• 没有用户明确指定，不切换 RC、nightly、开发版或旧稳定版，即使当前测试失败。所选本地安装缺失或未登录时报告未完成；官方查询失败只阻塞显式严格模式，不静默回退、不绕过登录；固定性能运行仍按已批准目标执行，不重新采样。
• 清理回归至少证明：本任务资源被释放，手动实例、另一项目及另一安装版本仍保留；重复 close/recovery 只释放一次。根因与复盘见 docs/plans/2026-09-30-devtools-process-ownership.md。
• OS-only 失败先输出 cross-platform suspect: checking command launch, path normalization, line endings, and filesystem assumptions before product logic，并检查 workflow -> script -> Node wrapper -> child process 的最早分歧。
• 跨平台进程启动优先使用 execa；原始 spawn 必须处理 Windows .cmd、quoting 和必要的 shell 边界。
• 长时间 IDE suite 在 macOS 使用 caffeinate -dimsu -- ...，避免机器休眠导致假失败。
• 若 native fetch 通过而 axios/graphql-request 在 DevTools 报 URL is not a constructor 或同类构造器错误，先做最小复现并记录为 DevTools 兼容缺陷；只 skip 受影响场景，保留 native fetch 覆盖。
• stateful HMR、plugin 输出和 MCP runtime tools 的断言优先使用路由、文本、结构化 bridge 返回值等稳定语义，不匹配压缩变量名或 hash。
• mpcore 可观察行为变化保持三层同步：package unit/integration、browser e2e、公开类型涉及时的 test-d。

约束

• 不要在同一 e2e-app 重复启动 automator。
• 不要为切页面反复重启 DevTools。
• 不要在路由不稳定时先做截图对比。
• 不要把环境问题误判成业务回归。
• 不要只跑通过的一侧 provider，也不要把路径分隔符、CRLF、驱动器或临时目录写进跨平台断言。
• 不要假定所有微信基础库都存在 queueMicrotask；单个 DevTools 版本探测为可用也不能替代兼容层。

输出

应用本 skill 时，输出必须包含：

• suite 结构。
• 页面切换方案。
• e2e-app 配置同步项。
• 最小验证命令。
• 官方稳定版核对来源及时间、实际 IDE/基础库版本、显式版本例外（如有）和资源清理范围。
• 本轮 CLI 选择、实际宿主与端口身份是否一致，以及租约是否由本任务持有、借用或因其他任务占用而等待；不记录敏感凭据。

完成标记

• automator 启动已复用。
• 多场景通过 reLaunch 串联。
• 条件页和 AppID 已同步。
• 已跑共享启动检查和目标 IDE e2e。

参考资料

• references/runtime-e2e-checklist.md

多版本验证使用 pnpm e2e:ide:matrix --targets=stable,rc,nightly --suite=ide-smoke，默认只测试 Stable。整个矩阵持有同一机器租约，前一安装资源终结后切换；失败或缺失继续记录，所有权异常、清理失败、OOM 或取消停止。同一账号切换安装后可能需要重新扫码，无需预备多个账号；矩阵采用非交互模式，登录失效记录为 blocked / needs-login 并继续，不等待扫码或自动重试、不迁移登录数据。报告必须区分选择元数据与实际 runtime 观察，缺失、阻塞、partial 和未执行项不能计为完整通过。