SuperAPI AI 工具集
合作ENAI 行业资讯收藏
Skill 广场minecraft-testing

minecraft-testing

测试与质量

查看项目

更新于 10-15 15:26

技能介绍

用途

Minecraft Testing Skill 用于为 Minecraft 模组与插件项目设计、实现自动化测试，覆盖单元测试、模拟测试、游戏内 Game Test 以及 CI 测试任务。它适用于当前 Minecraft 26.x 或旧版 1.21.x 项目。技能明确指出不适用于：实现玩法功能而非测试玩法功能的任务（属于 minecraft-modding、minecraft-plugin-dev、minecraft-datapack），以及发布自动化或发布流水线（属于 minecraft-ci-release）。

主要能力（测试策略）

  • JUnit Jupiter（纯单元测试）：适合逻辑、数据结构、NBT 序列化，不需要游戏。
  • MockBukkit：适合 Bukkit/Paper 插件的事件、命令、物品栏，不需要真实服务器（使用模拟服务器）。
  • NeoForge GameTests：适合游戏内方块/实体/世界交互，需要测试环境。
  • Fabric GameTests：适合游戏内方块/实体/世界交互，需要测试环境。
  • 集成服务器：适合完整插件/模组生命周期，需要专用测试服务器。

版本与 Java 对应：当前 26.x 项目用 Java 25；旧版 1.21.x 示例保持在 Java 21；Forge 1.20.1 用 Java 17。不要跨版本组合源码布局或 API。

附带参考与辅助

  • 布局指南：references/test-layouts.md
  • Fixture/布局校验器：./scripts/validate-test-layout.sh --root <project>。在把测试布局复制到真实项目前使用该校验器。它检查可见的静态依赖、元数据和字面结构引用，但不会编译项目，也不能证明 Game Test 可以运行。

使用方式（各类测试要点）

单元测试（JUnit Jupiter，无 Minecraft）

Gradle 中配置 tasks.test 使用 useJUnitPlatform() 并开启 testLogging。对于需要加载器设置的 Fabric 代码，应使用 Fabric Loader JUnit（依赖 net.fabricmc:fabric-loader-junit:${project.loader_version}），而不是假设普通 JUnit 已初始化 Minecraft。当单元测试触及依赖注册表的 Minecraft 类时，只在测试 setup 中初始化所需 bootstrap；当前 Fabric 指南使用 SharedConstants.tryDetectVersion() 与 Bootstrap.bootStrap()。

MockBukkit（Paper/Bukkit 插件测试）

文中的配对依赖是保留的 26.2 示例。对于 26.3，在更改任一依赖前，先确认与该确切 Paper 版本线对应的已发布 MockBukkit 制品；26.2 的 mock 不能证明 26.3 服务器行为。示例依赖包括 paper-api、junit-jupiter、mockbukkit-v26.2 与 junit-platform-launcher。

Setup/teardown 模式使用 MockBukkit.mock() 启动模拟服务器并用 MockBukkit.load() 加载插件，MockBukkit.unmock() 清理。示例涵盖：事件测试（addPlayer、simulateJoin、assertSaid、PlayerJoinEvent、BlockBreakEvent 取消）、命令测试（dispatchCommand、Op 权限校验）、物品栏/物品测试（kit starter）、调度器任务测试（performTicks）、Folia 安全的调度器抽象测试（SchedulerFacade 接口包装调度，MockBukkit 不模拟 Folia 的区域线程运行时）、PDC 测试（EntityDeathEvent 需要活体受害者和明确的伤害源；监听器应读取 event.getDamageSource().getCausingEntity()，真实战斗归因需在真实服务器上另行测试），以及物品或区块 PDC 写入测试（itemPdc_roundTripsCustomId）。

当前 NeoForge Game Tests（26.x）

