AIに任せたE2Eテストが俺TUEEEと化していたので、実プレイ由来のセーブデータで作り直した話

以前、Claude Code と Unity CLI Loop（旧 uLoopMCP）を組み合わせて、開発中のモバイルゲームのチュートリアルE2Eテストを自動化した話を書きました。

https://zenn.dev/unsoluble_sugar/articles/2a1f9e08ac9980

その後もE2Eテストのシナリオを増やし続けた結果、当時の構成では立ち行かない課題がいくつも顕在化しました。本記事は、その解決としてE2Eテスト基盤を2段階で作り直し、最終的に 「セーブデータスナップショットをロードするだけで検証条件を即再現する」方式へ移行した話です。

先に前提を書いておくと、対象は小〜中規模のモバイル向けカジュアルRPGです。大きめのゲーム開発であれば、セーブデータのスナップショットを使ってテストすること自体は普通にやられているはずで、手法として目新しいものではありません。

本記事の主眼はそこではなく、「人間が手動でE2Eテストを実行・検証する」体制から「AIが自動でE2Eテストを回し、テストの追加や修正まで任せられる」体制へ、この規模の開発でどう切り替えたかにあります。スナップショットはそのための土台です。

前回同様、実際にやったこと・変えたことベースで、移行のメリットだけでなくデメリットや運用上の注意点も書いていきます。

実行環境

本記事の内容は、執筆時点の以下環境におけるものです。

• macOS Sequoia 15.7.7
• Unity 6000.3.10f1
• Unity CLI Loop v2.1.10
• Claude Code v2.1.215

前回のおさらいと、その後

前回の記事で紹介したのは「セーブデータ初期化 → 起動 → 利用規約同意 → メインチュートリアル完走」までを自動で流すE2Eテストでした。構成は次の4層です。

「AIに毎ステップ判断させる」のをやめてロジックをシェルスクリプトに固めることで、トークン消費と実行時間（240秒→104秒）を大きく削減できた、というのが前回の結論でした。

ただ、前回対象にしたのは初回起動チュートリアルだけでした。これは、E2Eとしてはいちばん決定化しやすい題材です。セーブデータを消せば毎回必ずまっさらな状態から始まるので、前提状態の準備に悩む必要がありません。

しかしゲームの本番はチュートリアルの先にあります。特定レベルで機能が解禁され、装備やスキルが育ち、進行度によって挙動が変わる。この「進行テスト」に手を出した瞬間、「毎回同じ進行状態をどう用意するか」という、初回起動には存在しなかった問題に突き当たりました。

この問題を抱えつつもシナリオを増やし続けた結果、現在はチュートリアル以外に20本超のシナリオ（バトル、ダンジョン、ガチャ、放置報酬、デイリーミッションなど）が回るようになりました。本記事で紹介するスナップショット方式は、この進行テスト群を支える土台です。

顕在化した課題

E2Eテストのシナリオが増えるにつれて、当時の構成の限界がはっきりと見えてきました。

課題1: bash に埋め込んだ C# 文字列が壊れやすい

シナリオロジックの実体は bash スクリプト（計約4,100行）に文字列として埋め込んだC#コードでした。これが構造的に脆い状態でした。

• 文字列ベースのリフレクション: GetField("_claimButton", NonPublic) のような呼び出しは、対象フィールドのリネームで即死するのに、実行時まで壊れたことに気づけない
• 型名・GameObject名の文字列一致: GetType().Name == "DailyMissionItem" のような判定はUIリファクタで即座に破壊される
• bash+C#文字列のエスケープ地獄、シェル sleep ポーリング、CLI呼び出しをまたいで状態を受け渡すための __E2E_BRIDGE__ GameObject ハック

壊れたときに何が起きるかというと、AIが実行時エラーを見て「たぶんこのフィールド名に変わったのだろう」と推論で補い始めてしまうんですよね。

それで直ることもありますが、シナリオ実行のたびに推論とリトライが挟まって遅く不安定になり、最悪「テストが通るように」誤った修正をされるリスクもあります。

課題2: テストの前提状態を作るコストが高すぎる

もっと深刻だったのがこちらです。

