リプレイ、CI、エージェント

バグはテストになる

game.replay() はステップのリストをプレイします。JSON ファイルでもオブジェクトでも構いません。これは debuff がオーバーレイのリプレイやファズの発見に使っているシナリオ形式で、どんなツールからでも書き出せます。

{
  "steps": [
    { "press": "ArrowRight" },
    { "wait": 40 },
    { "release": "ArrowRight" },
    { "tap": [160, 90] },
    { "set": { "player.speed": 300 } },
    { "command": "warp", "args": ["level-2"] },
    { "expect": { "state.player.x": { "gt": 80 } } }
  ]
}

test("the wall-clip bug stays fixed", async () => {
  const game = await play();
  game.replay("bugs/wall-clip.json");
  expect(game.state.player.x).toBeAtLeast(8);
});

ステップは wait、press、release、tap、pointerDown、pointerMove、pointerUp、set、command、expect（比較は eq、gt、gte、lt、lte、approx）です。capture ステップは何も描画しないのでスキップされます。

おすすめの習慣：バグを見つけたら、それを引き起こす入力を記録します。その入力をリプレイして失敗するテストを作り、ゲームを直したら、テストは残しておきましょう。

CI で実行する

npx keiko

Keiko はテストが失敗すると終了コード 1 で終わるので、そのまま CI のゲートになります。便利なフラグはこちら。

npx keiko tests/levels        # フォルダを指定
npx keiko -t "boss"           # 名前に "boss" を含むテスト
npx keiko --json > report.json

JSON レポートには、すべての結果がステータスと所要時間付きで並びます。失敗には、メッセージ、where（テスト内のソース行）、ゲームの tick、時間、シーン、ステート、そしてコンソール出力が付きます。どのテストにも属さないところでゲームが出したエラーは outside に入ります。

GitHub Actions のステップならこうです。

- run: npm ci
- run: npx keiko

インストールするブラウザはありません。Keiko は Node で動きます。

コードから

ツールから直接テストを実行できます。

import { formatResult, runTests } from "keiko/runner";

const report = await runTests({ root: process.cwd(), onResult: (r) => console.log(formatResult(r)) });
process.exitCode = report.ok ? 0 : 1;

コーディングエージェント

Keiko はエージェントと相性抜群です。ブラウザが要らず、フィードバックが速く、失敗はスタックトレースではなくゲームの様子を伝えてくれます。うまくいくループはこうです。

1. 欲しい振る舞いのテストを書き、実行して失敗するのを確認する。
2. ゲームを変更する。
3. テストが通るまで実行し、テストは残しておく。

変更のたびに npx keiko --json を実行するよう、エージェントに伝えましょう。debuff プロジェクトでは MCP サーバーの run_tests ツールがこれを行い、新規プロジェクトの AGENTS.md はメカニクスごとにテストを書くようすでにエージェントに求めています。