使用 emrun 运行 HTML 文件

emrun 是一个命令行工具，可以通过本地启动的 Web 服务器运行生成的 HTML 页面。这在使用无法通过 file:// URL（例如，通过双击文件）运行生成的 .html 文件的 Web 浏览器时很有用，因为默认的浏览器 CORS 规则。

emrun 还支持各种命令行自动化，例如，将单元测试集成到项目构建农场中的 Emscripten 环境中。

功能

emrun 支持以下用途

  • 从命令行在 Web 浏览器中启动 Emscripten 生成的 HTML 页面。

  • 在运行期间捕获应用程序 stdout 和 stderr 流，并将它们打印到终端或记录到文件中。

  • 将命令行参数传递给应用程序，并从启动的 URL 中的 GET 参数，或 argc 和 argv 中的 main() 中读取这些参数。

  • 检测何时通过调用 C 的 exit(returncode) 来退出启动的应用程序，然后将指定的返回码传递给终端。

  • 选择要运行的已安装浏览器，甚至可以通过 adb 运行连接到本地计算机的 Android 设备上的浏览器。

快速入门

使用 emrun 很简单

  1. 重新构建 Emscripten 应用程序，并添加 --emrun 链接器标志。

此标志将代码注入生成的 模块对象 中，以启用捕获 stdout、stderr 和 exit()。

注意

如果跳过此步骤，你仍然可以使用 emrun 运行任何 .html 文件，但捕获将不起作用。

  1. 打开一个终端，导航到构建输出目录，并调用 emrun page.html。

这将生成一个新的 Web 服务器来托管页面，并启动你的默认系统浏览器以访问该页面。emrun 将阻塞，直到页面调用 exit(returncode)，之后它将使用给定的进程退出代码退出回 shell。

选择要运行的浏览器

--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 生成自己的 Web 服务器来托管目标 .html 文件。这具有以下安全隐患

  • 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 中运行网页

通过 emrun 使用 Firefox 运行网页时，你可能希望设置以下一个或多个浏览器首选项

; 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 进行基于浏览器的测试与在主机系统上测试时相同。