• ほぼ全シナリオが「チュートリアル完走済みセーブ」を暗黙の前提としており、無い場合は毎回チュートリアルを実走して作っていた
• 解禁レベルが前提のシナリオ（ダンジョン系: Lv6、仲間: Lv4 等）は、レベルアップAPIの反復実行 + PlayMode 再起動という高コストなセットアップをしていた
• バトルの勝敗を決定化するために Lv1000装備の強制やボス級敵の強制指定を使っていた。つまり「通常プレイでは到達し得ない状態」でテストしていた
• セーブデータの退避/復元が macOS 専用のシェル手順（cp / rm / defaults delete）に依存していた
• セーブデータのマイグレーション検証は EditMode の合成データテストのみで、実プレイ由来の旧バージョンセーブに対する検証手段がなかった

特に3つ目は、テストとしてかなり筋が悪い状態でした。実はこれ、バトルシナリオの設計ごと Claude Code に任せたらこうなっていた、というものです。

「勝敗を決定化したい」という要求に対して、AIは既存のデバッグ機能を組み合わせて「戦力と敵を強制する」という最短経路を選びました。

確かに毎回同じ結果にはなります。ただ、いきなりLv1000の装備を引っ提げて序盤の敵を瞬殺していく姿は、実挙動のテストというよりチート能力を授かった異世界転生主人公的な俺TUEEEです。敗北ケースに至っては、ボス級の敵を強制出現させる「序盤の街に魔王襲来」方式でした。

AIは大真面目に「勝利ケースPASS」と報告してくるのですが、これでは実際のプレイヤーが通る勝利・敗北フローを検証したことにはなりません。

移行その1: bash+動的コード → コンパイル済み C# E2E API

まず課題1を解消するため、シナリオロジックを bash から Editor 限定アセンブリのコンパイル済みC# に全面移行しました。

• E2E専用アセンブリ（Editor限定・!RELEASE_BUILD）を新設し、共通基盤（E2EContext / E2ESession / E2EAsyncOps / E2EUiQuery / E2EDialogs 等）とシナリオ別API（E2EGameEvent / E2EBattle / E2EDailyMission …）を実装
• E2EContext はロード済みシーンからDIコンテナを解決し、Service や Model へ型安全にアクセスする
• View の internal プロパティは <Type>.E2E.cs の partial + InternalsVisibleTo で公開し、リフレクション文字列を全廃
• 旧 __E2E_BRIDGE__ GameObject ハックは、開始と結果取得を分離した2段API（E2EAsyncOps.Status() が PENDING / DONE:<result> を返す）に置き換え
• bash スクリプトと共通関数ライブラリは全削除

エージェント（Claude Code）の動き方は「スキルの SKILL.md に書かれた手順に従い、uloop execute-dynamic-code でE2E APIを1行呼び出しする」に変わりました。

uloop execute-dynamic-code --code 'return MyGame.Tests.E2E.E2EGameEvent.GetState();'
# => "STAMINA:50|COIN:12345|..."

これでリネーム・リファクタによる破壊はコンパイル時に検知されるようになります。AIが実行時エラーから推論で補う場面は激減し、「コンパイルを通す」という決定的なフィードバックループに置き換わりました。

ちなみに単体テストは Unity Test Framework（EditMode）で普通に書いています。E2E もテストランナー（PlayModeテスト）に載せる選択肢はありましたが、スクリーンショットの目視確認・録画・停滞時の状況判断など、テストランナーの枠に収まらない検証をAIにやらせたいため、次の区分けを意図的に維持しています。

• 単体テスト = Unity Test Framework（EditMode）
• E2Eテスト = スキル駆動のエージェント実行（Claude Code）

UI操作のルールもこの移行で固めました。

第一選択は uloop simulate-mouse-ui による EventSystem 経由の実クリックです。onClick.Invoke() は非表示・無効化されたボタンでも発火してしまうため、「押せないはずのボタンが押せてしまう」系の不具合まで拾うには、レイキャストや interactable の実挙動を通る実クリックが必要です。

例外として、クリックで破棄されるダイアログだけは、破棄済みオブジェクトへのアクセスでエラーになることがあったため onClick.Invoke() 直呼びにフォールバックしています。

