HTML-Dateien mit emrun ausführen

emrun ist ein Kommandozeilen-Tool, das generierte HTML-Seiten über einen lokal gestarteten Webserver ausführen kann. Dies ist hilfreich bei Webbrowsern, die eine generierte .html-Datei aufgrund der standardmäßigen Browser-CORS-Regeln nicht über eine file://-URL (z. B. durch Doppelklick auf die Datei) ausführen können.

emrun ermöglicht zudem alle Arten der Kommandozeilen-Automatisierung, zum Beispiel die Integration von Unit-Tests in eine Emscripten-Umgebung innerhalb einer Projekt-Build-Farm.

Funktionen

emrun unterstützt die folgenden Anwendungsfälle

  • Starten Sie Ihre mit Emscripten generierte HTML-Seite über die Kommandozeile in einem Webbrowser.

  • Erfassen Sie während der Ausführung die stdout- und stderr-Streams der Anwendung und geben Sie diese im Terminal aus oder protokollieren Sie sie in einer Datei.

  • Übergeben Sie Kommandozeilenargumente an die Anwendung und lesen Sie diese aus GET-Parametern in der aufgerufenen URL oder über argc und argv in main() aus.

  • Erkennen Sie, wenn eine gestartete Anwendung durch einen Aufruf von Cs exit(returncode) beendet wird, und geben Sie den angegebenen Rückgabecode an das Terminal weiter.

  • Wählen Sie aus, welcher installierte Browser ausgeführt werden soll, oder führen Sie einen Browser auf einem Android-Gerät aus, das über adb mit dem lokalen Computer verbunden ist.

Kurzanleitung

Die Verwendung von emrun ist einfach

  1. Erstellen Sie Ihre Emscripten-Anwendung neu und fügen Sie das --emrun Linker-Flag hinzu.

Dieses Flag injiziert Code in das generierte Module-Objekt, um die Erfassung von stdout, stderr und exit() zu ermöglichen.

Hinweis

Wenn Sie diesen Schritt überspringen, können Sie trotzdem jede .html-Datei mit emrun ausführen, aber die Erfassung wird nicht funktionieren.

  1. Öffnen Sie ein Terminal, navigieren Sie zum Build-Ausgabeverzeichnis und rufen Sie emrun page.html auf.

Dadurch wird ein neuer Webserver gestartet, um die Seite bereitzustellen, und Ihr Standard-Systembrowser wird geöffnet, um diese Seite aufzurufen. emrun blockiert so lange, bis die Seite exit(returncode) aufruft, und kehrt danach mit dem angegebenen Prozess-Exit-Code zur Shell zurück.

Auswahl des auszuführenden Browsers

Die Kommandozeilenoption --browser <dateiname-oder-browser-alias> ermöglicht es Ihnen, eine HTML-Datei mit einem bestimmten Browser zu starten, indem Sie entweder dessen „Browser-Alias“ oder den vollständigen Pfad zu seiner ausführbaren Datei angeben (wenn das Flag nicht angegeben wird, wird der Standard-Systembrowser gestartet).

Um die Liste der Browser-Aliase auf Ihrem System aufzuzählen, verwenden Sie den Befehl --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

Hinweis

Damit Ihr Browser erkannt wird, sollte er im Standard-Installationsverzeichnis des Systems installiert sein (%ProgramFiles% unter Windows und /Applications/ unter macOS) oder zum PATH des aktuellen Benutzers hinzugefügt worden sein.

Sie können die Option --browser <alias> übergeben, um mit einem bestimmten Browser zu starten. Um beispielsweise den Browser Firefox Nightly auszuführen, würden Sie folgenden Aufruf verwenden

emrun --browser firefox_nightly page.html

Um den Start über den Dateinamen eines Browsers durchzuführen, verwenden Sie

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

Wenn Sie lediglich einen Webserver starten möchten, können Sie das Kommandozeilen-Flag --no_browser übergeben. In diesem Fall führt emrun den Server aus, ohne den Browser zu starten (dies ähnelt der Verwendung eines lokalen Webservers).

Sicherheitsrelevante Auswirkungen

emrun startet einen eigenen Webserver, um die Ziel-.html-Datei bereitzustellen. Dies hat die folgenden sicherheitsrelevanten Auswirkungen

  • Der Webserver ist ein generischer Dateiserver, der standardmäßig alle Dateien in dem Verzeichnis, in dem sich die .html-Datei befindet, sowie alle Verzeichnisse unterhalb dieses Verzeichnisbaums bereitstellt.

  • Der Webserver ist für andere Computer im selben Netzwerk sichtbar.

Steuerung des Webserver-Betriebs

Die folgenden Kommandozeilen-Flags steuern, wie emrun den Webserver startet

  • --no_server: Keinen Webserver starten. Die Zieldatei wird, sofern möglich, über das file://-Protokoll ausgeführt.

  • --serve_after_close: emrun nicht beenden; der Server läuft weiter, auch nachdem der Benutzer den Webbrowser geschlossen hat. Verwenden Sie dieses Flag, wenn Sie die Seite während desselben Laufs mehrmals oder mit verschiedenen Browsern besuchen möchten.

  • --serve_after_exit: emrun nicht beenden; der Server läuft weiter, nachdem die Seite mit einem Aufruf von exit(returncode) beendet wurde.

  • --serve_root <path>: Geben Sie ein benutzerdefiniertes Verzeichnis an, das als Stammverzeichnis für den gestarteten Webserver verwendet werden soll. Standardmäßig wird das Verzeichnis verwendet, in dem sich die .html-Datei befindet.

  • --port <number>: Geben Sie den TCP-Port des Webservers an. Der Standard-Port ist 6931.

  • --silence_timeout <seconds>: Geben Sie den emrun-Inaktivitäts-Timeout an. Wenn die Anwendung in dieser Zeit (in Sekunden) nichts auf stdout oder stderr ausgibt, wird davon ausgegangen, dass die Seite/der Browser hängt, und emrun wird beendet. Dies ist standardmäßig deaktiviert.

  • --timeout <seconds>: Geben Sie den emrun-Timeout an. Wenn der gesamte Seitenlauf länger als diese Anzahl an Sekunden dauert, wird davon ausgegangen, dass die Seite/der Browser hängt, und emrun wird beendet. Dies ist standardmäßig deaktiviert.

  • --hostname <name>: Geben Sie den TCP-Hostnamen des Webservers an. Der Standard-Hostname ist localhost.

  • --timeout_returncode <code>: Gibt den Prozess-Rückgabecode an, mit dem emrun beendet wird, wenn ein Timeout beim Seitenlauf auftritt. Standardmäßig ist dies 99999.

