--- title: SpecialPowers slug: Mozilla/Projects/Mochitest/SpecialPowers tags: - Mochistest - NeedsContent - QA - 'QA:Tools' - Reference translation_of: Mozilla/Projects/Mochitest/SpecialPowers ---

SpecialPowers は Mochitest のテストで利用可能な API 群の 1 つです。Mochitest は通常の Web ページとしてかけるようにする予定です。しかし、セキュリティ的な理由から権限の無い通常の Web ページではテストできないものもあります。そういった場合に SpecialPowers API を使う事で通常の Web ページでは触れることのできない操作をすることができます。

もし Mochitest で幅広い権限を必要とするテストをする場合は、変りに Chrome Mochitest を使う方が良いでしょう。

Method overview

Preference APIs

void pushPrefEnv(inPrefs, callback);

void popPrefEnv(callback);

void flushPrefEnv(callback);

bool getBoolPref(aPrefName);

int getIntPref(aPrefName);

string getCharPref(aPrefName);

any getComplexValue(aPrefName);

void setBoolPref(aPrefName, aValue);

void setIntPref(aPrefName, aValue);

void setCharPref(aPrefName, aValue);

void setComplexValue(aPrefName, aValue);

void clearUserPref(aPrefName);

Permission APIs

void pushPermissions(inPermissions, callback);

void popPermissions(callback);

void flushPermissions(callback);

void addPermission(type, allow, arg);

void removePermission(type, arg);

bool hasPermission(type, arg);

bool testPermission(type, value, arg);

void setFullscreenAllowed(document);

void removeFullscreenAllowed(document);

Event Listener / Observer APIs

TBD

Garbage Collection APIs

TBD

Privilege Wrapper APIs

Object wrap(Object);

XPCOM Components APIs

Cc

Ci

Cr

Cu

Log APIs

TBD

Environment APIs

bool isMainProcess();

string getMozFullPath(file);

bool isWindowPrivate(aWindow);

bool isBackButtonEnabled(aWindow);

int assertionCount();

void removeExpectedCrashDumpFiles(aExpectingProcessCrash);

string[] findUnexpectedCrashDumpFiles();

Focus Management APIs

TBD

Mock APIs

TBD

Form History APIs

TBD

Snapshot APIs

TBD

Clipboard APIs

TBD

Console APIs

TBD

Layout APIs

TBD

Frame Message APIs

TBD

Apps APIs

TBD

Other APIs

XMLHttpRequest createSystemXHR();

void quit();

DOMWindowUtils getDOMWindowUtils(window);

void executeSoon(aFun, aWindow);

object getDOMRequestService();

void openDialog(aWindow, aArg);

string sanityCheck();

Attributes

Attribute	Type	Description
`DOMWindowUtils`
`Services`

Methods

Preference APIs

内部的に、このメソッドがどのように使われているかは {{ interface("nsIPrefBranch") }} のドキュメントを参照してください。

`getBoolPref(aPrefName)`

boolean 型として aPrefName のプリファレンス値を取得します。

`getIntPref(aPrefName)`

integer 型として aPrefName のプリファレンス値を取得します。

`getCharPref(aPrefName)`

string 型として aPrefName のプリファレンス値を取得します。

`getComplexValue(aPrefName)`

XPCOM オブジェクトとして aPrefName のプリファレンス値を取得します。

`setBoolPref(aPrefName, aValue)`

boolean 型の aValue を aPrefName をキーとしてプリファレンスへ設定します。

`setIntPref(aPrefName, aValue)`

integer 型の aValue を aPrefName をキーとしてプリファレンスへ設定します。

`setCharPref(aPrefName, aValue)`

string 型の aValue を aPrefName をキーとしてプリファレンスへ設定します。

`setComplexValue(aPrefName, aValue)`

XPCOM オブジェクトの aValue を aPrefName をキーとしてプリファレンスへ設定します。

`clearUserPref(aPrefName)`

aPrefName のプリファレンス値を初期値に戻します。

Permission APIs

TBD

Event Listener / Observer APIs

`addChromeEventListener(type, listener, capture, allowUntrusted)`

TabChildGlobal オブジェクトにイベントリスナーを登録します。

`removeChromeEventListener(type, listener, capture)`

TabChildGlobal オブジェクトからイベントリスナーを除去します。

Garbage Collection APIs

`gc()`

強制的にガベージコレクションを発生させます。

Privilege Wrapper APIs

`Object wrap(Object)`

chrome オブジェクトにアクセスするために chrome オブジェクトをラップします。(例えば) XPCOM コンポーネントを返すメソッドの戻り値にアクセスするためには必要です。

XPCOM Components APIs

`Cc`

Components.classes の値を取得できます。これは chrome コード内で取得できるものと同じです。

`Ci`

Components.interfaces の値を取得できます。これは chrome コード内で取得できるものと同じです。

`Cr`

Components.results の値を取得できます。これは chrome コード内で取得できるものと同じです。

`Cu`

Components.utils の値を取得できます。これは chrome コード内で取得できるものと同じです。

Log APIs

TBD

Environment APIs

TBD

Focus Management APIs

TBD

Mock APIs

`MockFilePicker`

これは読み込み・保存のコードをテストするために、標準 File Picker をスクリプトで制御可能にするものに置換します。これを使うと、以下のコードをテストすることができます。

