aily Blockly E2E测试体系揭秘：Playwright+Electron自动化测试与AI执行手册完整设计指南
【免费下载链接】aily-blocklyAI IDE for hardware development, support Arduino, MicroPython, ESP32, STM32, RP2040, Nrf5x...项目地址: https://gitcode.com/gh_mirrors/ai/aily-blockly
aily Blockly是一款面向硬件开发的 AI IDE，支持 Arduino、ESP32、STM32、RP2040、nRF5x 等开发板。它的 E2E 测试体系基于Playwright 的_electronAPI直接启动 Electron 桌面应用，对生产构建产物做真实回归，并配套一份专为 AI 编码代理设计的执行手册（AI Runbook），让自动化测试既能"跑得起来"，也能"说得清楚"。
一、为什么桌面应用的 E2E 测试很难做？
普通 Web 应用用 Playwright 测浏览器就行，但 aily Blockly 是一个Electron 桌面应用，还牵扯编译工具链、开发板包、SDK 安装等重型操作。常见痛点有三个：
- 产物失真：开发环境（dev server）能跑，不代表生产打包产物能跑；
- 进程难管：每个用例都要真实启动一个 Electron 实例，还有编译、终端等子进程要清理；
- 批量测试成本高：验证所有开发板 + 项目广场全部项目，动辄几小时，失败后从哪继续？
aily Blockly 的方案可以概括为一句话：用生产路径跑测试、用断点扛长流程、用 AI 手册管执行纪律。
二、工作原理：三步启动真实的生产应用
整个 E2E 体系的核心配置在 playwright.config.ts，关键逻辑分三步：
1. 全局构建：每次都用最新代码
全局设置文件e2e/global-setup.ts会在测试启动前执行ng build --base-href ./，然后把 Angular 产物从dist/aily-blockly/browser暂存到项目根目录的renderer/。这正是electron-builder打包时的映射关系（browser→renderer），每次运行都重新构建，不复用旧产物，确保测试针对的是当前源码。
2. 启动夹具：像用户一样打开应用
启动夹具e2e/fixtures/electron-app.ts用 Playwright 的_electron.launch以项目根为工作目录启动 Electron 主进程（electron/main.js）。主进程走"非--serve"分支，通过loadFile('renderer/index.html')加载生产渲染层——无需完整打包安装，却跑的是真实生产路径。
夹具还处理了三个工程细节：
- 每个测试使用独立的临时
--user-data-dir，隔离用户配置，不污染真实数据； - 应用会预缓冲若干
about:blank子窗口，夹具通过检测<app-main-window>标签精确定位真正的主窗口； - 关闭应用时优先调用
app.quit()走优雅退出，让编译、终端等子进程完成清理，超时才强制杀进程树。
3. 测试策略：串行 + 失败留痕
由于每个用例都真实启动 Electron，配置里设置workers: 1串行执行，避免多实例争抢窗口与资源；失败时自动保留trace、截图、视频（retain-on-failure），方便事后复盘。
三、测试套件：从冒烟到全开发板编译
测试用例统一放在e2e/tests/目录，按覆盖范围分为三档（完整清单见e2e/README.md）：
| 档位 | 代表用例 | 覆盖内容 |
|---|---|---|
| ✅ 默认运行 | smoke.spec.ts、guide.spec.ts、tools.spec.ts、aily-chat.spec.ts | 启动、主窗口、指南页、串口监视器/终端、AI 聊天离线 UI |
| ✅ 默认运行 | compile-diagnostic.spec.ts、error-decision.spec.ts、full-flow-checkpoint.spec.ts | 编译器根因诊断、错误决策、断点续跑等辅助逻辑回归 |
| ⏭️ 需环境变量 | blockly-editor.spec.ts、compile.spec.ts、full-flow.spec.ts | 打开已有项目、真实编译、单/全开发板与项目广场全流程 |
其中full-flow.spec.ts是全流程核心：指定开发板后，自动完成"选板 → 新建项目 → 安装依赖 → 冷编译 → 热编译"的完整链路，第二板还会额外验证 QEMU/GDB 块级调试闭环（simulator-debug.spec.ts）。
常用运行入口：
# 完整回归（重新构建生产渲染层后运行） npm run test:e2e # 只跑某个用例文件 npm run test:e2e -- smoke.spec.ts # 有界面调试 / 打开 HTML 报告 npm run test:e2e:headed npm run test:e2e:report所有入口都通过scripts/run-e2e.mjs转发给 Playwright CLI，并自动判断是否为交互终端（TTY）来决定错误提示行为。
四、断点续跑：让几小时的批量测试可以"中断后继续"
全流程测试（指定开发板 / 所有开发板 / 项目广场）耗时可能长达数小时，e2e/full-flow-checkpoint.ts实现了断点机制：
- 待处理条目持久化到
e2e/.artifacts/full-flow-checkpoints/下的模式文件（如all-boards.json），成功项自动移除，失败项保留； - 再次执行相同命令时自动从剩余条目继续；删除对应 checkpoint 文件即可从头开始；
- 交互终端下遇错会标红提示：输入
c视为已处理并继续，输入a中止并保留断点；设置AILY_E2E_STOP_ON_ERROR=0则无人值守跑完再统一汇总； - 项目广场支持可复现抽样（
SAMPLE_RATE+SAMPLE_SEED），例如 builder 验证时随机抽取 50% 项目，相同 seed 保证续跑时选择同一批项目。
五、AI 执行手册：把"怎么测"写成机器可执行的纪律
这套体系最有特色的部分是e2e/AI-RUNBOOK.md——一份面向 AI 编码代理的执行手册。它不按测试文件组织，而是按"操作类型"组织，规定了 AI 在什么场景下必须跑哪些测试、通过标准是什么、什么不能跳过：
| 操作类型 | 场景 | 必测内容 |
|---|---|---|
OP-UI-CHANGE | 普通 UI/路由改动 | 冒烟 + 受影响页面用例，合并前跑默认全集 |
OP-BUILDER | 测试编译工具 aily-builder | 辅助逻辑回归 + 代表板冷/热两轮编译 + 项目广场 50% 抽样 |
OP-RELEASE | 发布前验收 | 默认 E2E + 冷环境 builder + 全开发板 + 项目广场全量 |
OP-FAILURE-RETRY | 失败定位 | 原命令断点续跑 + 报告分析，禁止弱化断言凑通过 |
手册还定义了AI 错误归因与自动跳过规则：项目广场中的失败必须先归入builder/project/environment-or-unknown三类，只有凭证据确认"是项目自身问题"的条目才允许加入跳过列表（SKIP_PROJECT_IDS），builder 或环境问题一律不得跳过。测试完成后，AI 必须按固定的 YAML 结构汇报版本、命令、退出码、跳过项与覆盖缺口，release_decision只有pass或blocked，不允许"基本通过"这种模糊结论。
六、这套设计对普通开发者的启示 🚀
即使你不在维护 aily Blockly，这套 E2E 体系也提供了桌面应用自动化测试的完整参考清单：
- 测生产路径，而不是开发环境——用打包同款产物启动应用，才能发现真实问题；
- 夹具隔离一切状态——临时用户数据目录 + 优雅退出兜底强杀，测试之间互不污染；
- 长流程必须可断点——批量验证开发板/项目时，中断续跑能把数小时的重跑成本降到失败点之后；
- 给 AI 一份带纪律的手册——明确"必测/不能证明/汇报格式"，AI 代理才能可靠地承担回归与发布验收职责。
说明：当前 E2E 未覆盖"上传烧录"流程，因为它需要真实外设，不便在 CI 稳定运行；发布前该项由人工验收补充（详见
e2e/AI-RUNBOOK.md的覆盖边界章节）。
想动手体验，只需克隆仓库、执行npm ci安装依赖后，在项目根目录运行npm run test:e2e，第一次跑完再看npm run test:e2e:report的 HTML 报告，你就能完整感受这套 Playwright + Electron + AI 执行手册的组合拳。
【免费下载链接】aily-blocklyAI IDE for hardware development, support Arduino, MicroPython, ESP32, STM32, RP2040, Nrf5x...项目地址: https://gitcode.com/gh_mirrors/ai/aily-blockly
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
