Magic-Mirror/gecko-dev
1
0
Fork 0
mirror of https://github.com/mozilla/gecko-dev.git synced 2025-02-26 04:09:50 +00:00
Code Issues Actions Packages Projects Releases Wiki Activity

Bug 1804219 - [remote] Clarify where to add remote preferences r=webdriver-reviewers,whimboo,Sasha

Browse Source 
Depends on D163891

Differential Revision: https://phabricator.services.mozilla.com/D163922
This commit is contained in:
Julian Descottes 2022-12-07 09:07:32 +00:00
parent ec74a5084d
commit dda315bf6a
3 changed files with 44 additions and 10 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

44
remote/shared/RecommendedPreferences.sys.mjs
View File

@ -33,14 +33,48 @@ if (Services.appinfo.processType != Ci.nsIXULRuntime.PROCESS_TYPE_DEFAULT) {
// Preferences are set for automation on startup, unless
// remote.prefs.recommended has been set to false.
//
// All prefs listed here have immediate effect, and don't require a restart
// nor have to be set in the profile before the application starts. If such a
// latter preference has to be added, it needs to be done for the client like
// Marionette client (geckoinstance.py), or geckodriver (prefs.rs).
//
// Note: Clients do not always use the latest version of the application. As
// such backward compatibility has to be ensured at least for the last three
// releases.
// INSTRUCTIONS TO ADD A NEW PREFERENCE
//
// Preferences for remote control and automation can be set from several entry
// points:
// - remote/shared/RecommendedPreferences.sys.mjs
// - remote/test/puppeteer/src/node/FirefoxLauncher.ts
// - testing/geckodriver/src/prefs.rs
// - testing/marionette/client/marionette_driver/geckoinstance.py
//
// The preferences in `FirefoxLauncher.ts`, `prefs.rs` and `geckoinstance.py`
// will be applied before the Application starts, and should typically be used
// for preferences which cannot be updated during the lifetime of the Application.
//
// The preferences in `RecommendedPreferences.sys.mjs` are applied after
// the Application has started, which means that the application must apply this
// change dynamically and behave correctly. Note that you can also define
// protocol specific preferences (CDP, WebDriver, ...) which are merged with the
// COMMON_PREFERENCES from `RecommendedPreferences.sys.mjs`.
//
// Additionally, users relying on the Marionette Python client (ie. using
// geckoinstance.py) set `remote.prefs.recommended = false`. This means that
// preferences from `RecommendedPreferences.sys.mjs` are not applied and have to
// be added to the list of preferences in that Python file. Note that there are
// several lists of preferences, either common or specific to a given application
// (Firefox Desktop, Fennec, Thunderbird).
//
// Depending on how users interact with the Remote Agent, they will use different
// combinations of preferences. So it's important to update the preferences files
// so that all users have the proper preferences.
//
// When adding a new preference, follow this guide to decide where to add it:
// - Add the preference to `geckoinstance.py`
// - If the preference has to be set before startup:
// - Add the preference to `prefs.rs`
// - Add the preference `FirefoxLauncher.ts`
// - Create a PR to upstream the change on `FirefoxLauncher.ts` to puppeteer
// - Otherwise, if the preference can be set after startup:
// - Add the preference to `RecommendedPreferences.sys.mjs`
const COMMON_PREFERENCES = new Map([
// Make sure Shield doesn't hit the network.
["app.normandy.api_url", ""],

7
testing/geckodriver/src/prefs.rs
View File

@ -6,11 +6,8 @@ use mozprofile::preferences::Pref;
// ALL CHANGES TO THIS FILE MUST HAVE REVIEW FROM A GECKODRIVER PEER!
//
// All preferences in this file are not immediately effective, and
// require a restart of Firefox, or have to be set in the profile before
// Firefox gets started the first time. If a preference has to be added,
// which is immediately effective, it needs to be done in Marionette
// (RecommendedPreferences.sys.mjs).
// Please refer to INSTRUCTIONS TO ADD A NEW PREFERENCE in
// remote/shared/RecommendedPreferences.sys.mjs
//
// Note: geckodriver is used out-of-tree with various builds of Firefox.
// Removing a preference from this file will cause regressions,

3
testing/marionette/client/marionette_driver/geckoinstance.py
View File

@ -4,6 +4,9 @@
# ALL CHANGES TO THIS FILE MUST HAVE REVIEW FROM A MARIONETTE PEER!
#
# Please refer to INSTRUCTIONS TO ADD A NEW PREFERENCE in
# remote/shared/RecommendedPreferences.sys.mjs
#
# The Marionette Python client is used out-of-tree with various builds of
# Firefox. Removing a preference from this file will cause regressions,
# so please be careful and get review from a Testing :: Marionette peer