游戏客户端架构 / 系统课时
为输入模块做确定性测试
为输入模块做确定性测试
输入测试若需要真人按键、等待计时器或反复启动编辑器,就很难稳定重现漏按和重复消费。本课用整数逻辑帧驱动同一个输入核心,固定映射、Context 与缓冲期限,让失败发生在明确的帧和事件上,而不是依赖机器运行速度。
学习目标
- 固定输入测试的初始状态、时钟和事件顺序。
- 为边沿、菜单阻断、失焦与缓冲期限设计具体断言。
- 区分输入核心确定性通过与真实设备、游戏模拟验收。
固定影响决策的全部变量
测试夹具至少包含动作映射、初始 Context、初始焦点、缓冲参数和按帧事件。输入模块直接接收测试帧,禁止在内部读取墙上时间、随机数或真实设备。采用时间戳的实现也可以注入单调时钟,但测试必须主动推进,不能调用 sleep 等待。
同帧事件按 seq 排序,并拒绝重复的 (tick, seq)。例如菜单打开在前、跳跃按下在后,与相反顺序可能有不同结果。只按帧号排序会把规则隐含在数组顺序中,录制文件换一种序列化顺序就可能改变结果。
本例将缓冲有效期定义为“创建帧至 expiresAt,两端都包含”,并在该帧处理事件后尝试消费。期限是两帧时,第零帧输入允许在第二帧消费,第三帧必须过期。这个边界属于项目约定;换成右侧不包含也可以,但测试和实现必须一起改变。
建立能说明失败原因的夹具
先选择小场景,让每个测试只改变一个条件,而不是把上百次操作压进一个最终状态断言。
- 在规定顺序下映射跳跃,再比较打乱存储顺序后的完整输出。
- 把消费窗口放在到期帧和到期后一帧,分别验证成功与过期。
- 覆盖重复按下、菜单开启、失焦与恢复,检查命令数量和持续状态。
菜单切换清空缓冲,表示旧玩法意图不会在关菜单后突然执行;失焦同样清空 held 与缓冲。释放事件必须持续处理,即使玩法 Context 已关闭。输入核心测试应该使用正式核心函数;本课的教学核心展示规则,不能证明你项目的另一个实现也满足这些规则。
运行包含边界断言的完整例程
保存为 deterministic_input_test.js,执行 node deterministic_input_test.js。只依赖 Node.js 标准库;失败时断言会使进程以非零状态退出。消费者的开放帧是固定条件,本例没有角色物理或引擎事件替身。
'use strict';
const assert = require('node:assert/strict');
function run(records, { openAt = 0, ttl = 2, end = 5 } = {}) {
for (const number of [openAt, ttl, end]) {
assert(Number.isInteger(number) && number >= 0, 'invalid test parameter');
}
const orderKeys = new Set();
const events = records.map(record => {
assert(Number.isInteger(record.tick) && record.tick >= 0 && record.tick <= end);
assert(Number.isInteger(record.seq) && record.seq >= 0);
const id = `${record.tick}:${record.seq}`;
assert(!orderKeys.has(id), 'duplicate order');
orderKeys.add(id);
return { ...record };
}).sort((a, b) => a.tick - b.tick || a.seq - b.seq);
const mapping = { Space: 'Jump', KeyD: 'Move' };
const held = new Set();
const commands = [], moves = [];
let context = 'Gameplay', focused = true, buffer = [], cursor = 0;
for (let tick = 0; tick <= end; tick++) {
while (events[cursor]?.tick === tick) {
const event = events[cursor++];
if (event.kind === 'context' || event.kind === 'focus') {
if (event.kind === 'context') {
assert(['Gameplay', 'Menu'].includes(event.value));
context = event.value;
} else {
assert.equal(typeof event.value, 'boolean');
focused = event.value;
}
// 状态边界不允许旧的持续值与未消费意图泄漏。
held.clear();
buffer = [];
continue;
}
assert.equal(event.kind, 'key');
assert(['pressed', 'released'].includes(event.phase));
if (event.phase === 'released') {
held.delete(event.key);
continue;
}
if (!focused || held.has(event.key) || !mapping[event.key]) continue;
held.add(event.key);
if (context === 'Gameplay' && mapping[event.key] === 'Jump') {
buffer.push({ action: 'Jump', expiresAt: tick + ttl });
}
}
buffer = buffer.filter(command => command.expiresAt >= tick);
moves.push(focused && context === 'Gameplay' && held.has('KeyD') ? 1 : 0);
// 接受后从缓冲删除;每帧最多消费一个,不能重复执行旧命令。
if (focused && context === 'Gameplay' && tick >= openAt && buffer.length) {
const command = buffer.shift();
commands.push({ tick, action: command.action });
}
}
return { commands, moves };
}
const key = (tick, seq, name, phase = 'pressed') =>
({ tick, seq, kind: 'key', key: name, phase });
const trace = [key(0, 1, 'KeyD'), key(0, 2, 'Space'), key(1, 1, 'Space', 'released')];
assert.deepEqual(run(trace), run([...trace].reverse()));
const jump = [key(0, 1, 'Space')];
assert.deepEqual(run(jump, { openAt: 2, end: 3 }).commands,
[{ tick: 2, action: 'Jump' }]);
assert.deepEqual(run(jump, { openAt: 3, end: 3 }).commands, []);
const repeats = [key(0, 1, 'Space'), key(1, 1, 'Space'), key(2, 1, 'Space'),
key(3, 1, 'Space', 'released'), key(4, 1, 'Space')];
assert.deepEqual(run(repeats).commands,
[{ tick: 0, action: 'Jump' }, { tick: 4, action: 'Jump' }]);
assert.deepEqual(run([
{ tick: 0, seq: 0, kind: 'context', value: 'Menu' }, key(0, 1, 'Space')
]).commands, []);
assert.deepEqual(run([
key(0, 1, 'KeyD'), { tick: 1, seq: 1, kind: 'focus', value: false },
{ tick: 2, seq: 1, kind: 'focus', value: true }
], { end: 3 }).moves, [1, 0, 0, 0]);
assert.throws(() => run([key(0, 1, 'Space'), key(0, 1, 'KeyD')]), /duplicate order/);
console.log('7 deterministic checks passed');预期输出
7 deterministic checks passed只打印一行通过信息,不代表只有一个断言。七个检查分别验证重排稳定性、期限两侧、重复边沿、菜单、焦点和重复序号。缓冲测试也检查接受后不会再次消费;最终结果不能只比较命令数量,还要比较每个命令的动作和消费帧。
让失败变得可解释
把 expiresAt >= tick 改成严格大于,第二区间边界断言应失败;去掉重复按下过滤,重复边沿断言应失败;去掉失焦时的 held 清理,恢复焦点后移动归零断言应失败。这样的反例能证明测试正在约束行为,而不是只检查函数跑完。
发生失败时先保存排序后的事件、配置版本与预期结果,再定位首次不同的帧。不要通过增加真实等待时间来“修复”测试;如果同一夹具偶发变化,应排查未注入的时钟、共享可变状态、线程投递或依赖回调顺序。
练习:增加“有缓冲时打开菜单,再关闭菜单”的夹具,断言旧命令没有执行;再加入两个同帧按下与释放事件,明确你的快点击策略。最后在实际引擎中另测窗口失焦、UI 抢占和设备重连。纯逻辑测试通过只证明输入规则,不能证明真实事件已到达,更不能保证物理模拟跨平台逐位一致。