フォールバック対象のボタンは実クリック検証を諦めていることになるため、そこは検証の穴として自覚しつつ、「ダイアログが閉じたか・報酬が正しく付与されたか」というゲーム内状態と期待値の突合で本質の検証を担保しています。

移行その2: セーブデータスナップショット

ここからが本題です。課題2「前提状態の構築コスト」を、検証対象の進行状態を名前付きセーブデータスナップショットとしてリポジトリに保存し、ロードするだけで再現する方式で解決しました。

このゲームのセーブデータはクライアント内のSQLite単一ファイルとなっています。そのためスナップショットの実体も「DBファイルのコピー + メタデータJSON」だけで済みます。

ディレクトリ構成と E2EFixture API

Tests/E2E/Fixtures~/
├── README.md                     # 索引・運用ルール
└── v1.2.0/                       # 撮影時のアプリバージョン別ディレクトリ
    ├── tutorial-completed.db             # スナップショット本体（平文SQLite）
    ├── tutorial-completed.manifest.json  # DBと対になるメタデータ
    ├── lv06-dungeon-unlocked.db
    ├── battle-win-ready.db
    └── ...

• ディレクトリ末尾の ~ は Unity のインポート対象外にするため。.meta が生成されず、Editor限定アセンブリ配下でもビルド混入の心配がない（アクセスは File I/O のみ）
• ハマりどころ: グローバル gitignore の *~ パターンと衝突するので、同階層の .gitignore で明示的に追跡対象へ戻す必要がありました
• Editor 専用機構なのでDBは平文のまま（リリースビルドのみ暗号化される設計）

操作APIは E2EFixture に集約しました。すべて uloop execute-dynamic-code から1行で呼びます。

# これだけで「ダンジョン解禁済み・Lv6」の検証条件が整う
uloop execute-dynamic-code --code 'return MyGame.Tests.E2E.E2EFixture.Load("lv06-dungeon-unlocked");'
# => "OK:loaded:v1.2.0/lv06-dungeon-unlocked:rebased_columns=42"
#    （rebased_columns は後述の時刻リベースで更新した列の数）
# あとは PlayMode を開始すれば、Boot 時に未適用マイグレーションが自動適用されて Main に到達する

Load の1コマンドの裏では、次の一連の処理が走っています。

かつて macOS 専用シェルで書かれていた退避/復元も API 化したので、脱シェル・OS非依存になり、git worktree で作業コピーを分けたときの Unity Editor の保存先パス分離にも自動追従するようになりました。

manifest はこんな内容です。Capture() が撮影時のDB実値（マイグレーションID・プレイヤーEXP）を自動記入し、撮影者が説明と不変条件を追記します。

{
    "name": "tutorial-completed",
    "appVersion": "1.2.0",
    "capturedAtUtcTicks": 639192654667712070,
    "lastMigrationId": "Migration202601011200",
    "pointExpCount": 210,
    "description": "チュートリアル完走直後（Lv2・自動周回解禁済み）。全シナリオの基盤",
    "generation": "e2e-fixture-capture Phase 1（初期状態→チュートリアル完走）",
    "invariantItemCounts": [],
    "invariantUnlockedFeatures": [
        "LockedFeature01_IdleRewards",
        "LockedFeature02_AutoPlay"
    ]
}

スナップショットセット

現行バージョンのセットは以下のような形です。機能の解禁レベル境界に合わせて撮影しており、シナリオの前提状態にはこうしたスナップショットを用意しています。

「解禁直前」のスナップショットがあるのがポイントで、「Lv+1したら機能が解禁されてチュートリアルが発火する」という境界そのものを検証するのに使います。

設計原則: スナップショットは「実プレイ由来」で作る

この機構でいちばん大事にしたのが生成側のルールです。スナップショットは初期状態からの実プレイで実際に到達した状態だけを収録する、と決めました。

方針は「実プレイで到達し得ない状態を作る操作は禁止、時間さえかければ実プレイと同じ結果になる加速は許容」です。代表例を挙げます。

「抽選は固定してよい。結果は捏造しない」