var MockFilePicker = SpecialPowers.MockFilePicker;
MockFilePicker.reset(); // You must call reset before each test

このパッチではMockFilePicker の使い方と XPCShell テストの使い方の良い例です。 testing/mochitest/MockFilePicker.jsm のコードが参考になるでしょう。

Form History APIs

TBD

Snapshot APIs

TBD

Clipboard APIs

TBD

Console APIs

TBD

Layout APIs

TBD

Frame Message APIs

`loadChromeScript()`

TBD

Apps APIs

TBD

Other APIs

`createSystemXHR()`

完全な "system privileges" を持った XMLHttpRequest を生成して返します。言い換えれば以下の事が可能になります。

制限なくクロスサイトリクエスト (cross-site requests) を要求できます。すなわちターゲットとなるサーバーは CORS をサポートする必要がありません。
xhr.setRequestHeader を使ってどんなヘッダーでも追加することができます。
xhr.getResponseHeader と xhr.getAllResponseHedaders を使ってすべてのレスポンスにアクセスできます。
xhr.responseXML のプロパティを使って XUL コンテンツの読み込み・パースができます。
referer (sic) ヘッダー無しでリクエストを要求できます。もし referer ヘッダーを設定したい場合は、xhr.setRequestHeader を使って手動で設定する必要があります。

しかし、xhr オブジェクトをパースしたドキュメントや xhr.responseXML からアクセスしたドキュメントは null principal として生成されています。そのため、ドキュメントでできることに制限があります。

`sanityCheck()`

"foo" という文字列を返します。

Adding new APIs

もし現在定義されていない権限が必要な関数をテストしたい場合、SpecialPowers オブジェクトに新しい API を追加することができます。

SpecialPowers API は Electrolysis(e10s) プロジェクトでは前方互換として設計されています。そのためコンテンツは別プロセスとして動作します。(Firefox Mobile と同様)。変更したもの全てについてこれを考慮しなくてはいけません。考慮しない場合は許可されることは無いでしょう。

プロセス外 (out-of-process) のコンテンツをサポートするために、SpecialPowers の実装は以下の 2 つのファイルに分離されています。

親プロセスで常に動作する {{ Source("testing/specialpowers/components/SpecialPowersObserver.js", "SpecialPowersObserver.js") }}
コンテンツプロセスで動作し、コンテンツスクリプトである{{ Source("testing/specialpowers/content/specialpowers.js", "specialpowers.js") }}

両方のファイルは chrome 権限で実行されます。しかし XPCOM API は恐らくコンテンツプロセスでは利用できないでそう。もし特殊な API でそれを利用する場合は Electrolysis や Mobile チームに相談するべきです。プロセス間メッセージの仕組みについての情報を知りたい場合、 Message Manager のドキュメントを参照してください。

{{ interface("nsIScreenManager") }} インターフェイスの numberOfScreens をアクセス可能にする修正を例にしてみましょう。このインターフェイスはコンテンツアプリではアクセス不可能ですので、サンプルコードでそれを可能にしてみましょう。まず初めに、コンテンツで利用できるように SpecialPowers に新しい API を定義した方が良いでしょう。このオブジェクトは {{ Source("testing/specialpowers/content/specialpowers.js", "the content script") }} に定義します。

SpecialPowers は標準の JavaScript オブジェクトです。そのため、関数・属性・セッター・ゲッターを自由に追加することができます。特殊な __exposedProps__ property のようにアンダースコア("_") から始まるプロパティを定義することでプロパティを隠すことができます。アンダースコアから始まる関数もプライベートになります。

最初にSpecialPowers に numberOfScreens のゲッターを追加しましょう。単純に chrome プロセスにブロッキングメッセージを送信し、応答として値を返すだけです。

var SpecialPowers = {
  // existing APIs
  //...

  // Provide nsIScreenManager.numberOfScreens
  get numberOfScreens() {
    // You could pass additional parameters in the second parameter, consult the message manager documentation for more details.
    // Ideally this would be a memoizing getter, that's somewhat out of scope for this document.
    return sendSyncMessage("SPNumberOfScreens", {})[0];
  }
};

このとき、対応するメッセージのハンドラーを {{ Source("testing/specialpowers/components/SpecialPowersObserver.js", "chrome observer script") }} に定義する必要があります。SpecialPowersObserver.observe 関数の中で、以下の実在するメッセージを登録します。

// Register for any messages our API needs us to handle
messageManager.addMessageListener("SPPrefService", this);
messageManager.addMessageListener("SPNumberOfScreens", this);

そして、SpecialPowersObserver.receiveMessage 関数の中で、新しいメッセージの分岐を追加し結果を返します。

receiveMessage: function(aMessage) {
  switch(aMessage.name) {
    case "SPPrefService":
    // existing code...

    case "SPNumberOfScreens":
      var screenManager = Components.classes["@mozilla.org/gfx/screenmanager;1"]
                    .getService(Components.interfaces.nsIScreenManager);}
      return screenManager.numberOfScreens;

    default:

これで終わりです。
この修正を反映させるために、testing/mochitest ディレクトリを再ビルドする必要があるでしょう。これで Mochitest でSpecialPowers.numberOfScreens を利用することができるようになります。

新しい API を追加後に、このドキュメントに新 API の説明を書くことを忘れないで下さい。