WingStats Manager Docs

Appearance

Fresh userData サンドボックス（開発用） ​

初回起動フロー（Onboarding / プロファイル新規作成 / ブラウザ自動化のログイン）を、既存の %APPDATA%/broadcast-Overlay/ を破壊せずに 試すための開発ツール。

仕様: .spec-workflow/specs/dev-fresh-userdata-sandbox/

TL;DR ​

powershell
# 既存 DB / 設定を一切触らずに「初回起動状態」のアプリを開く
yarn dev:electron:fresh

# 念のため起動前に既存 userData を snapshot に取っておく
yarn dev:electron:fresh --snapshot

# 既存 matches.db だけは引き継いで Onboarding を試す
yarn dev:electron:fresh --seed-from-current

終了時にサンドボックス（%TEMP%/broadcast-Overlay-sandbox-<ts>/）は自動削除されます。%APPDATA%/broadcast-Overlay/ は 絶対に変更されません。

なぜ必要か ​

通常の yarn dev:electron は %APPDATA%/broadcast-Overlay/ を userData として開くため:

  • 一度プロファイルや UID を設定すると、次回起動時もそれが残る → 「初回起動」を再現できない
  • ブラウザ自動化で一度ログインすると Cookie が残る → 「未ログイン状態」を試せない
  • 開発中に Onboarding ダイアログを変更しても、自分の環境では一度しか出ないので確認が面倒

Fresh モードは Electron 起動時の userData パスを別ディレクトリに切り替えるだけのシンプルな仕組みで、これらすべてを解決します。

仕組み ​

electron/main.ts の ELECTRON_USER_DATA 環境変数 (E2E 用に既に存在) を流用します:

  1. yarn dev:electron:fresh を実行
  2. ラッパースクリプト（scripts/dev/fresh-userdata.ts）が %TEMP%/broadcast-Overlay-sandbox-<ts>/ を作成
  3. ELECTRON_USER_DATA=<sandbox path> を立てて yarn dev:electron を子プロセスとして起動
  4. Electron が ELECTRON_USER_DATA を見て userData を sandbox に差し替え
  5. すべての DB / 設定 / Cookie / storageState は sandbox 配下に書かれる
  6. アプリ終了時にラッパーが sandbox を削除

E2E (tests/e2e/helpers/withTempUserData.ts) と 同じ仕組み を共有しています。

コマンド早見表 ​

コマンド用途
yarn dev:electron:fresh空 userData で起動 → 終了で sandbox 削除
yarn dev:electron:fresh --keep-sandbox終了後に sandbox を残す（中身を覗きたいとき）
yarn dev:electron:fresh --user-data <abs-path>sandbox の場所を明示指定
yarn dev:electron:fresh --snapshot起動前に既存 userData を snapshot
yarn dev:electron:fresh --seed-from-current既存 matches.db のみ sandbox に copy
yarn dev:electron:fresh --seed-from <db-path>任意 db を sandbox に copy
yarn dev:userdata:snapshot --comment "<text>"snapshot を手動作成
yarn dev:userdata:listsnapshot 一覧（timestamp / size / コメント）
yarn dev:userdata:restore <timestamp> [--force]snapshot を %APPDATA%/broadcast-Overlay/ に復元

Snapshot の場所と運用 ​

  • 保存先: %APPDATA%/broadcast-Overlay.snapshots/<timestamp>/
  • 取得方法: コピー（リネームではない）→ 既存 userData は物理的に無傷
  • 取得後は attrib +R /S /D で 読み取り専用属性 が立つ → 誤上書き防止
  • timestamp が衝突する場合（同一秒に 2 回取った等）は エラー終了（自動上書きしない）
  • 古い snapshot は手動削除（Remove-Item -Recurse -Force、必要なら先に attrib -R /S /D）

ユースケース別の使い方 ​

1. Onboarding ダイアログを試したい ​

powershell
yarn dev:electron:fresh

空 userData なので、初回起動時のフローがそのまま走る。

2. 既存設定を絶対に守りたい（念押し snapshot 付き） ​

powershell
yarn dev:userdata:snapshot --comment "before testing X"
yarn dev:electron:fresh

万が一 %APPDATA%/broadcast-Overlay/ が壊れても snapshot から戻せる:

powershell
yarn dev:userdata:list
yarn dev:userdata:restore 2026-05-07T08-30-00-000Z --force

3. 過去の試合データだけ引き継いで「初回プロファイル設定後の状態」を試す ​

powershell
yarn dev:electron:fresh --seed-from-current
  • DB だけ既存内容
  • localStorage / config.json / Cookie は空
  • → 「Onboarding 完了 → ダッシュボードに過去データが出る」フローを試せる

4. ブラウザ自動化の未ログイン状態を試す ​

powershell
yarn dev:electron:fresh

sandbox 内で起動したブラウザ自動化は <sandbox>/browser-automation/storageState.json に Cookie を書く。本番 userData の Cookie には絶対影響しない（electron/ipc/BrowserAutomationHandlers.ts:118 で app.getPath('userData') 配下に閉じる構造）。

トラブルシュート ​

sandbox が削除されない ​

--keep-sandbox 指定なしで終了したのに %TEMP%/broadcast-Overlay-sandbox-*/ が残る場合、ファイルが他プロセスに掴まれていた可能性。手動削除:

powershell
Get-ChildItem $env:TEMP -Filter 'broadcast-Overlay-sandbox-*' | Remove-Item -Recurse -Force

OS のテンポラリクリーンアップでも数日内に消えます。

snapshot 取得が遅い / サイズが大きい ​

%APPDATA%/broadcast-Overlay/ 配下に大量の試合 detail JSON が溜まっている可能性。responses/ 等のキャッシュ系ディレクトリは sandbox では不要なので、snapshot の保管先を別ドライブに変えるのが楽（自動化はしていない）。

snapshot の ReadOnly 属性で開けない ​

Windows Explorer で snapshot ファイルを直接編集したいときは:

powershell
attrib -R /S /D "%APPDATA%\broadcast-Overlay.snapshots\<ts>\*"

または yarn dev:userdata:restore <ts> で復元してから編集する。

dev:electron と dev:electron:fresh を同時起動できる？ ​

できます。userData が別パスなので競合しません。Vite と Electron のポートはデフォルトで重なるので、dev サーバーは 1 個までにしてください（同時に走らせるなら片方を vite --port で別ポートにする必要あり）。

関連 ​