許容と禁止の線引きを一般化すると、「分岐や抽選の行き先は Debug 機能で固定してよい。ただしその結果生じる状態は、実プレイと同じコードパスで発生させる」 となります。

• 許容: ランダムイベントの抽選結果を ForceGameEvent("Battle") でバトルに固定する。どのイベントが出るかを固定するだけで、そのバトルの敵も勝敗も実プレイと同じ（実戦・実結果）
• 禁止: Lv1000装備・ボス級敵の強制。結果（戦力・敵の強さ）そのものの捏造

この手法の代表例が敗北用スナップショット battle-lose-ready の生成です。自然に進行すると装備が育って通常バトルには勝ち続けてしまい、「通常バトルで負ける状態」が作れません。

そこで、次の手順を踏みました。

1. イベント抽選をバトル固定にして装備を一切獲得させずに進行する（装備は初期値のまま）
2. 仲間/スキルは装備したままボスを突破し、ステージだけ進める → 装備がステージ相応の敵に追いつかなくなる
3. 十分進んだら仲間/スキルを外す → 通常バトルの連戦でHPが削られ、2〜3戦目に自然敗北する

この敗北は実際の敵との実戦の結果であって、ボス級敵強制のような捏造ではありません。ゲーム設計（仲間/スキル＝主要戦力、装備＝通常戦の勝敗、ボス＝進行の壁）を利用して「自然に負ける状態」を作っているのがポイントです。

なお、この状態でも「何戦目で負けるか」は2〜3戦の幅でブレます。そのためシナリオ側は 「負けるまで抽選を繰り返す」有界ループ型にしてブレを吸収し、決定化するのは「必ず敗北に収束する」という方向だけに絞っています。

勝利側の battle-win-ready は逆に仲間/スキルを装備した状態で撮影し、勝敗ペアを「仲間/スキルの有無」で対称に決定化しました。バトルシナリオの手順書からは Lv1000 装備強制・ボス級敵強制が完全に消えています。

ちなみにこのペア設計は、最初から狙っていたわけではありません。当初の勝利ケースは「自然に育った装備でボスに勝つ」想定だったのですが、撮影中の実測で勝てないことが判明。勝敗を左右するのは装備品だけではなく仲間/スキルを活用するか否かだと分かり、「仲間/スキルの有無」のペア設計に方針転換しました。

異常値で決定化していた頃には見えていなかったゲームバランスの実態が、実プレイ由来に切り替えたことで見えてきた、という副産物でもありました。

時刻のリベース

スナップショット方式特有の問題がひとつあります。セーブデータ内の時刻（放置報酬の最終受取、デイリーミッションのリセット等）は絶対UTC時刻で保存されており、「now − 保存時刻」で経過を算出します。つまり撮影から時間が経ったスナップショットをそのままロードすると、放置報酬が満タンになっているなど撮影時と違う状態になってしまいます。

対策として、Load はDBコピー直後に「撮影時刻と現在時刻の差分」を対象の時刻列へ一律加算します。相対関係を保ったまま「いま撮影した」ことにするわけです。

スナップショットの生成もE2Eで自走する

スナップショットは手作業で作るのではなく、生成パイプライン自体を Claude Code のスキル（手順書）にしました。

1. ResetToFirstLaunch() で初回起動状態を作る
2. 既存のチュートリアルE2E（前回記事のシナリオの後継）でチュートリアルを完走 → Capture("tutorial-completed", ...)
3. 以降は前のチェックポイントから継続プレイで差分生成。倍速の自動周回でレベルを上げ、解禁レベルの閾値ごとに停止
4. 解禁チュートリアルが発火したら実際に消化してから撮影（チュートリアルの指ガイド座標を返すAPIを叩き、返ってきた座標を simulate-mouse-ui でタップ、のループ）

4は地味に重要で、PlayMode 再起動でチュートリアルをスキップして撮影することは禁止にしています。ガイド中の実操作（ガチャを引く・装備する）がセーブに反映されず、通常プレイと乖離したスナップショットになってしまうからです。

この生成フローを図にすると次のようになります。前のチェックポイントから継続プレイし、解禁境界ごとに停止して撮影するループ構造です。

