| // <copyright file="FirefoxOptions.cs" company="Selenium Committers"> | |
| // Licensed to the Software Freedom Conservancy (SFC) under one | |
| // or more contributor license agreements. See the NOTICE file | |
| // distributed with this work for additional information | |
| // regarding copyright ownership. The SFC licenses this file | |
| // to you under the Apache License, Version 2.0 (the | |
| // "License"); you may not use this file except in compliance | |
| // with the License. You may obtain a copy of the License at | |
| // | |
| // http://www.apache.org/licenses/LICENSE-2.0 | |
| // | |
| // Unless required by applicable law or agreed to in writing, | |
| // software distributed under the License is distributed on an | |
| // "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY | |
| // KIND, either express or implied. See the License for the | |
| // specific language governing permissions and limitations | |
| // under the License. | |
| // </copyright> | |
| namespace OpenQA.Selenium.Firefox; | |
| /// <summary> | |
| /// Class to manage options specific to <see cref="FirefoxDriver"/> | |
| /// </summary> | |
| /// <remarks> | |
| /// Used with the marionette executable wires.exe. | |
| /// </remarks> | |
| /// <example> | |
| /// <code> | |
| /// FirefoxOptions options = new FirefoxOptions(); | |
| /// </code> | |
| /// <para></para> | |
| /// <para>For use with FirefoxDriver:</para> | |
| /// <para></para> | |
| /// <code> | |
| /// FirefoxDriver driver = new FirefoxDriver(options); | |
| /// </code> | |
| /// <para></para> | |
| /// <para>For use with RemoteWebDriver:</para> | |
| /// <para></para> | |
| /// <code> | |
| /// RemoteWebDriver driver = new RemoteWebDriver(new Uri("http://localhost:4444/wd/hub"), options.ToCapabilities()); | |
| /// </code> | |
| /// </example> | |
| public class FirefoxOptions : DriverOptions | |
| { | |
| private const string BrowserNameValue = "firefox"; | |
| private const string IsMarionetteCapability = "marionette"; | |
| private const string FirefoxLegacyProfileCapability = "firefox_profile"; | |
| private const string FirefoxLegacyBinaryCapability = "firefox_binary"; | |
| private const string FirefoxProfileCapability = "profile"; | |
| private const string FirefoxBinaryCapability = "binary"; | |
| private const string FirefoxArgumentsCapability = "args"; | |
| private const string FirefoxLogCapability = "log"; | |
| private const string FirefoxPrefsCapability = "prefs"; | |
| private const string FirefoxEnvCapability = "env"; | |
| private const string FirefoxOptionsCapability = "moz:firefoxOptions"; | |
| private const string FirefoxEnableDevToolsProtocolCapability = "moz:debuggerAddress"; | |
| private readonly List<string> firefoxArguments = new List<string>(); | |
| private readonly Dictionary<string, object> profilePreferences = new Dictionary<string, object>(); | |
| private readonly Dictionary<string, object> additionalFirefoxOptions = new Dictionary<string, object>(); | |
| private readonly Dictionary<string, object> environmentVariables = new Dictionary<string, object>(); | |
| /// <summary> | |
| /// Initializes a new instance of the <see cref="FirefoxOptions"/> class. | |
| /// </summary> | |
| public FirefoxOptions() | |
| : base() | |
| { | |
| this.BrowserName = BrowserNameValue; | |
| this.AddKnownCapabilityName(FirefoxOptions.FirefoxOptionsCapability, "current FirefoxOptions class instance"); | |
| this.AddKnownCapabilityName(FirefoxOptions.IsMarionetteCapability, "UseLegacyImplementation property"); | |
| this.AddKnownCapabilityName(FirefoxOptions.FirefoxProfileCapability, "Profile property"); | |
| this.AddKnownCapabilityName(FirefoxOptions.FirefoxBinaryCapability, "BrowserExecutableLocation property"); | |
| this.AddKnownCapabilityName(FirefoxOptions.FirefoxArgumentsCapability, "AddArguments method"); | |
| this.AddKnownCapabilityName(FirefoxOptions.FirefoxPrefsCapability, "SetPreference method"); | |
| this.AddKnownCapabilityName(FirefoxOptions.FirefoxEnvCapability, "SetEnvironmentVariable method"); | |
| this.AddKnownCapabilityName(FirefoxOptions.FirefoxLogCapability, "LogLevel property"); | |
| this.AddKnownCapabilityName(FirefoxOptions.FirefoxLegacyProfileCapability, "Profile property"); | |
| this.AddKnownCapabilityName(FirefoxOptions.FirefoxLegacyBinaryCapability, "BrowserExecutableLocation property"); | |
| this.AddKnownCapabilityName(FirefoxOptions.FirefoxEnableDevToolsProtocolCapability, "EnableDevToolsProtocol property"); | |
| // https://fxdx.dev/deprecating-cdp-support-in-firefox-embracing-the-future-with-webdriver-bidi/. | |
| // Enable BiDi only | |
| this.SetPreference("remote.active-protocols", 1); | |
| } | |
| /// <summary> | |
| /// Gets or sets the <see cref="FirefoxProfile"/> object to be used with this instance. | |
| /// </summary> | |
| public FirefoxProfile? Profile { get; set; } | |
| /// <summary> | |
| /// Gets or sets the path and file name of the Firefox browser executable. | |
| /// </summary> | |
| public override string? BinaryLocation { get; set; } | |
| /// <summary> | |
| /// Gets or sets the logging level of the Firefox driver. | |
| /// </summary> | |
| public FirefoxDriverLogLevel LogLevel { get; set; } = FirefoxDriverLogLevel.Default; | |
| /// <summary> | |
| /// Gets or sets a value indicating whether to enable the DevTools protocol for the launched browser. | |
| /// </summary> | |
| public bool EnableDevToolsProtocol { get; set; } | |
| /// <summary> | |
| /// Gets or sets the options for automating Firefox on Android. | |
| /// </summary> | |
| public FirefoxAndroidOptions? AndroidOptions { get; set; } | |
| /// <summary> | |
| /// Adds an argument to be used in launching the Firefox browser. | |
| /// </summary> | |
| /// <param name="argumentName">The argument to add.</param> | |
| /// <remarks>Arguments must be preceded by two dashes ("--").</remarks> | |
| /// <exception cref="ArgumentException">If <paramref name="argumentName"/> is <see langword="null"/> or <see cref="string.Empty"/>.</exception> | |
| public void AddArgument(string argumentName) | |
| { | |
| if (string.IsNullOrEmpty(argumentName)) | |
| { | |
| throw new ArgumentException("argumentName must not be null or empty", nameof(argumentName)); | |
| } | |
| this.AddArguments(argumentName); | |
| } | |
| /// <summary> | |
| /// Adds a list arguments to be used in launching the Firefox browser. | |
| /// </summary> | |
| /// <param name="argumentsToAdd">An array of arguments to add.</param> | |
| /// <remarks>Each argument must be preceded by two dashes ("--").</remarks> | |
| /// <exception cref="ArgumentNullException">If <paramref name="argumentsToAdd"/> is <see langword="null"/>.</exception> | |
| public void AddArguments(params string[] argumentsToAdd) | |
| { | |
| this.AddArguments((IEnumerable<string>)argumentsToAdd); | |
| } | |
| /// <summary> | |
| /// Adds a list arguments to be used in launching the Firefox browser. | |
| /// </summary> | |
| /// <param name="argumentsToAdd">An array of arguments to add.</param> | |
| /// <exception cref="ArgumentNullException">If <paramref name="argumentsToAdd"/> is <see langword="null"/>.</exception> | |
| public void AddArguments(IEnumerable<string> argumentsToAdd) | |
| { | |
| if (argumentsToAdd == null) | |
| { | |
| throw new ArgumentNullException(nameof(argumentsToAdd), "argumentsToAdd must not be null"); | |
| } | |
| this.firefoxArguments.AddRange(argumentsToAdd); | |
| } | |
| /// <summary> | |
| /// Sets a preference in the profile used by Firefox. | |
| /// </summary> | |
| /// <param name="preferenceName">Name of the preference to set.</param> | |
| /// <param name="preferenceValue">Value of the preference to set.</param> | |
| /// <exception cref="ArgumentException">If <paramref name="preferenceName"/> is <see langword="null"/> or <see cref="string.Empty"/>.</exception> | |
| public void SetPreference(string preferenceName, bool preferenceValue) | |
| { | |
| this.SetPreferenceValue(preferenceName, preferenceValue); | |
| } | |
| /// <summary> | |
| /// Sets a preference in the profile used by Firefox. | |
| /// </summary> | |
| /// <param name="preferenceName">Name of the preference to set.</param> | |
| /// <param name="preferenceValue">Value of the preference to set.</param> | |
| /// <exception cref="ArgumentException">If <paramref name="preferenceName"/> is <see langword="null"/> or <see cref="string.Empty"/>.</exception> | |
| public void SetPreference(string preferenceName, int preferenceValue) | |
| { | |
| this.SetPreferenceValue(preferenceName, preferenceValue); | |
| } | |
| /// <summary> | |
| /// Sets a preference in the profile used by Firefox. | |
| /// </summary> | |
| /// <param name="preferenceName">Name of the preference to set.</param> | |
| /// <param name="preferenceValue">Value of the preference to set.</param> | |
| /// <exception cref="ArgumentException">If <paramref name="preferenceName"/> is <see langword="null"/> or <see cref="string.Empty"/>.</exception> | |
| public void SetPreference(string preferenceName, long preferenceValue) | |
| { | |
| this.SetPreferenceValue(preferenceName, preferenceValue); | |
| } | |
| /// <summary> | |
| /// Sets a preference in the profile used by Firefox. | |
| /// </summary> | |
| /// <param name="preferenceName">Name of the preference to set.</param> | |
| /// <param name="preferenceValue">Value of the preference to set.</param> | |
| /// <exception cref="ArgumentException">If <paramref name="preferenceName"/> is <see langword="null"/> or <see cref="string.Empty"/>.</exception> | |
| public void SetPreference(string preferenceName, double preferenceValue) | |
| { | |
| this.SetPreferenceValue(preferenceName, preferenceValue); | |
| } | |
| /// <summary> | |
| /// Sets a preference in the profile used by Firefox. | |
| /// </summary> | |
| /// <param name="preferenceName">Name of the preference to set.</param> | |
| /// <param name="preferenceValue">Value of the preference to set.</param> | |
| /// <exception cref="ArgumentException">If <paramref name="preferenceName"/> is <see langword="null"/> or <see cref="string.Empty"/>.</exception> | |
| public void SetPreference(string preferenceName, string preferenceValue) | |
| { | |
| this.SetPreferenceValue(preferenceName, preferenceValue); | |
| } | |
| /// <summary> | |
| /// Sets an environment variable to be set in the operating system's environment under which the Firefox browser is launched. | |
| /// </summary> | |
| /// <param name="variableName">The name of the environment variable.</param> | |
| /// <param name="variableValue">The value of the environment variable.</param> | |
| /// <exception cref="ArgumentException">If <paramref name="variableName"/> is <see langword="null"/> or <see cref="string.Empty"/>.</exception> | |
| public void SetEnvironmentVariable(string variableName, string? variableValue) | |
| { | |
| if (string.IsNullOrEmpty(variableName)) | |
| { | |
| throw new ArgumentException("Environment variable name cannot be null or an empty string"); | |
| } | |
| this.environmentVariables[variableName] = variableValue ?? string.Empty; | |
| } | |
| /// <summary> | |
| /// Provides a means to add additional capabilities not yet added as type safe options | |
| /// for the Firefox driver. | |
| /// </summary> | |
| /// <param name="optionName">The name of the capability to add.</param> | |
| /// <param name="optionValue">The value of the capability to add.</param> | |
| /// <exception cref="ArgumentException"> | |
| /// thrown when attempting to add a capability for which there is already a type safe option, or | |
| /// when <paramref name="optionName"/> is <see langword="null"/> or the empty string. | |
| /// </exception> | |
| /// <remarks>Calling <see cref="AddAdditionalFirefoxOption(string, object)"/> | |
| /// where <paramref name="optionName"/> has already been added will overwrite the | |
| /// existing value with the new value in <paramref name="optionValue"/>. | |
| /// Calling this method adds capabilities to the Firefox-specific options object passed to | |
| /// geckodriver.exe (property name 'moz:firefoxOptions').</remarks> | |
| public void AddAdditionalFirefoxOption(string optionName, object optionValue) | |
| { | |
| this.ValidateCapabilityName(optionName); | |
| this.additionalFirefoxOptions[optionName] = optionValue; | |
| } | |
| /// <summary> | |
| /// Returns DesiredCapabilities for Firefox with these options included as | |
| /// capabilities. This does not copy the options. Further changes will be | |
| /// reflected in the returned capabilities. | |
| /// </summary> | |
| /// <returns>The DesiredCapabilities for Firefox with these options.</returns> | |
| public override ICapabilities ToCapabilities() | |
| { | |
| IWritableCapabilities capabilities = GenerateDesiredCapabilities(true); | |
| Dictionary<string, object> firefoxOptions = this.GenerateFirefoxOptionsDictionary(); | |
| capabilities.SetCapability(FirefoxOptionsCapability, firefoxOptions); | |
| if (this.EnableDevToolsProtocol) | |
| { | |
| capabilities.SetCapability(FirefoxEnableDevToolsProtocolCapability, true); | |
| } | |
| return capabilities.AsReadOnly(); | |
| } | |
| private Dictionary<string, object> GenerateFirefoxOptionsDictionary() | |
| { | |
| Dictionary<string, object> firefoxOptions = new Dictionary<string, object>(); | |
| if (this.Profile != null) | |
| { | |
| firefoxOptions[FirefoxProfileCapability] = this.Profile.ToBase64String(); | |
| } | |
| if (!string.IsNullOrEmpty(this.BinaryLocation)) | |
| { | |
| firefoxOptions[FirefoxBinaryCapability] = this.BinaryLocation!; | |
| } | |
| if (this.LogLevel != FirefoxDriverLogLevel.Default) | |
| { | |
| Dictionary<string, object> logObject = new Dictionary<string, object>(); | |
| logObject["level"] = this.LogLevel.ToString().ToLowerInvariant(); | |
| firefoxOptions[FirefoxLogCapability] = logObject; | |
| } | |
| if (this.firefoxArguments.Count > 0) | |
| { | |
| List<object> args = [.. this.firefoxArguments]; | |
| firefoxOptions[FirefoxArgumentsCapability] = args; | |
| } | |
| if (this.profilePreferences.Count > 0) | |
| { | |
| firefoxOptions[FirefoxPrefsCapability] = this.profilePreferences; | |
| } | |
| if (this.environmentVariables.Count > 0) | |
| { | |
| firefoxOptions[FirefoxEnvCapability] = this.environmentVariables; | |
| } | |
| if (this.AndroidOptions != null) | |
| { | |
| AddAndroidOptions(this.AndroidOptions, firefoxOptions); | |
| } | |
| foreach (KeyValuePair<string, object> pair in this.additionalFirefoxOptions) | |
| { | |
| firefoxOptions.Add(pair.Key, pair.Value); | |
| } | |
| return firefoxOptions; | |
| } | |
| private void SetPreferenceValue(string preferenceName, object preferenceValue) | |
| { | |
| if (string.IsNullOrEmpty(preferenceName)) | |
| { | |
| throw new ArgumentException("Preference name may not be null an empty string.", nameof(preferenceName)); | |
| } | |
| this.profilePreferences[preferenceName] = preferenceValue; | |
| } | |
| private static void AddAndroidOptions(FirefoxAndroidOptions androidOptions, Dictionary<string, object> firefoxOptions) | |
| { | |
| firefoxOptions["androidPackage"] = androidOptions.AndroidPackage; | |
| if (!string.IsNullOrEmpty(androidOptions.AndroidDeviceSerial)) | |
| { | |
| firefoxOptions["androidDeviceSerial"] = androidOptions.AndroidDeviceSerial!; | |
| } | |
| if (!string.IsNullOrEmpty(androidOptions.AndroidActivity)) | |
| { | |
| firefoxOptions["androidActivity"] = androidOptions.AndroidActivity!; | |
| } | |
| if (androidOptions.AndroidIntentArguments.Count > 0) | |
| { | |
| List<object> args = [.. androidOptions.AndroidIntentArguments]; | |
| firefoxOptions["androidIntentArguments"] = args; | |
| } | |
| } | |
| } |