使用 emrun 執行 HTML 檔案

emrun 是一個命令列工具，可以透過本機啟動的網頁伺服器執行產生的 HTML 頁面。當使用無法透過 file:// URL (例如，按兩下檔案) 執行產生的 .html 檔案的網頁瀏覽器時，這會很有幫助，因為預設的瀏覽器 CORS 規則。

emrun 也支援各種命令列自動化，例如，將單元測試整合到專案建置農場中的 Emscripten 環境。

功能

emrun 支援下列用途

  • 從命令列在網頁瀏覽器中啟動您產生的 Emscripten HTML 頁面。

  • 在執行期間擷取應用程式 stdout 和 stderr 串流，並將其列印到終端機或記錄到檔案。

  • 將命令列引數傳遞給應用程式，並從啟動的 URL 中的 GET 參數讀取它們，或從 main() 中的 argc 和 argv 讀取它們。

  • 偵測到啟動的應用程式透過呼叫 C 的 exit(returncode) 結束時，然後將指定的傳回碼傳遞給終端機。

  • 選擇要執行的已安裝瀏覽器，甚至在透過 adb 連接到本機電腦的 Android 裝置上執行瀏覽器。

快速入門指南

使用 emrun 很簡單

  1. 重建您的 Emscripten 應用程式並加入 --emrun 連結器旗標。

此旗標會將程式碼注入產生的 模組物件，以啟用擷取 stdout、stderr 和 exit()。

注意

如果您跳過此步驟，您仍然可以使用 emrun 執行任何 .html 檔案，但擷取將無法運作。

  1. 開啟終端機，瀏覽至建置輸出目錄，並呼叫 emrun page.html。

這將產生一個新的網頁伺服器來託管頁面，並啟動您的預設系統瀏覽器來瀏覽該頁面。emrun 將會封鎖，直到頁面呼叫 exit(returncode)，之後它將會使用給定的處理程序結束代碼回到 shell。

選擇要執行的瀏覽器

--browser <檔案名稱或瀏覽器別名> 命令列選項可讓您透過指定其「瀏覽器別名」或其可執行檔的完整路徑 (如果未指定旗標，則會啟動預設系統瀏覽器) 來啟動使用特定瀏覽器的 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 <別名> 選項，以使用指定的瀏覽器啟動。例如，若要執行 Firefox Nightly 瀏覽器，您會呼叫

emrun --browser firefox_nightly page.html

若要使用瀏覽器的檔案名稱啟動，請使用

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

如果您只想啟動網頁伺服器，您可以傳遞 --no_browser 命令列旗標。在這種情況下，emrun 將會執行伺服器，而不會產生瀏覽器 (這類似於使用 本機網頁伺服器)。

安全性影響

emrun 會產生自己的網頁伺服器來託管目標 .html 檔案。這具有下列安全性影響

  • 網頁伺服器是一個通用的檔案伺服器，預設會提供 .html 檔案所在的目錄中的所有檔案，以及該目錄樹下的所有目錄。

  • 網頁伺服器對於同一網路上的其他電腦是可見的。

控制網頁伺服器操作

下列命令列旗標可控制 emrun 如何產生網頁伺服器

  • --no_server：不要啟動網頁伺服器。如果可能，目標檔案會透過 file:// 通訊協定執行。

  • --serve_after_close：不要結束 emrun；即使在使用者關閉網頁瀏覽器後，仍繼續執行伺服器。當您想要在同一次執行期間多次瀏覽頁面或使用不同的瀏覽器時，請使用此旗標。

  • --serve_after_exit：不要結束 emrun；在頁面呼叫 exit(returncode) 結束後，仍繼續執行伺服器。

  • --serve_root <路徑>：指定要用作產生網頁伺服器根目錄的自訂目錄。預設會使用 .html 檔案所在的目錄。

  • --port <數字>：指定網頁伺服器 TCP 連接埠。預設連接埠為 6931。

  • --silence_timeout <秒數>：指定 emrun 靜音逾時。如果應用程式在此許多秒數內沒有在 stdout 或 stderr 中列印任何內容，則會假設頁面/瀏覽器已停止回應，而 emrun 將會結束。預設會停用此設定。

  • --timeout <秒數>：指定 emrun 逾時。如果整個頁面執行時間超過此許多秒數，則會假設頁面/瀏覽器已停止回應，而 emrun 將會結束。預設會停用此設定。

  • --hostname <name>：指定網頁伺服器的 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 執行網頁時，您可能想要設定一個或多個下列瀏覽器偏好設定

; Make sure to unblock popups being spawned from https://127.0.0.1/.
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 手機連接到本機系統，並啟用其開發人員模式。無需 root 手機。

  • 在主機系統上安裝 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 進行瀏覽器測試與在主機系統上測試相同。