GameTestHelper API
基本信息
| 属性 |
值 |
| 实现类 |
com.gtnewhorizons.horizonqa.api.GameTestHelper |
| 注入方式 |
作为测试方法唯一参数传入，签名 void testName(GameTestHelper helper) |
| 构造函数 |
GameTestHelper(GameTestInstance, WorldServer, int originX, int originY, int originZ)（GameTestHelper.java:57） |
| 公开方法数 |
68 |
| 公开断言方法数 |
37 |
[!NOTE]
坐标类方法默认使用测试局部坐标，并提供 TestPos、绝对 int 三元组、结构标签字符串的平行重载。
标签重载经 pos(String) 解析（含结构旋转），无匹配标签时抛 LabelResolutionException
（GameTestHelper.java:42-47）。
功能
GameTestHelper 是测试方法体内唯一的操作入口，覆盖四类能力：坐标换算、断言、世界操作、流程控制。
坐标换算
| 方法 |
说明 |
来源 |
absolute(x, y, z) |
局部坐标 → 绝对 TestPos |
GameTestHelper.java:68 |
absolute(TestPos) |
同上，TestPos 重载 |
GameTestHelper.java:73 |
pos(String label) |
结构标签名 → TestPos |
GameTestHelper.java:83 |
absolute(String label) |
标签 → 绝对 TestPos |
GameTestHelper.java:93 |
getOriginX/Y/Z() |
测试格原点坐标 |
GameTestHelper.java |
断言
断言失败抛 GameTestAssertException（内部包 GameTestInfrastructureException），
带位置信息以定位到具体方块坐标。
| 分组 |
方法 |
| 布尔 |
assertTrue / assertFalse（均有带 message 与不带 message 两种重载） |
| 空值 |
assertNull / assertNotNull |
| 相等 |
assertEquals（Object / long / double+delta）、assertNotEquals（同三种）、assertSame / assertNotSame |
| 集合 |
assertIterableEquals、assertLinesMatch |
| 方块 |
assertBlockPresent / assertBlockAbsent |
| TileEntity |
assertTileEntityPresent、assertTileNBT、assertTileNBTPath |
| 实体 |
assertEntityPresent / assertEntityAbsent、assertEntityCount、assertEntityNBT、assertEntityNBTPath |
| 物品 |
assertItemEqual、assertSlot、assertInventoryContains / assertInventoryCount / assertInventoryEmpty |
| 流体 |
assertFluidTank / assertFluidTankEmpty |
| 红石 |
assertRedstonePower |
| 类型 |
assertInstanceOf |
| 异常 |
assertThrows |
| 前提 |
assumeTrue / assumeFalse（失败时为 ASSUMPTION_FAILED，非真实失败） |
完整方法名清单（grep -n '^ public ' GameTestHelper.java）：
absolute afterTest assertBlockAbsent assertBlockPresent assertEntityAbsent assertEntityCount
assertEntityNBT assertEntityNBTPath assertEntityPresent assertEquals assertFalse assertFluidTank
assertFluidTankEmpty assertInstanceOf assertInventoryContains assertInventoryCount assertInventoryEmpty
assertItemEqual assertIterableEquals assertLinesMatch assertNotEquals assertNotNull assertNotSame
assertNull assertRedstonePower assertSame assertSlot assertThrows assertTileEntityPresent
assertTileNBT assertTileNBTPath assertTrue assumeFalse assumeTrue clearSlot countItems
destroyBlock disableRandomTicks extractItem fail fixWorldTime getEntities getEntityNBT
getOriginX getOriginY getOriginZ getRecorder getTileNBT getWorld gtnh insertFluid
insertItem onEachTick onEachTickDisabled pos pulseRedstone setBlock setRedstoneInput
setSlot setTile setWeather simulateLeftClick simulateRightClick spawnEntity spawnFakePlayer
startSequence succeed succeedAtTimeout succeedWhen
流程控制
| 方法 |
说明 |
来源 |
succeed() |
立即判定通过 |
GameTestHelper.java:111 |
succeedWhen(BooleanSupplier) |
每 tick 求值，谓词为真时通过 |
GameTestHelper.java:116 |
succeedAtTimeout() |
超时时判定通过 |
GameTestHelper.java:124 |
fail(String) / fail() |
立即判定失败 |
GameTestHelper.java:196、201 |
startSequence() |
进入序列（sequence）模式，支持分步时序断言 |
GameTestHelper.java |
onEachTick(Runnable) / onEachTickDisabled() |
注册 / 注销每 tick 回调 |
GameTestHelper.java |
getRecorder() |
取只读 EventLog，查看本测试已记录事件 |
api/event/EventLog.java:6-8 |
afterTest |
测试结束钩子 |
GameTestHelper.java |
gtnh() |
取 GTNHGameTestHelper 扩展 |
GameTestHelper.java |
隔离与时间
fixWorldTime()：固定世界时间，消除昼夜噪声disableRandomTicks()：关闭随机刻setWeather(...)：通过 api/Weather.java 枚举设置天气- 每测试通过独立的 fixture 区域（
TestCell）与强制加载区块（GameTestChunkLoader）保证隔离
- 违反隔离会抛
TestIsolationViolation（api/TestIsolationViolation.java）
数值
| 数值名 |
值 |
来源 |
| 公开方法总数 |
68 |
grep -n '^ public ' GameTestHelper.java |
| 断言类方法数（含 assume） |
37 |
同上（assert* 32 + assumeTrue + assumeFalse + assertThrows 计入口径） |
| 默认超时 tick 数 |
100 |
api/annotation/GameTest.java:17 |
| 每 tick 时长 |
0.05 秒 |
report/CaseResult.java:27（TICKS_PER_SECOND = 20.0） |
交互
- 断言在序列（sequence）步骤内超时，会包装为
SequenceStepTimeoutException
（internal/SequenceStepTimeoutException.java:7），它继承自 GameTestAssertException
并保留步骤快照与最后一次断言的带位置 cause（SequenceStepTimeoutException.java:11-18）
assumeTrue / assumeFalse 失败不计入失败，而是 ASSUMPTION_FAILED
（report/CaseResult.java:28）gtnh() 返回的扩展依赖 GregTech 5 Unofficial，非 GT 环境下不可用
相关条目