MDN wants to talk to developers like you: https://qsurvey.mozilla.com/s3/a3e7b5301fea

デバッグ

この記事では、デフォルトでインストールされている Firefox 開発ツールを使って、WebExtensions をどのようにデバッグするか説明します。Add-on SDK で開発したアドオンをデバッグする場合は、アドオンデバッガ の解説を参照してください。

デバックツールへの接続方法を、簡単なサンプルアドオン "notify-link-clicks-i18n" を用いて説明します。このコードは GitHub の WebExtensions examples リポジトリ で公開されています。

このアドオンは以下から構成されています。

  • バックグラウンドスクリプト "background-script.js"
  • コンテンツスクリプト "content-script.js" (全てのページに読み込まれるスクリプト)

ページ上のリンクをクリックするという動作は、コンテンツスクリプトがイベントとして感知します。リンクがクリックされた際、 リンクを含んだメッセージがコンテンツスクリプトからバックグラウンドスクリプトに送られます。

バックグラウンドスクリプトがメッセージを受け取ると、リンクを含んだ通知画面が表示されます。

"content-script.js"

/*
リンクがクリックされた場合、バックグラウンドページにメッセージを送信する。
このメッセージにはリンクの URL が含まれている。
*/
function notifyExtension(e) {
  var target = e.target;
  while ((target.tagName != "A" || !target.href) && target.parentNode) {
    target = target.parentNode;
  }
  if (target.tagName != "A")
    return;

  console.log("content script sending message");
  chrome.runtime.sendMessage({"url": target.href});
}

/*
クリックイベントのリスナ関数に notifyExtension() を追加する
*/
window.addEventListener("click", notifyExtension);

"background-script.js"

/*
受信したメッセージを記録する。
続いて通知画面を表示する。
この通知画面には、メッセージから読み取った URL が含まれている。
*/
function notify(message) {
  console.log("background script received message");
  var title = chrome.i18n.getMessage("notificationTitle");
  var content = chrome.i18n.getMessage("notificationContent", message.url);
  chrome.notifications.create({
    "type": "basic",
    "iconUrl": chrome.extension.getURL("icons/link-48.png"),
    "title": title,
    "message": content
  });
}

/*
content script からのメッセージを受信するリスナ関数に `notify()` を追加する
*/
chrome.runtime.onMessage.addListener(notify);

以下の手順を実際に試してみる際は、 webextensions-examples リポジトリからコードを clone し、"notify-link-clicks-i18n" を インストールして下さい

ブラウザツールボックス

アドオンをデバッグするには ブラウザツールボックス を使用します。

前提条件

ブラウザツールボックスを使用する準備として、以下の手順を踏む必要があります。

  • Firefox 開発ツールを開く (Shift+Ctrl+I / F12)
  • 設定 タブ(歯車のアイコン)を開く
  • "詳細な設定" において下記の設定項目にチェックが入っているか確認する。
    • ブラウザとアドオンのデバッガを有効
    • リモートデバッグを有効

ブラウザツールボックスを開く

次に、ブラウザツールボックスを開きます。

  • Alt キーを押下して表示されるメニューで、"ツール" → "Web 開発" → "ブラウザツールボックス" の順にクリックします。ブラウザコンソールでは無いことに中止して下さい。
  • 警告ダイアログが出るかもしれませんが OK を押して下さい。

ブラウザツールボックスが新しいウインドウとして開きます。ここで Firefox のメインウィンドウが前面に表示された場合は、ブラウザツールボックスが前に表示されるように画面をクリックしてください。

Firefox における "ツールボックス" とは、下図のように複数のツールがタブで句切られているウインドウの名前です。上記のツールボックスには 5 つのツール、"Inspector" / "Console" / "Debugger" / "Style Editor" / "Scratchpad" が含まれており、ウインドウの上部にあるタブで切り替えることができます。この記事では "Console(コンソール)" と "Debugger(デバッガ)" の 2 つのツールを使用します。

ログの出力を見る

コンソールタブでログを見ることができます。ここに表示されるメッセージは以下から出力されたものです。

  • バックグラウンドスクリプト
  • ポップアップの中で動作しているスクリプト
  • コンテンツスクリプト

このメッセージには、Console API を使用しているコードから出力されたログも含まれています。また、JavaScript エンジンからもエラーメッセージが出力されます。

それでは上記のサンプルを使って試してみましょう。ブラウザツールボックスのコンソールタブを選択し、何かしらの Web ページを開き、リンクをクリックし、コンテンツスクリプトやバックグラウンドスクリプトからメッセージが記録されるのを確認してみましょう。

ただし、ブラウザツールボックスはどんなメッセージも受け取るため、要らないメッセージも多く受け取ってしまう問題があります。この問題を解決するには フィルタリングと検索 を参照して下さい。

JavaScript をデバッグする

ブラウザツールボックスを用いると、バックグラウンドスクリプトやブラウザ上で動作しているスクリプト、ポップアップのページアクションで動作するスクリプトに対し、JavaScript デバッガでブレークポイントを設定することができます。

アドオンがインストールされて有効になっている間は、デバッガからバックグラウンドスクリプトにアクセス可能です。ポップアップスクリプトは、ポップアップが表示されている間にアクセス可能です。ポップアップスクリプトが読み込まれた時点ですぐにデバッガからアクセスしたい場合は、スクリプトの最初に debugger; 文を挿入してみてください。

