测试插件#

插件测试应覆盖源码级自动化检查、开发环境联调和最终 JAR 安装验证。haloServer 能快速加载开发目录，但不能代替对发布制品的安装测试；准备发布时还需要完成插件发布验收清单。

#选择验证层级

优先运行与改动最相关的最小任务，再运行完整构建。不要因为页面可以打开，就跳过权限、失败路径和生命周期验证。

#运行自动化检查

#后端测试

Halo 插件通常使用 JUnit 5，测试代码位于 src/test/java。只验证后端时运行：

./gradlew test

测试应围绕实际行为编写，至少覆盖本次变更涉及的正常路径和失败路径。处理用户输入、权限、外部服务或响应式错误时，还应验证无权限、无效输入、依赖不可用和异常传播。

#UI 检查

推荐的插件工程会在 UI 子项目中注册 pnpmCheck，并把它接入 Gradle 的 check 生命周期：

./gradlew :ui:pnpmCheck

如果 UI 目录名为 console，将命令中的 ui 替换为 console。不同项目的 pnpmCheck 可能只运行单元测试，也可能同时运行格式、Lint 和类型检查；以仓库的 ui/build.gradle、package.json 和 CI 配置为准。接入方式参考 UI 构建。

不要手动修改 OpenAPI 生成的 API client。API 契约变化时，应运行项目已有的生成任务，并把生成差异与后端契约一起审查。

#完整检查

运行所有已接入 Gradle 验证生命周期的任务：

./gradlew check

发布前执行干净构建：

./gradlew clean build

标准 Java Gradle 工程的 build 会依赖 check，并在 build/libs 生成插件 JAR。自定义测试任务只有接入 check 后才会随完整构建执行，因此新增测试任务时需要同时检查任务依赖关系。

#在本地 Halo 中联调

使用 DevTools 启动加载开发目录的 Halo：

./gradlew haloServer

修改插件后，可以重新加载或持续监听：

./gradlew reload
# 或者持续监听
./gradlew watch

haloServer 和 watch 需要 Docker，并会复用项目的 workplace 目录。该目录中的数据会跨任务重启保留；需要验证首次安装或默认配置时，应使用新的测试数据目录或干净环境，不要把生产数据用于开发测试。

联调时至少检查：

• 插件能够启动，服务端和浏览器控制台没有未处理错误。
• API 的成功、无权限、无效输入和依赖失败路径符合预期。
• Console 或用户中心入口在不同角色下正确显示并限制操作。
• 配置保存、重新加载和 Halo 重启后仍然生效。
• 使用外部服务时，超时、认证失败和服务不可用不会破坏 Halo 的主要流程。
• 与主题集成并提供 Finder、模板或前台资源时，在实际主题中验证输出；声明插件依赖时，验证依赖缺失、停用、版本不满足和正常启用的状态。

#验证兼容性和生命周期

至少在 plugin.yaml 的 spec.requires 所声明的最低 Halo 版本和计划支持的当前版本上验证关键路径。不要仅根据编译成功推断兼容范围。

禁用、重载和重启后，插件应能恢复工作，持久化业务数据不应被意外删除。升级和卸载测试应使用可丢弃环境，并按照插件生命周期确认运行时资源、预置资源和持久化数据的处理结果。

#记录可复核结果

人工测试或 AI Agent 执行后，应保留能够复现结论的信息：

Commit:
Halo versions tested:
Java, Node.js and pnpm versions:
Commands run:
Automated checks: pass/fail
Roles and dependency states checked:
Manual paths checked:
Known limitations:

命令失败、测试被跳过或环境与声明兼容范围不一致时，应明确记录，不能用“构建成功”概括未执行的验证。