AIでブラウザゲームをデバッグする方法｜スクリーンショットと再現手順

不具合報告は、四つの項目から始める

最初に端末と画面条件を書きます。パソコンかスマートフォンか、画面は縦か横か、どの画面から始めたかを残します。次に押したボタンや移動した場所を順番に書き、期待した結果と実際の結果を対にします。原因の予想を長く説明するより、別の人が同じ操作をできる記録を優先しましょう。

たとえば「開始、右移動を押し続ける、指をボタンの外へ動かして離す。その後も右へ移動する。期待は指を離した時点で停止」です。この形なら、正常に押せる場合との違いを調べられます。毎回起こるか、時々だけか、再読み込み直後でも起こるかを添えると、条件をさらに絞れます。

再挑戦後だけ起こるなら、何回目かを記録します。音が二重に鳴る、敵が増える、時間の減り方が変わるなど、数字や観察できる現象を書きます。似た症状があっても原因が同じとは限りません。AIには、今の実装を確認してから仮説を立て、仮説を確かめる方法も示すよう依頼します。

環境：端末、ブラウザ、画面の向き
開始地点：タイトル／プレイ／結果
操作：1 → 2 → 3
期待：何が起きるべきか
実際：何が起きたか
頻度：毎回／特定の回だけ
添付：問題の画像、関連するエラー、確認時刻

画像には、正確な文字や数値を別に添える

OpenAIの画像入力の資料には、視覚モデルが小さな文字や精密な位置の理解を誤る場合があると説明されています。ゲーム画面を見せるときも、画像から読めそうだから十分とは考えません。エラー文章、得点、残り時間など、判断に必要な値は文字でも添え、画面のどこを見るかを指定しましょう。

画像は問題の場面を共有するものです。ボタンが画面外に出る問題なら全体を、文字が重なる問題なら該当箇所が読める画像を用意します。修正前後の比較では、同じ画面幅と同じゲーム状態を使います。幅や得点が違う画像同士では、変更による違いなのか条件による違いなのか判断しにくくなります。

Canvasで描いたものとHTMLのボタンが混ざる画面では、見た目の位置と入力の座標が一致しているかも調べます。「ボタンが右にある」という画像の説明だけでは、どの座標変換が必要か決まりません。表示領域の寸法、描画の寸法、入力位置をどこで計算しているかをコードで確かめます。

入力、ゲーム状態、表示を順番に追う

入力が届かない問題と、届いた入力を表示に反映できない問題は、修正する場所が違います。当ブログの提案は、操作を受け取った時点、ゲーム状態が変わった時点、画面を描いた時点を分けて調べる方法です。必要な箇所だけ一時的に記録し、全フレームの大量のログで重要な情報を埋めないようにします。

タッチの例なら、押し始め、移動、離したとき、操作が中断されたときに、入力の状態がどうなるかを見ます。MDNのPointer eventsの資料で扱われるイベントの種類を確認し、採用している入力方式に合わせます。見た目のボタンを大きくするだけでは、押しっぱなしの状態が残る原因を解消できない場合があります。

原因が分かったら、関連する最小の変更から試します。入力の修正と画面の全面変更を同時に行うと、どの変更が効いたか分からなくなります。再現できる手順があるなら修正前に残し、修正後にも同じ手順を使います。不要になった調査用ログを片付けるところまで作業に含めましょう。

修正の確認は、結果まで見る

Playwrightの公式資料では、画面や要素の状態を確認するためのアサーションが説明されています。自動化する場合も「クリックを実行できた」だけを成功にしません。開始後に説明が消えたか、結果が表示されたか、再挑戦で得点が戻ったかなど、その操作で変わるはずの状態を確認する条件にします。

自動化に向かない遊び心地は、人が触って確認します。クリック可能な範囲や反応の遅さ、音が重なる感じは、コードの成功判定だけでは見落とすことがあります。修正対象がスマートフォンの入力なら、画面を狭くしたパソコンの確認と、指で操作した確認を区別して記録します。両者を同じ実機確認として扱いません。

最後に、問題が起きた条件と近い条件を一つずつ試します。指を外へ動かして離す問題なら、ボタン内で離す、画面を離れる、再挑戦後に押す、といった条件です。すべての操作を無制限に繰り返す必要はありません。何を確かめたかと何が未確認かを残せば、次の不具合報告に役立つ記録になります。