Protokollausgabe steuern

Die folgenden Kommandozeilen-Flags beeinflussen die Protokollausgabe

  • --verbose: Detaillierte Informationen über die internen Schritte von emrun ausgeben.

  • --log_stdout <filename>: Alle stdout-Nachrichten der Anwendung in die angegebene Datei schreiben (anstatt sie im Terminal auszugeben).

  • --lot_stderr <filename>: Alle stderr-Nachrichten der Anwendung in die angegebene Datei schreiben (anstatt sie im Terminal auszugeben).

  • --system_info: Detaillierte Informationen über das aktuelle System vor dem Start ausgeben. Dies ist nützlich bei automatisierten Läufen, wenn Sie Hardware-Informationen in Protokollen erfassen möchten.

  • --browser_info: Informationen darüber ausgeben, welcher Browser gestartet wird.

  • --no_emrun_detect: Die Warnmeldung ausblenden, die erscheint, wenn erkannt wird, dass eine Ziel-.html-Datei nicht mit --emrun erstellt wurde.

Aufräumen nach dem Durchlauf

Diese Kommandozeilen-Flags ermöglichen es Ihnen, offene Browser-Prozesse vor dem Start eines neuen Laufs zu beenden – dies ist wichtig für automatisierte Tests auf Build-Servern

  • --kill_start: Alle Instanzen des Zielbrowser-Prozesses vor dem Start des Laufs beenden. Verwenden Sie dieses Flag, um sicherzustellen, dass keine alten (hängenden) Instanzen des Zielbrowsers existieren, die den aktuellen Lauf stören könnten. Dies ist standardmäßig deaktiviert.

  • --kill_exit: Alle Instanzen des Zielbrowser-Prozesses beenden, wenn emrun beendet wird. Verwenden Sie dieses Flag, um sicherzustellen, dass Browser-Seiten nach Abschluss des Laufs geschlossen werden. Dies ist standardmäßig deaktiviert. Beachten Sie, dass es bei der Verwendung von --kill_exit notwendig sein kann, explizit die Option --browser=/pfad/zum/browser zu verwenden, da das Beenden andernfalls möglicherweise nicht ordnungsgemäß funktioniert.

Warnung

Diese Operationen führen dazu, dass der Browser-Prozess zwangsweise beendet wird. Alle geöffneten Fenster oder Tabs werden geschlossen, auch solche, die möglicherweise ungespeicherte Daten enthalten.

Webseiten in Firefox ausführen

Wenn Sie Webseiten über emrun mit Firefox ausführen, möchten Sie möglicherweise eine oder mehrere der folgenden Browser-Einstellungen (Prefs) festlegen

; Make sure to unblock popups being spawned from https:///.
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

Um eine Firefox-Browser-Einstellung festzulegen, navigieren Sie in der Adressleiste des Browsers zur Seite about:config.

Webseiten auf einem Android-Gerät ausführen

emrun kann browserbasierte Tests auf Android automatisieren.

Damit dies funktioniert, müssen Sie

  • Ein Android-Telefon über USB mit dem lokalen System verbinden und den Entwicklermodus aktivieren. Es ist nicht erforderlich, das Telefon zu rooten.

  • Das Tool adb auf dem Host-System installieren und sicherstellen, dass es in der Umgebungsvariable PATH vorhanden ist.

  • Überprüfen, ob adb funktioniert, indem Sie adb devices aufrufen, um zu sehen, ob Ihr Gerät aufgelistet wird.

  • Installieren Sie eine beliebige Browser-APK auf dem Gerät, die Sie ausführen möchten.

Um auf Android auszuführen, fügen Sie das Kommandozeilen-Flag --android hinzu und verwenden Sie das Flag --browser <alias>, um explizit den richtigen Browser für die Ausführung auszuwählen.

Hinweis

Das Weglassen von --browser (um einen Standard-Android-Browser zu starten) wird nicht unterstützt.

Hinweis

Beim Ausführen auf Android wird die Option --hostname ignoriert.

Die folgenden Browser-Aliase wurden getestet und funktionieren nachweislich: firefox, firefox_beta, firefox_aurora, firefox_nightly, chrome, chrome_beta, opera.

Die folgenden Browser-Aliase werden ebenfalls unterstützt, haben jedoch bekannte Probleme

  • opera_mini: Der Browser startet, aber aus irgendeinem Grund tritt ein Timeout beim Versuch auf, eine Seite zu laden.

  • dolphin: Funktioniert, unterstützt aber kein WebGL.

Ansonsten entspricht die Verwendung von emrun für browserbasierte Tests auf Android der Vorgehensweise beim Testen auf dem Host-System.