emrunを使用したHTMLファイルの実行

emrunは、ローカルで起動したウェブサーバーを介して生成されたHTMLページを実行できるコマンドラインツールです。これは、デフォルトのブラウザのCORSルールのため、file:// URL（例：ファイルをダブルクリック）を介して生成された.htmlファイルを実行できないウェブブラウザを使用する場合に役立ちます。

emrunは、あらゆる種類のコマンドライン自動化を可能にします。たとえば、プロジェクトビルドファームでEmscripten環境にユニットテストを統合することができます。

機能

emrunは次の用途をサポートしています。

  • コマンドラインからウェブブラウザでEmscriptenで生成されたHTMLページを起動します。

  • 実行中のアプリケーションのstdoutとstderrストリームを取得し、ターミナルに出力するか、ファイルにログ記録します。

  • アプリケーションにコマンドライン引数を渡して、起動されたURLのGETパラメータ、またはmain()内のargcとargvからそれらを読み取ります。

  • Cのexit(returncode)を呼び出すことによって起動されたアプリケーションが終了したことを検出し、指定された戻りコードをターミナルに渡します。

  • インストールされているブラウザを選択して実行するか、adbを介してローカルコンピュータに接続されたAndroidデバイスでブラウザを実行することもできます。

クイックスタート

emrunの使用は簡単です。

  1. Emscriptenアプリケーションを再ビルドし、リンカフラグである--emrunを追加します。

このフラグは、stdout、stderr、exit()のキャプチャを有効にするコードを生成されたModuleオブジェクトに挿入します。

注記

この手順をスキップした場合でも、emrunで任意の.htmlファイルを実行できますが、キャプチャは機能しません。

  1. ターミナルを開き、ビルド出力ディレクトリに移動して、emrun page.htmlと呼び出します。

これにより、ページをホストする新しいWebサーバーが生成され、デフォルトのシステムブラウザが起動してそのページにアクセスします。emrunは、ページがexit(returncode)を呼び出すまでブロックし、その後、指定されたプロセスの終了コードと共にシェルに戻ります。

実行するブラウザの選択

--browser <filename-or-browser-alias>コマンドラインオプションを使用すると、その「ブラウザエイリアス」または実行可能ファイルのフルパスを指定することで、特定のブラウザを使用してHTMLファイルを実行できます（フラグが指定されていない場合は、デフォルトのシステムブラウザが起動します）。

システム上のブラウザエイリアスのリストを列挙するには、--list_browsersコマンドを使用します。

> emrun --list_browsers

emrun has automatically found the following browsers in the default install locations on the system:

- firefox: Mozilla Firefox 26.0.0.5087
- firefox_beta: Mozilla Firefox 26.0.0.5077
- firefox_aurora: Mozilla Firefox Aurora 28.0.0.5098
- firefox_nightly: Mozilla Firefox Nightly 29.0.0.5098
- chrome: Google Chrome 31.0.1650.63
- chrome_canary: Google Chrome 34.0.1752.0
- iexplore: Microsoft Internet Explorer 11.0.9600.16384
- opera: Opera 18.0.1284.63

注記

ブラウザを検出するには、システムのデフォルトのインストール場所にインストールされている必要があります（Windowsでは%ProgramFiles%、macOSでは/Applications/）または現在のユーザーのPATHに追加する必要があります。

指定したブラウザで起動するには、--browser <alias>オプションを渡すことができます。たとえば、Firefox Nightlyブラウザを実行するには、次のように呼び出します。

emrun --browser firefox_nightly page.html

ブラウザのファイル名を使用して起動するには、次のようにします。

--browser /path/to/browser/executable page.html

Webサーバーだけを起動する場合は、--no_browserコマンドラインフラグを渡すことができます。この場合、emrunはブラウザを生成せずにサーバーを実行します（これはローカルWebサーバーを使用する場合と同様です）。

セキュリティ上の考慮事項

emrunは、ターゲットの.htmlファイルをホストするための独自のWebサーバーを生成します。これには、次のセキュリティ上の考慮事項があります。

  • Webサーバーは一般的なファイルサーバーであり、デフォルトでは.htmlファイルが存在するディレクトリとそのディレクトリツリーの下にあるすべてのディレクトリのすべてのファイルをサービスします。

  • Webサーバーは、同じネットワーク上の他のコンピュータからアクセスできます。

Webサーバー動作の制御

次のコマンドラインフラグは、emrunがWebサーバーを生成する方法を制御します。

  • --no_server：Webサーバーを起動しません。可能であれば、ターゲットファイルはfile://プロトコルを介して実行されます。

  • --serve_after_close：emrunを終了しません。ユーザーがWebブラウザを閉じた後も、サーバーの実行を続けます。同じ実行中にページを複数回、または異なるブラウザでアクセスする場合に使用します。

  • --serve_after_exit：emrunを終了しません。ページがexit(returncode)を呼び出して終了した後も、サーバーの実行を続けます。

  • --serve_root <path>：生成されたWebサーバーのルートディレクトリとして使用するカスタムディレクトリを指定します。デフォルトでは、.htmlファイルが存在するディレクトリが使用されます。

  • --port <number>：WebサーバーのTCPポートを指定します。デフォルトのポートは6931です。

  • --silence_timeout <seconds>：emrunのサイレントタイムアウトを指定します。アプリケーションがこれだけの秒数内にstdoutまたはstderrに何も出力しない場合、ページ/ブラウザはハングしているものと見なされ、emrunは終了します。デフォルトでは無効になっています。

  • --timeout <seconds>：emrunのタイムアウトを指定します。ページの実行全体がこれだけの秒数を超える場合、ページ/ブラウザはハングしているものと見なされ、emrunは終了します。デフォルトでは無効になっています。

  • --hostname <name>：WebサーバーのTCPホスト名を指定します。デフォルトのホスト名はlocalhostです。

  • --timeout_returncode <code>：ページ実行のタイムアウトが発生した場合にemrunが終了するプロセスの戻りコードを指定します。デフォルトは99999です。