NeoForge 1.21.5 及以后使用数据驱动的测试环境和测试实例，而不是旧的 @GameTestHolder 方法注册 API。资源放在 data/<namespace>/test_environment/ 和 data/<namespace>/test_instance/。test_instance 选择环境、结构、时序，以及注册的函数或基于方块的测试。示例 JSON 包含 environment、structure、max_ticks、setup_ticks、required、type、function 字段。使用 DeferredRegister 为当前 BuiltInRegistries.TEST_FUNCTION 注册 Consumer<GameTestHelper>，并挂到模组事件总线。仅在代码中注册环境和测试实例（而非数据文件）时使用 RegisterGameTestsEvent。被引用的结构应放在 data/<namespace>/structure/<path>.nbt，并显式标记成功。运行 ./gradlew runGameTestServer，服务器以必需失败测试的数量退出。

当前 Fabric Game Tests（26.x）

使用 Fabric Loom 专用 Game Test 源集，在 fabricApi 块中配置 configureTests（createSourceSet = true、modId、enableGameTests、enableClientGameTests、eula）。将 fabric.mod.json 放在 src/gametest/resources/，服务端测试注册在 fabric-gametest 下，客户端测试用 fabric-client-gametest。服务端方法用 net.fabricmc.fabric.api.gametest.v1.GameTest 实现，需要方法运行前 setup 时用 CustomTestMethodInvoker。保持 fabric-gametest 入口点与具体 Game Test 类同步。Fabric 服务端 Game Tests 随 build 运行；客户端测试用 runClientGameTest。具体 Loom 选项与无头客户端 CI 请遵循当前 Fabric 文档。

旧版 NeoForge Game Tests（仅 1.21.3）

基于注解的测试仅限 Minecraft 1.21.3。类可通过 @GameTestHolder(MOD_ID) 或 RegisterGameTestsEvent 监听器注册，不要对 @GameTestHolder 类再用 modEventBus.register(MyGameTests.class) 注册。对于 RegisterGameTestsEvent，在模组事件总线上注册类，并在每个 @GameTest 上设置 templateNamespace = MOD_ID。旧模板是 data/<namespace>/structure/ 下的 .nbt 文件；@PrefixGameTestTemplate(false) 控制模板路径是否加入类名。省略 template 时，路径使用小写方法名，并且除非禁用该前缀，还会加入小写简单类名加一个点。template 只是路径名，其命名空间通过 templateNamespace 或 @GameTestHolder 配置。

CI

保持快速单元/mock 测试与加载器 Game Test 任务分离，并针对每个 Minecraft 版本选择 Java：26.x 用 25，1.21.x 用 21，Forge 1.20.1 用 17。当面向运行时的任务失败时上传测试报告。不要假设其他加载器的任务名：Fabric 服务端 Game Tests 随 build 运行，而 NeoForge 使用 runGameTestServer。MockBukkit 不能证明 Folia 线程安全或真实服务器 bootstrap。

限制

  • 校验器只检查可见的静态依赖、元数据和字面结构引用，不编译项目，也不证明 Game Test 能运行。
  • MockBukkit 不模拟 Folia 的区域线程运行时；也不能证明 Folia 线程安全或真实服务器 bootstrap。
  • 26.2 的 mock 不能证明 26.3 服务器行为。
  • PDC 测试中合成的死亡事件只用于派发；真实战斗归因需在真实服务器上单独测试。
  • runGameTestServer 命令用于真实项目，不适用于该 skills 仓库本身。

参考

  • MockBukkit GitHub：https://github.com/MockBukkit/MockBukkit
  • MockBukkit docs：https://docs.mockbukkit.org/
  • Fabric automated testing：https://docs.fabricmc.net/develop/automatic-testing
  • NeoForge 26.x Game Tests：https://docs.neoforged.net/docs/misc/gametest/
  • NeoForge 1.21.3 Game Tests：https://docs.neoforged.net/docs/1.21.3/misc/gametest/
  • JUnit Jupiter user guide：https://junit.org/junit5/docs/current/user-guide/