副産物: 旧バージョンのスナップショットがマイグレーション検証のテストデータ集になる

スナップショットをバージョン別ディレクトリに保管し、旧バージョンのセットは削除禁止というルールにしたことで、思わぬ強力な副産物が生まれました。

起動時のマイグレーションは未適用分を自動適用するので、旧バージョンのスナップショットはそのまま「実プレイ由来の旧セーブデータ」としてマイグレーションの回帰検証に使えます。

検証は2層です。

1. EditMode テスト（高速・全数）: 全バージョンの全 .db を列挙 → tempコピー → マイグレーション実行 → 「例外なし・適用済みIDが最新・manifest の不変条件（EXP値・所持アイテム・解禁機能）が成立」を assert。マイグレーションを追加すると自動で回帰ゲートになる
2. E2E ブートスモーク（実経路）: 旧スナップショットを Load → 実際に Boot → Main 到達・Errorログ0件・破損隔離ファイル（Save.corrupted-*.db）が生成されていない・進行データが維持されている、を確認

従来「合成データの EditMode テストのみ」だったマイグレーション検証が、実プレイ由来のデータで自動回帰する体制になりました。

移行して得られたもの

当初狙っていた観点と、やってみて分かった効果をまとめます。前回は実行時間の短縮を成果として強調しましたが、今回の移行では実行時間をあまり重視していません。

これは git worktree で作業環境を分けてAIにテストを自動実行させる運用が定着し、人間が完了を待って張り付く場面自体が減ったためです。時間のかかるデータ生成側も倍速デバッグ機能で走るため、体感上のボトルネックになっていません。

1. 推論に委ねる部分の減少

• シナリオロジックはコンパイル済みC#になり、リネーム破壊はコンパイル時に検知。AIが実行時エラーから「たぶんこう直せば」と推論する場面がほぼ消えた
• 前提状態の構築も Load("battle-lose-ready") などの1コマンドになり、「レベル上げが足りているか」「前提セーブがあるか」をAIが判断する余地がなくなった
• AIの役割は 「SKILL.md の手順を順に実行し、決定的なAPIの戻り値（OK: / ERROR:）を期待値と突合して結果を報告する」に集約された
• 課題1で挙げた「テストが通るように誤った修正をされる」リスクも、ロジックがコンパイル済みコードとレビュー対象の手順書（SKILL.md）に固定されたことで、書き換えが必ず PR の差分として可視化されるようになった

2. 再現性の確立

• 全シナリオが毎回同一のDBファイルから開始される。実行のたびに微妙に違うセーブ状態で走ることがなくなった
• 勝敗のような確率的に見える結果も、「勝てる進行状態」「負ける進行状態」のスナップショットペアで決定化。しかも異常値ではなく実プレイ由来なので、検証しているのは本物の勝利/敗北フロー
• 時刻リベースにより、時間依存の状態（放置報酬・デイリーリセット）も撮影時のまま再現される

3. テスト追加・変更のしやすさ

新シナリオの追加が「前提スナップショット名の指定 + 検証手順の markdown + 必要なら小さなE2E API」だけになりました。前提状態の構築コードを書く工程が丸ごと消えています。

実際、移行完了後には、もともと追加を想定していた基本機能の検証シナリオを続けざまに追加できました。いずれも前提はスナップショットの Load だけで、前提構築のコードは書いていません。成功条件も既存シナリオと同じく「期待値との厳密一致・Errorログ0件」です。

4. AIの自己ループ強化

個人的に一番効果を感じているのがここです。E2Eの前提・手順・検証がすべてスキル（手順書）とコンパイル済みAPIに構造化されたことで、Claude Code が自律的に回せるループが太くなりました。

• 新機能の実装を依頼すると、既存のE2Eスキルを参考に対象機能のE2Eテストを追加し、関連する既存テストを実行して回帰確認までやってくれる。「テストを書いて」と言わなくても、隣のシナリオの形式に倣って揃えてくる
• 不具合検出の質が上がった。実プレイ由来の状態で回すので、異常値テストでは踏めなかった本物のコードパス（解禁チュートリアル、報酬オーバーレイ、ストアレビュー要求の割り込み…）を踏む
• 修正→検証のループが速い。不具合を見つけたら該当スナップショットを Load して即再現、修正して同じ手順で再検証。再現手順の構築が不要

