debugging

デバッグスキル

コンソールの調査、ネットワーク分析、トレースポイント、ログポイント、例外監視による、ブロッキングを伴わないコードデバッグを使用して、Web アプリケーションと Node.js バックエンドをデバッグします。

使用するタイミング

このスキルは、次のような場合に有効になります。

• ユーザーが Web ページまたはバックエンドのバグやエラーを報告した場合
• ユーザーが JavaScript（フロントエンドまたは Node.js）のデバッグを依頼した場合
• ユーザーが API 呼び出しやネットワークリクエストを調査したい場合
• ユーザーがページの読み込みや API ハンドラーの問題をトラブルシューティングする必要がある場合
• ユーザーがコンソールのエラーや警告について言及した場合
• ユーザーがブレークポイントを使わずにデバッグしたい場合
• ユーザーが関数呼び出しを追跡したり、変数を監視したりする必要がある場合

機能

コンソールの調査

browser-devtools-cli o11y get-console-messages
browser-devtools-cli o11y get-console-messages --type warning
browser-devtools-cli --json o11y get-console-messages --type error

ネットワーク分析

browser-devtools-cli o11y get-http-requests
browser-devtools-cli --json o11y get-http-requests --resource-type fetch
browser-devtools-cli --json o11y get-http-requests --status '{"min":400}'

トレースポイント（ブロッキングなし）

browser-devtools-cli debug put-tracepoint --url-pattern "app.js" --line-number 42
browser-devtools-cli debug list-probes --types tracepoint
browser-devtools-cli debug remove-probe --type tracepoint --id <probe-id>
browser-devtools-cli debug clear-probes --types tracepoint

ログポイント

browser-devtools-cli debug put-logpoint --url-pattern "app.js" --line-number 50 --log-expression "user.id"
browser-devtools-cli debug list-probes --types logpoint
browser-devtools-cli debug remove-probe --type logpoint --id <probe-id>
browser-devtools-cli debug clear-probes --types logpoint

例外監視

browser-devtools-cli debug put-exceptionpoint --state uncaught
browser-devtools-cli debug put-exceptionpoint --state all

ウォッチ式

browser-devtools-cli debug add-watch --expression "this"
browser-devtools-cli debug add-watch --expression "user.id"
browser-devtools-cli debug list-probes --types watch
browser-devtools-cli debug remove-probe --type watch --id <probe-id>
browser-devtools-cli debug clear-probes --types watches

スナップショットの取得と消去（統合）

browser-devtools-cli --json debug get-probe-snapshots
browser-devtools-cli --json debug get-probe-snapshots --types tracepoint,logpoint,exceptionpoint
browser-devtools-cli --json debug get-probe-snapshots --probe-id "tp_abc" --from-sequence 0
browser-devtools-cli debug clear-probe-snapshots
browser-devtools-cli debug clear-probe-snapshots --types tracepoint --probe-id "tp_abc"

Node.js バックエンドのデバッグ（node-devtools-cli）

Node.js の API サーバー、バックエンド、またはスクリプトをデバッグする場合：

# 1. Connect to process (by PID, name, or Docker)
node-devtools-cli --session-id backend-debug debug connect --pid 12345
node-devtools-cli --session-id backend-debug debug connect --process-name "server.js"

# 2. Tracepoint on route handler or service
node-devtools-cli --session-id backend-debug debug put-tracepoint \
  --url-pattern "routes/api.ts" \
  --line-number 42

# 3. Exception monitoring
node-devtools-cli --session-id backend-debug debug put-exceptionpoint --state uncaught

# 4. Console logs from Node process
node-devtools-cli --session-id backend-debug --json debug get-logs
node-devtools-cli --session-id backend-debug --json debug get-logs --search "error"

# 5. Retrieve snapshots (after triggering the code path)
node-devtools-cli --session-id backend-debug --json debug get-probe-snapshots
node-devtools-cli --session-id backend-debug --json debug get-probe-snapshots --types tracepoint,exceptionpoint

# 6. Status and cleanup
node-devtools-cli --session-id backend-debug debug status
node-devtools-cli debug disconnect

Node.js のコンテキストでは、urlPattern はスクリプトのファイルパス（例：server.js、routes/users.ts）に一致します。詳しくは、node-devtools-cli スキルを参照してください。

エラーの調査

browser-devtools-cli content take-screenshot --name "error-state"
browser-devtools-cli content get-as-html --selector ".error-container"

基本的なデバッグワークフロー

1. 再現：問題が発生しているページに移動します
2. キャプチャ：現在の状態のスクリーンショットを撮影します
3. コンソールを調査：JavaScript エラーがないか確認します
4. ネットワークを分析：失敗したリクエストを探します
5. 調査：診断用 JavaScript を実行します
6. 記録：証拠を添えて調査結果を要約します

# Quick debug workflow
browser-devtools-cli navigation go-to --url "https://example.com"
browser-devtools-cli content take-screenshot --name "initial"
browser-devtools-cli --json o11y get-console-messages --type warning
browser-devtools-cli --json o11y get-http-requests --status '{"min":400}'

高度なデバッグワークフロー（ブロッキングなし）

1. プローブを設定する

SESSION="--session-id debug-session"

# Navigate to app
browser-devtools-cli $SESSION navigation go-to --url "http://localhost:3000"

# Tracepoint on a function
browser-devtools-cli $SESSION debug put-tracepoint \
  --url-pattern "app.js" \
  --line-number 42

# Exception monitoring
browser-devtools-cli $SESSION debug put-exceptionpoint --state uncaught

2. ウォッチ式を追加する

browser-devtools-cli $SESSION debug add-watch --expression "this"
browser-devtools-cli $SESSION debug add-watch --expression "user.id"

3. アプリケーションを操作する

browser-devtools-cli $SESSION interaction click --selector "#submit-btn"
browser-devtools-cli $SESSION sync wait-for-network-idle

4. スナップショットを取得する

browser-devtools-cli $SESSION --json debug get-probe-snapshots
browser-devtools-cli $SESSION --json debug get-probe-snapshots --types tracepoint,exceptionpoint
browser-devtools-cli $SESSION --json debug get-probe-snapshots --from-sequence 0

5. クリーンアップする

browser-devtools-cli $SESSION debug clear-probes
browser-devtools-cli $SESSION debug clear-probe-snapshots
browser-devtools-cli session delete debug-session

プローブの種類の概要

プローブ	目的	出力	CLI
トレースポイント	関数呼び出し	スタック、ローカル変数、ウォッチ	browser-devtools-cli、node-devtools-cli
ログポイント	式の値	評価結果	両方
例外ポイント	エラーの捕捉	エラー、スタックトレース	両方
ウォッチ	トレースポイントごとの式	スナップショット内の watchResults	list-probes、remove-probe、clear-probes で一覧表示／削除

ベストプラクティス

1. 適切な CLI を選択する：フロントエンド／ページのデバッグには browser-devtools-cli を使用し、Node.js バックエンド／API のデバッグには node-devtools-cli を使用します
2. 最初に必ずコンソールでエラーを確認する
3. 関連するエンドポイントにネットワークリクエストを絞り込みます
4. 操作の前後にスクリーンショットを撮影します（ブラウザー）
5. 縮小／バンドルされたコードにはソースマップを使用します
6. まず例外を設定して、エラーを捕捉します
7. 軽量な監視にはログポイントを使用します
8. 効率化のため、--from-sequence を使ってスナップショットをポーリングします
9. オーバーヘッドを避けるため、完了したらプローブを消去します
10. 再現手順を明確に記録します