集成测试与 E2E

集成测试回答"模块之间是否按同一契约协作"，E2E 回答"用户路径能否从入口走到最终状态并正确清理"。两者都不能替代真机验收。

测试分层

层级	测什么	用什么跑
纯逻辑	解析器、状态机、工具函数	插件工程已配置的测试框架与脚本（以 `package.json` 为准）
运行时集成	清单装载、接口、数据读写、事件	工程内测试 + 本地运行时
浏览器 E2E	本地调试页面里的完整用户路径	Playwright
环境 E2E	真实宿主、真实网关、真实设备	私有化测试环境人工/自动验收

先锁定前后端契约

前后端的共同契约是统一调用入口：

POST /plugin/invoke
body = { pluginId, handler, input }

写一个契约测试，至少固定：

请求/响应字段和 {code, message, data} 信封。

幂等键由谁生成、重试时是否复用。

事件 id 去重与重复投递行为。

前端代码、后端清单、后端代码三处的 pluginId / 接口名（handler）/ 事件类型一致。

本地全栈集成

前置条件：生成工程依赖已安装，后端目录存在，且没有使用 --frontend-only。在工作区根执行工程已有的 dev 脚本：

在浏览器里走一遍完整路径：插件加载 → 触发动作 → 接口写数据 → 本地事件投递 → 状态回写 → 卸载宿主检查资源归零。事件使用模板已有的本地测试数据，不把媒体消息包装差异当作生产兼容要求。

期间用辅助端点观察数据。先将 FH2_LOCAL_ORIGIN 设为本次 dev 的回环监听地址（默认 http://127.0.0.1:5175）。以下三个模拟数据辅助端点只受本地调试页面同源门禁约束，当前不检查插件令牌；不可发往真实环境，也不能把这一点推广到 /plugin-api/plugin/invoke：

在实际能力工程目录手动投递已存在的事件测试数据：

这验证的是插件接口/事件脚本与本地 HTTP 模拟器，不是真实网关、后端运行时、消息队列或数据库。invoke 调用仍需本机调试 Token，不能省略鉴权；请求示例见后端调试。reset 恢复初始测试数据，不保证空表。

浏览器 E2E（Playwright）

浏览器 E2E 由插件工程维护，覆盖自己的入口、业务状态和资源清理。生成工程不保证已提供 Playwright 配置或 E2E 脚本；先在插件自己的测试目录安装并配置 Playwright，确定 baseURL 指向本次本地调试页面地址，再编写用例。

已具备 Playwright 依赖、配置和测试文件，且 dev 已启动时，可以在该测试工作区执行已有用例：

这是 Playwright CLI 调用方式，不代表生成工程自带某个 npm 脚本。插件测试应显式配置失败时的追踪记录/截图，并在每个用例开始时准备自己的测试数据，避免依赖上一用例遗留状态；含历史列表的用例另测排序和分页。本地模拟器与已部署环境的差异见已知限制。

后端流程集成

不启动流程引擎的快速回归：

build 只产出资产，pack 构建并组装交付包，两者都不启动网关；含后端且非 --frontend-only 的 dev 只启动 HTTP 模拟器，不执行流程。已有测试环境由部署方确认插件、表、能力提供方和队列就绪后，还要验证：

重复触发同一业务 ID 不会产生第二个流程实例。

发人工信号前先查询当前等待状态。

步骤重试、进程重启后流程状态不倒退。

收尾步骤在主步骤失败或取消后仍会尝试执行。

事件消费需在部署环境验证命中消费方的并发执行、独立重试及 Requeue > Discard > Ack（重新入队 > 丢弃 > 确认）聚合处置。重试耗尽后的死信保存和人工重放由部署方协助确认，没有自动死信恢复保证。

E2E 必测分支

成功路径：创建、查询、状态推进、最终呈现。

业务拒绝：重复、冲突、不存在——不自动重试。

契约错误：缺字段、错类型、未知接口。

系统错误：超时、下游 5xx、恢复后重试。

幂等：同键重复调用不产生第二个副作用。

至少一次事件：重复投递只处理一次，或可安全重复。

竞态：切换宿主/项目时，迟到响应不能覆盖新状态。

清理：插件禁用、宿主卸载后资源快照归零。

真机验收门槛

涉及相机、云台、飞行控制、航线下发、媒体回传的用例，只有在目标机型、真实账号权限和目标网络中执行后，才能标记"真机通过"。本地调试页面里的"成功"只说明本地模拟器接受了调用。

失败取证

E2E 失败时保留：

Playwright 追踪记录、截图和失败步骤。

诊断面板记录（pluginId + hostId + 阶段）。

HTTP 状态、业务 code、请求 ID 和幂等键。

流程 ID、失败步骤和重试次数。

设备型号、固件、机场/飞行器 SN 及测试环境。

取证要求见日志与链路追踪：不要记录 Token、密码或签名 URL。

测试分层#

先锁定前后端契约#

本地全栈集成#

浏览器 E2E（Playwright）#

后端流程集成#

E2E 必测分支#

真机验收门槛#

失败取证#