これを実感したエピソードをひとつ紹介します。

スナップショット撮影のために倍速の自動周回で放置プレイをさせていたところ、Unity Editor が繰り返しフリーズする問題に遭遇。Claude Code と一緒にログ解析とスタックダンプ採取で追究した結果、真因はチュートリアルの指ガイド実装に潜んでいた無限ループバグで、実機でもプレイヤーが踏み得るものでした。

つまり、テストデータを「実プレイ由来」で作る方針にしたおかげで、撮影自体が長時間放置プレイのストレステストとして機能し、本番で起き得るバグを事前に検出・修正できたわけです。

異常値注入でスナップショットを作っていたら、おそらくこのバグは踏めていません。

デメリット・運用上の注意点

いいことばかりではないので、把握しているコストも並べておきます。

• バイナリコミット: SQLiteファイルはPRで差分レビューできない。manifest の併記と「生成パイプラインで再現可能」であることで補っているが、レビュー体験は確実に悪化する
• リポジトリの肥大: バージョンセットが増えるほどリポジトリは膨らむ。ただしサイズは1本あたり200KB弱・現行セット全体でも約1.5MBなので、テストが今後増えても当面 Git LFS 等の対策を考える必要はない規模
• バージョンアップごとの再撮影コスト: アプリバージョンを上げるたびに最新セットを生成パイプラインで撮り直す運用が必要。自走するとはいえ実プレイ由来なので時間はかかる
• ゲームバランス調整との乖離リスク: 「battle-win-ready で自然に勝てる」という性質はバランス調整で崩れ得る。シナリオ側の前提アサート（期待状態でなければ「前提:」メッセージで明示的に失敗）で検知する設計にしているが、根本的には再撮影で追従するしかない
• 時刻列の追従運用: DateTime を保存する新しい列名を追加したら、リベース対象列の一覧を更新する必要がある。セーブデータ仕様の更新チェック項目に組み込んで運用でカバー
• エディタE2E専用: 実機ビルドはDB暗号化・パス差異があるため対象外。実機での検証は別の手段が必要
• ローカル実行前提: 現状は手元の Unity Editor + Unity CLI Loop で実行する前提で、CI には組み込んでいない。CI 組み込みは将来的にできればと考えている段階で、実現方法はまだ深掘りしていない

Before / After まとめ

おわりに

前回の記事では「テストロジックをAIの推論から決定的なコードに寄せる」ことで速度と再現性を得ました。今回はそれをさらに進めて、テストの前提状態まで決定的な成果物（スナップショット）に寄せたことになります。

方針は一貫しており「AIに委ねる範囲を、AIが一番得意な部分（手順の実行と結果の解釈・報告）まで絞り込む」という形です。状態構築もロジックも決定化された結果、逆説的ですが、AIは新しいテストの追加や不具合の調査といった創造的な仕事に集中できるようになり、自己ループはむしろ強化されています。

「E2Eテストのセットアップが重くてシナリオを増やせない」「AIにテストを任せたいが実行のたびに挙動が揺れる」という方には、セーブデータスナップショット方式はかなりおすすめできます。SQLite単一ファイルのようなポータブルなセーブ形式を採用しているゲームなら、導入のハードルはそれほど高くないはずです。

なお、今回紹介した仕組みの手軽さは「セーブデータがローカル完結している」ことに支えられています。前述のとおり本タイトルも将来的にはSaaSクラウドへのセーブデータ移行を検討しており、その際は「DBファイルのコピー」というスナップショットの実体は成立しなくなります。

それでも「名前付きの進行状態を実プレイ由来で撮影し、ロードするだけで検証条件を再現する」という考え方自体はサーバー側のテストデータ設計にそのまま持ち込めるはずで、移行時にはこの機構をどう引き継ぐかも設計項目の一つになる予定です。

参考

https://zenn.dev/unsoluble_sugar/articles/2a1f9e08ac9980

https://zenn.dev/hiraoku/articles/56f4f9ffc6d186

https://github.com/hatayama/unity-cli-loop