この翻訳は不完全です。英語から この記事を翻訳 してください。
SpecialPowers は Mochitest のテストで利用可能な API 群の 1 つです。Mochitest は通常の Web ページとしてかけるようにする予定です。しかし、セキュリティ的な理由から権限の無い通常の Web ページではテストできないものもあります。そういった場合に SpecialPowers API を使う事で通常の Web ページでは触れることのできない操作をすることができます。
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
内部的に、このメソッドがどのように使われているかは 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 を追加することができます。
プロセス外 (out-of-process) のコンテンツをサポートするために、SpecialPowers の実装は以下の 2 つのファイルに分離されています。
- 親プロセスで常に動作する SpecialPowersObserver.js
- コンテンツプロセスで動作し、コンテンツスクリプト であるspecialpowers.js
両方のファイルは chrome 権限で実行されます。しかし XPCOM API は恐らくコンテンツプロセスでは利用できないでそう。もし特殊な API でそれを利用する場合は Electrolysis や Mobile チームに相談するべきです。プロセス間メッセージの仕組みについての情報を知りたい場合、 Message Manager のドキュメントを参照してください。
nsIScreenManager インターフェイスの numberOfScreens をアクセス可能にする修正を例にしてみましょう。このインターフェイスはコンテンツアプリではアクセス不可能ですので、サンプルコードでそれを可能にしてみましょう。まず初めに、コンテンツで利用できるように SpecialPowers に新しい API を定義した方が良いでしょう。このオブジェクトは the content script に定義します。
__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];
}
};
このとき、対応するメッセージのハンドラーを 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 を利用することができるようになります。