ログ出力の制御

次のコマンドラインフラグは、ログ出力を変更します。

  • --verbose：emrunの内部手順に関する詳細情報を表示します。

  • --log_stdout <filename>：アプリケーションからのすべてのstdoutメッセージを、指定されたファイルに書き込みます（ターミナルに出力する代わりに）。

  • --lot_stderr <filename>：アプリケーションからのすべてのstderrメッセージを、指定されたファイルに書き込みます（ターミナルに出力する代わりに）。

  • --system_info: 起動前に現在のシステムに関する詳細情報を表示します。これは、ハードウェア情報をログに記録したい自動実行時に役立ちます。

  • --browser_info: 起動しようとしているブラウザに関する情報を表示します。

  • --no_emrun_detect: ターゲットの.htmlファイルが--emrunでビルドされていないと検出された場合に表示される警告メッセージを非表示にします。

実行後のクリーンアップ

これらのコマンドラインフラグを使用すると、新しい実行を開始する前に開いているブラウザプロセスをクリーンアップできます。これは、ビルドサーバーでの自動テストにとって重要です。

  • --kill_start: 実行を開始する前に、ターゲットブラウザプロセスのすべてのインスタンスを終了します。このフラグを渡すと、現在の実行を妨げる可能性のある古い（ハングした）ターゲットブラウザプロセスのインスタンスが存在しないことが保証されます。デフォルトでは無効になっています。

  • --kill_exit: emrunが終了するときに、ターゲットブラウザプロセスのすべてのインスタンスを終了します。このフラグを渡すと、実行が終了したときにブラウザページが閉じられます。デフォルトでは無効になっています。--kill_exitを使用する場合は、--browser=/path/to/browserコマンドラインオプションを明示的に使用する必要がある場合もあります。それ以外の場合は、終了が正しく機能しない可能性があります。

警告

これらの操作により、ブラウザプロセスが強制的に終了されます。開いているウィンドウやタブはすべて閉じられます。保存されていないデータが含まれている可能性のあるタブも含まれます。

Firefoxでのウェブページの実行

Firefoxを使用してemrunでウェブページを実行する場合は、次のブラウザプリファレンスの1つ以上を設定することをお勧めします。

; Make sure to unblock popups being spawned from http://localhost/.
browser.popups.showPopupBlocker;false

; Don't ask the user to change the default browser when spawning the browser.
browser.shell.checkDefaultBrowser;false

; Don't autorestore previous tabs, just open the one from the command line.
browser.sessionstore.resume_from_crash;false
services.sync.prefs.sync.browser.sessionstore.restore_on_demand;false
browser.sessionstore.restore_on_demand;false

; Don't bring up the modal "Start in Safe Mode" dialog after browser is killed, since
; that is an expected path for --kill_start and --kill_exit options.
browser.sessionstore.max_resumed_crashes;-1
toolkit.startup.max_resumed_crashes;-1

; Don't fail on long-running scripts, but have emrun instead control execution termination.
dom.max_script_run_time;0
dom.max_chrome_script_run_time;0

; Accelerate browser update background timer tick so that autoupdates take place as quickly as possible.
; This is useful for continuous integration servers wanting to always test the latest browser version.
app.update.download.backgroundInterval;1

; Always run in private browsing mode to avoid caching any pages (but also disables IndexedDB persistency!).
browser.privatebrowsing.autostart;true

; When switching between multiple Firefox browser versions/channels, suppress showing the first time welcome page.
startup.homepage_override_url;about:blank
startup.homepage_welcome_url;about:blank

Firefoxブラウザプリファレンスを設定するには、ブラウザのナビゲーションバーでabout:configページに移動します。

Androidデバイスでのウェブページの実行

emrunは、Androidでのブラウザベースのテストを自動化できます。

これを実現するには、次の手順が必要です。

  • 開発者モードを有効にして、USB経由でAndroid電話をローカルシステムに接続します。電話をルート化する必要はありません。

  • ホストシステムにadbツールをインストールし、PATH環境変数に存在することを確認します。

  • adb devicesを呼び出して、デバイスが一覧表示されていることを確認することにより、adbが機能していることを確認します。

  • 実行したいブラウザのapkをデバイスにインストールします。

Androidで実行するには、--androidコマンドラインフラグを追加し、--browser <alias>コマンドラインフラグを使用して、実行する正しいブラウザを明示的に選択します。

注記

--browserを省略して（デフォルトのAndroidブラウザを起動するには）はサポートされていません。

注記

Androidで実行すると、--hostnameオプションは省略されます。

次のブラウザエイリアスはテストされており、動作することがわかっています：firefox, firefox_beta, firefox_aurora, firefox_nightly, chrome, chrome_beta, opera。

次のブラウザエイリアスもサポートされていますが、既知の問題があります。

  • opera_mini: ブラウザは起動しますが、何らかの理由でページの読み込みを試行するとタイムアウトします。

  • dolphin: 動作しますが、WebGLをサポートしていません。

それ以外の場合、Androidでのブラウザベースのテストにemrunを使用するのは、ホストシステムでテストする場合と同じです。