profile-tests

プロファイリングテストとブラウザーテスト

統合プロファイリングライブラリを使用した elements パッケージテストの CPU プロファイリングです。パフォーマンスのボトルネックを特定し、最適化の推奨事項を生成して、アンチパターンを検出します。

クイックコマンド

ブラウザーテストをプロファイリング（簡易）

# Built-in profiling for all browser tests
./scripts/browsertest --profile

# Profile specific test file
./scripts/browsertest --profile packages/elements/src/preview/renderTimegroupToCanvas.browsertest.ts

# Profile with test pattern
./scripts/browsertest --profile -t "batch capture"

ブラウザーテストをプロファイリング（詳細な分析）

# Full analysis with unified profiling library
npx tsx scripts/profile-browsertest.ts \
  packages/elements/src/preview/renderTimegroupToCanvas.browsertest.ts

# Get JSON output for LLM analysis
npx tsx scripts/profile-browsertest.ts \
  packages/elements/src/preview/renderTimegroupToCanvas.browsertest.ts \
  --json

# Focus on specific file
npx tsx scripts/profile-browsertest.ts \
  packages/elements/src/preview/renderTimegroupToCanvas.browsertest.ts \
  --focus renderToImage \
  --json

シナリオをプロファイリング

# Profile a scenario in sandbox
./scripts/ef profile EFCanvas basic --json

# With pattern detection
./scripts/ef profile EFCanvas basic --json --verbose

# Compare against baseline
./scripts/ef profile EFCanvas basic \
  --baseline .profiles/baseline.cpuprofile \
  --json

パフォーマンス調査のワークフロー

テストのパフォーマンス問題を調査するときは、次の手順に従います。

1. 初期プロファイルを取得

# For browser tests
npx tsx scripts/profile-browsertest.ts \
  packages/elements/src/preview/renderTimegroupToCanvas.browsertest.ts \
  --json > profile.json

# For scenarios
./scripts/ef profile EFCanvas basic --json > profile.json

2. JSON 出力を分析

プロファイルを解析して、次の項目を特定します。

{
  "hotspots": [
    {
      "rank": 1,
      "functionName": "updateFrame",
      "file": "EFTimegroup.ts",
      "line": 234,
      "selfTimeMs": 45.2,
      "selfTimePct": 31.1,
      "callCount": 234
    }
  ],
  "byFile": [
    { "file": "EFTimegroup.ts", "timeMs": 82.1, "timePct": 56.5 }
  ],
  "recommendations": [
    "• updateFrame called 234 times - consider caching"
  ],
  "patterns": [
    {
      "name": "Hot Loop Detected",
      "severity": "high",
      "suggestion": "Review loop logic..."
    }
  ]
}

3. 最適化の優先順位を決定

次の項目に注目します。

• selfTimePct > 15% の関数（重大なボトルネック）
• callCount > 100 かつ selfTimePct > 5% の関数（キャッシュの機会）
• timePct > 40% のファイル（アーキテクチャ上の問題）
• severity: "high" のパターン

4. 変更を加える

検出されたパターンに基づいて最適化を適用します。

5. ベースラインとの比較で検証

# Save baseline before changes
./scripts/ef profile EFCanvas basic \
  --save .profiles/baseline-$(date +%Y%m%d-%H%M%S).cpuprofile

# After optimization, compare
./scripts/ef profile EFCanvas basic \
  --baseline .profiles/baseline-TIMESTAMP.cpuprofile \
  --json

比較結果を確認します。

• selfTimeDiffMs が負の値 ＝ 改善 ✅
• selfTimeDiffMs が正の値 ＝ リグレッション ⚠️

プロファイルのメトリクスを理解する

主なメトリクス

メトリクス	意味	用途
selfTimeMs	関数自体で費やした時間（呼び出し先を除く）	直接的な最適化対象
selfTimePct	プロファイル全体の時間に占める割合	優先順位付け（>15% ＝ 重大）
callCount	関数がコールスタックに現れる回数	キャッシュ／メモ化の判断
hitCount	関数を捕捉したプロファイルのサンプル数	ループの検出（>200 ＝ 高頻度ループ）

パターンの解釈

統合プロファイリングライブラリは、よくある 8 つのアンチパターンを検出します。

