automation.rst (6649B)
1 .. -*- Mode: rst; fill-column: 80; -*- 2 3 Configuring GeckoView for Automation 4 #################################### 5 How to set environment variables, Gecko arguments, and Gecko preferences for automation and debugging. 6 7 .. contents:: :local: 8 9 Configuring GeckoView 10 ===================================== 11 12 GeckoView and the underlying Gecko engine have many, many options, switches, and toggles "under the hood". Automation (and to a lesser extent, debugging) can require configuring the Gecko engine to allow (or disallow) specific actions or features. 13 14 Some such actions and features are controlled by the `GeckoRuntimeSettings <https://mozilla.github.io/geckoview/javadoc/mozilla-central/org/mozilla/geckoview/GeckoRuntimeSettings.html>`_ instance you configure in your consuming project. For example, remote debugging web content via the Firefox Developer Tools is configured by `GeckoRuntimeSettings.Builder#remoteDebuggingEnabled <https://mozilla.github.io/geckoview/javadoc/mozilla-central/org/mozilla/geckoview/GeckoRuntimeSettings.Builder.html#remoteDebuggingEnabled(boolean)>`_ 15 16 Not all actions and features have GeckoView API interfaces. Generally, actions and features that do not have GeckoView API interfaces are not intended for broad usage. Configuration for these types of things is controlled by: 17 18 - environment variables in GeckoView's runtime environment 19 - command line arguments to the Gecko process 20 - internal Gecko preferences 21 22 Automation-specific configuration is generally in this category. 23 24 Running GeckoView with environment variables 25 ------------------------------------------------ 26 27 After a successful ``./mach build``, ``./mach run --setenv`` can be used to run GeckoView with 28 the given environment variables. 29 30 For example, to enable extended logging for ``JSComponentLoader``, run ``./mach 31 run --setenv MOZ_LOG=JSComponentLoader:5``. 32 33 Reading configuration from a file 34 ------------------------------------------------ 35 36 When GeckoView is embedded into a debugabble application (i.e., when your manifest includes ``android:debuggable="true"``), by default GeckoView reads configuration from a file named ``/data/local/tmp/$PACKAGE-geckoview-config.yaml``. For example, if your Android package name is ``com.yourcompany.yourapp``, GeckoView will read configuration from:: 37 38 /data/local/tmp/com.yourcompany.yourapp-geckoview-config.yaml 39 40 41 Configuration file format 42 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 43 44 The configuration file format is `YAML <https://yaml.org>`_. The following keys are recognized: 45 46 - ``env`` is a map from string environment variable name to string value to set in GeckoView's runtime environment 47 - ``args`` is a list of string command line arguments to pass to the Gecko process 48 - ``prefs`` is a map from string Gecko preference name to boolean, string, or integer value to set in the Gecko profile 49 50 .. code-block:: yaml 51 52 # Contents of /data/local/tmp/com.yourcompany.yourapp-geckoview-config.yaml 53 54 env: 55 MOZ_LOG: nsHttp:5 56 57 args: 58 - --marionette 59 - --profile 60 - "/path/to/gecko-profile" 61 62 prefs: 63 foo.bar.boolean: true 64 foo.bar.string: "string" 65 foo.bar.int: 500 66 67 68 Verifying configuration from a file 69 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 70 71 When configuration from a file is read, GeckoView logs to ``adb logcat``, like: :: 72 73 GeckoRuntime I Adding debug configuration from: /data/local/tmp/org.mozilla.geckoview_example-geckoview-config.yaml 74 GeckoDebugConfig D Adding environment variables from debug config: {MOZ_LOG=nsHttp:5} 75 GeckoDebugConfig D Adding arguments from debug config: [--marionette] 76 GeckoDebugConfig D Adding prefs from debug config: {foo.bar.baz=true} 77 78 79 When a configuration file is found but cannot be parsed, an error is logged and the file is ignored entirely. When a configuration file is not found, nothing is logged. 80 81 Controlling configuration from a file 82 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 83 84 By default, GeckoView provides a secure web rendering engine. Custom configuration can compromise security in many ways: by storing sensitive data in insecure locations on the device, by trusting websites with incorrect security configurations, by not validating HTTP Public Key Pinning configurations; the list goes on. 85 86 **You should only allow such configuration if your end-user opts-in to the configuration!** 87 88 GeckoView will always read configuration from a file if the consuming Android package is set as the current Android "debug app" (see ``set-debug-app`` and ``clear-debug-app`` in the `adb documentation <https://developer.android.com/studio/command-line/adb>`_). An Android package can be set as the "debug app" without regard to the ``android:debuggable`` flag. There can only be one "debug app" set at a time. To disable the "debug app" check, `disable reading configuration from a file entirely <#disabling-reading-configuration-from-a-file-entirely>`_. Setting an Android package as the "debug app" requires privileged shell access to the device (generally via ``adb shell am ...``, which is only possible on devices which have ADB debugging enabled) and therefore it is safe to act on the "debug app" flag. 89 90 To enable reading configuration from a file: :: 91 92 adb shell am set-debug-app --persistent com.yourcompany.yourapp 93 94 95 To disable reading configuration from a file: :: 96 97 adb shell am clear-debug-app 98 99 Enabling reading configuration from a file unconditionally 100 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 101 102 Some applications (for example, web browsers) may want to allow configuration for automation unconditionally, i.e., even when the application is not debuggable, like release builds that have ``android:debuggable="false"``. In such cases, you can use `GeckoRuntimeSettings.Builder#configFilePath`_ to force GeckoView to read configuration from the given file path, like: 103 104 .. code-block:: java 105 106 new GeckoRuntimeSettings.Builder() 107 .configFilePath("/your/app/specific/location") 108 .build(); 109 110 Disabling reading configuration from a file entirely 111 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 112 113 To force GeckoView to never read configuration from a file, even when the embedding application is debuggable, invoke `GeckoRuntimeSettings.Builder#configFilePath`_ with an empty path, like: 114 115 .. code-block:: java 116 117 new GeckoRuntimeSettings.Builder() 118 .configFilePath("") 119 .build(); 120 121 The empty path is recognized and no file I/O is performed. 122 123 124 .. _GeckoRuntimeSettings.Builder#configFilePath: https://mozilla.github.io/geckoview/javadoc/mozilla-central/org/mozilla/geckoview/GeckoRuntimeSettings.Builder.html#configFilePath(java.lang.String)