JavaScript デバッガを使用するために、まずはブラウザツールボックスのデバッガタブを選択します。ここにはブラウザで動いている全てのソースコードが表示されています。そのため、検索ボックスをクリックしてソースの名前を入力し、自分のスクリプトが表示されるようにします。

自分のスクリプトを見つかったら、ブレークポイントをコードに設定したり、コードをステップ実行したり、他にもデバッガに可能なことは何でも実行できます

JavaScript コマンドラインインタプリタ

コンソールには コマンドラインインタプリタ が含まれており、実行しているプログラムの状態を調べたり操作することができます。この機能はコンソールを Web ページにアタッチしている際によく使いますが、ブラウザツールボックスでインタプリタを用いるのは一般に難しくなります(ブラウザツールボックスのコンソールは、デバッグしたい特定のアドオンだけではなく、ブラウザ全体をスコープとしてしまうため)。

とはいえ、次のようなトリックを使うと上手くいきます。デバッガがブレークポイントで停止している間は、そのプログラムにコンソールのスコープが設定されます。そのため、アドオンのコードにブレークポイントを設定しておくことで、アドオン中の関数を呼び出したり、変数値を再代入したりするなど、アドオンに対して動的にアクセスすることができます。

この機能は コンソールを常時表示 (画面の半分にはコンソールを、もう半分にはデバッガなどの異なるツールを表示)している際に特に効果的です。

コンテンツスクリプトをデバッグする

ブラウザツールボックスには大きな制約が 1 つあります。それは、マルチプロセス Firefox で開発している場合に、 JavaScript Debugger からコンテンツスクリプトにアタッチできない点です。

マルチプロセス Firefox では少なくとも 2 つのプロセスに分かれています。一つはブラウザ自身の UI やシステムコードを実行し、他は Web ページのスクリプト実行などを担当するコンテンツプロセス です。ブラウザツールボックスは前者のプロセスにデバッガとしてアタッチします。しかし、コンテンツスクリプトは他のプロセスで実行しているため、ブラウザツールボックスのスクリプト一覧には表示されないのです。

コンテンツスクリプトスクリプトをマルチプロセス Firefox でデバッグするには Browser Content Toolbox を使用して下さい。Browser Content Toolbox はブラウザツールボックスにちょうど似ていますが、開発ツールをブラウザのコンテンツプロセスにアタッチさせる点で異なり、コンテンツスクリプトにアクセスできるようになります。

補足: この Browser Content Toolbox は、マルチプロセス Firefox で開発している場合にのみ必要なものであり、またその場合のみ利用可能です。

ブラウザツールボックスのオプションで "Worker のデバッグを有効" を設定すると、Browser Content Toolbox でデバッグができなくなります。この問題は Bug 1236892 で解決されるはずです。

ポップアップをデバッグする

Firefox 47 からの新機能です

Firefox 47 から、ブラウザツールボックスでポップアップの中身をデバッグできるようになりました。デバッグは 3 つの手順からなります。

  • パネルの autohide を無効化する
  • ポップアップを開く
  • ポップアップを含んだドキュメントを選択する

autohide を無効化する

パネルのデバッグに関してありがちな問題は、パネルの外をクリックすると隠れてしまう点です。そのため、まず初めにこの動作を無効化しておきましょう。ブラウザツールボックスで 4 つの小さい四角形からなるアイコンをクリックします。

すると、Escape キーを押した場合でもパネルが前面に表示されたままになるはずです。

ここで設定した authohide の無効化は、アドオンのポップアップのみならず、ハンバーガーメニュー () などによる ブラウザ本体のポップアップ にも適用されます。

また、この設定はブラウザを再起動した後も引き継がれます。この件に関しては bug 1251658 で修正中ですが、現時点ではブラウザツールボックスを閉じる前に autohide を再び有効にしておくと良いでしょう。

ブラウザの内部構造的には、この autohide ボタンは ui.popup.disable_autohide の設定項目を切り替えるだけのものです。そのため、about:config において手動で切り替えることも可能です。

ポップアップを開く

次にポップアップを開きます。ここでブラウザツールボックスに戻ると、パネルが開いたままになっているはずです。

ポップアップのフレームを選択する

ポップアップはそれ自身のフレームに読み込まれています。そのため、ブラウザツールボックスの フレーム選択ボタン でポップアップのドキュメントを選択します。このドキュメントは以下のような名前を持っています。

moz-extension://<some-uuid>/path/to/your-popup.html

こうしてツールボックスのスコープがポップアップに設定されました。インスペクタでポップアップの HTML や CSS の確認・変更が行えます。デバッガでは、ポップアップに読み込まれているスクリプトを検索したり、スクリプトにブレークポイントを設定することができます。

Add-on Debuggerとは?

Firefox でのアドオンのデバッグは、今後 Add-on Debugger が用いられる予定になっています。

ブラウザツールボックスと比較した際、Add-on Debugger はアドオンファイルのみを表示するため、容易にスクリプトを探すことができるという大きな利点があります。しかし今のところ、コンソールメッセージをアドオンから Add-on Debugger へ表示させられないため、ブラウザツールボックスのほうが便利です。

ドキュメントのタグと貢献者

 このページの貢献者: hashedhyphen, lv7777
 最終更新者: hashedhyphen,