過剰な DOM 操作 → DOM の更新をまとめるか、DocumentFragment を使用します
レイアウトスラッシング → レイアウトの読み取りと書き込みを分離します
ホットループ → ループ本体を最適化するか、反復回数を減らします
小さなコストの積み重ね → 頻繁に呼び出される関数にメモ化を追加します
負荷の高い JSON 操作 → 構造化複製を使用するか、シリアライズを減らします
頻繁なスタイル計算 → 計算済みのスタイルをキャッシュします
アニメーション API のオーバーヘッド → アニメーションオブジェクトをキャッシュします
特定ファイルへの集中 → アーキテクチャのレビューが必要です

よくある最適化パターン

呼び出し回数が多い（>100）＋時間は中程度（5～15%）

問題： 関数が頻繁に呼び出されるものの、1 回あたりのコストは小さい
解決策： メモ化またはキャッシュ

// Before
function expensiveCalculation(x: number) {
  return /* complex math */;
}

// After
const cache = new Map<number, number>();
function expensiveCalculation(x: number) {
  if (cache.has(x)) return cache.get(x)!;
  const result = /* complex math */;
  cache.set(x, result);
  return result;
}

自己実行時間が長い（>30%）＋呼び出し回数が少ない（<10）

問題： 単一の関数が過剰な処理を行っている
解決策： 複雑さを減らすか、処理を後回しにする

// Before
function processAll() {
  // All work done synchronously
  loadData();
  transformData();
  validateData();
  saveData();
}

// After  
function processAll() {
  loadData(); // Only critical work
  queueMicrotask(() => {
    transformData();
    validateData();
    saveData();
  });
}

DOM 操作パターンを検出

問題： 複数の DOM 更新によってリフローが発生している
解決策： 更新をまとめる

// Before
for (const item of items) {
  container.appendChild(createItem(item)); // Multiple reflows
}

// After
const fragment = document.createDocumentFragment();
for (const item of items) {
  fragment.appendChild(createItem(item));
}
container.appendChild(fragment); // Single reflow

出力形式

テキスト出力（人が読みやすい形式）

./scripts/ef profile EFCanvas basic

次の項目が表示されます。

• 自己実行時間が長いホットスポット
• ファイルごとに集計した時間
• 自動生成された推奨事項
• 検出されたパターン（--verbose を指定した場合）

JSON 出力（LLM／スクリプト向け）

./scripts/ef profile EFCanvas basic --json

プログラムによる分析に使える構造化データです。

• メトリクス付きのホットスポット一覧（順位順）
• ファイル単位の集計
• 推奨事項の配列
• パターン検出結果

詳細モード（強化された分析）

./scripts/ef profile EFCanvas basic --json --verbose

次の情報が追加されます。

• 呼び出し回数
• アンチパターンの検出
• 詳細な提案

用途別プロファイリングツール

再生パフォーマンスをプロファイリング

npx tsx scripts/profile-playback.ts \
  --project improv-edit \
  --duration 5000 \
  --json

エクスポートパフォーマンスをプロファイリング

npx tsx scripts/profile-export.ts \
  --project design-catalog \
  --json

ページ読み込みをプロファイリング

npx tsx scripts/profile-load.ts \
  --project improv-edit \
  --json

トラブルシューティング

「プロファイリング関数が利用できません」

• ブラウザーが Playwright によって制御されていることを確認してください（通常のブラウザーではなく ef open を使用します）

「プロファイルデータが空です」

• シナリオ／テストの実行が速すぎる可能性があります（<10ms）
• 実行時間の長いテストを試すか、テストの複雑さを上げてください

「数値が大きすぎて不自然です」

• 時間の単位がマイクロ秒かミリ秒かを確認してください
• 統合ライブラリはミリ秒を返します
• レガシーインターフェースではマイクロ秒が使われる場合があります

「呼び出し回数がおかしいようです」

• 呼び出し回数は、コールスタックの走査に基づく概算です
• サンプリングに基づく頻度には、代わりに hitCount を使用してください

ベストプラクティス

1. 変更を加える前に、必ずベースラインを保存してください
2. 直接的な影響を把握するには、自己時間に注目してください（合計時間には呼び出し先の時間も含まれます）
3. 最大の効果を得るために、上位3つのホットスポットから始めてください
4. プログラムによる分析には、JSON 出力を使用してください
5. 手動で分析する前にパターンを確認してください。具体的な修正方法が提案されます
6. 変更前後のプロファイルを比較して、変更を検証してください
7. ベースラインの比較でリグレッションに注意してください

追加リソース

• プロファイリングの完全ガイド：elements/PROFILING.md
• LLM 固有のガイド：elements/LLM_PROFILING_GUIDE.md
• 実装の詳細：elements/PROFILING_IMPLEMENTATION_SUMMARY.md
• ライブラリのソース：packages/elements/src/profiling/