| // <copyright file="DriverOptions.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> | |
| using System.Diagnostics.CodeAnalysis; | |
| using System.Globalization; | |
| using OpenQA.Selenium.Internal; | |
| using OpenQA.Selenium.Remote; | |
| namespace OpenQA.Selenium; | |
| /// <summary> | |
| /// Specifies the behavior of waiting for page loads in the driver. | |
| /// </summary> | |
| public enum PageLoadStrategy | |
| { | |
| /// <summary> | |
| /// Indicates the behavior is not set. | |
| /// </summary> | |
| Default, | |
| /// <summary> | |
| /// Waits for pages to load and ready state to be 'complete'. | |
| /// </summary> | |
| Normal, | |
| /// <summary> | |
| /// Waits for pages to load and for ready state to be 'interactive' or 'complete'. | |
| /// </summary> | |
| Eager, | |
| /// <summary> | |
| /// Does not wait for pages to load, returning immediately. | |
| /// </summary> | |
| None | |
| } | |
| internal class Timeout | |
| { | |
| public TimeSpan? Script { get; set; } | |
| public TimeSpan? PageLoad { get; set; } | |
| public TimeSpan? ImplicitWait { get; set; } | |
| public Dictionary<string, object> ToCapabilities() | |
| { | |
| var timeoutCapabilities = new Dictionary<string, object>(); | |
| if (Script.HasValue) timeoutCapabilities.Add("script", Script.Value.TotalMilliseconds); | |
| if (PageLoad.HasValue) timeoutCapabilities.Add("pageLoad", PageLoad.Value.TotalMilliseconds); | |
| if (ImplicitWait.HasValue) timeoutCapabilities.Add("implicit", ImplicitWait.Value.TotalMilliseconds); | |
| return timeoutCapabilities; | |
| } | |
| } | |
| /// <summary> | |
| /// Base class for managing options specific to a browser driver. | |
| /// </summary> | |
| public abstract class DriverOptions | |
| { | |
| private readonly Dictionary<string, object> additionalCapabilities = new Dictionary<string, object>(); | |
| private readonly Dictionary<string, LogLevel> loggingPreferences = new Dictionary<string, LogLevel>(); | |
| private readonly Dictionary<string, string> knownCapabilityNames = new Dictionary<string, string>(); | |
| /// <summary> | |
| /// Initializes a new instance of the <see cref="DriverOptions"/> class. | |
| /// </summary> | |
| protected DriverOptions() | |
| { | |
| this.AddKnownCapabilityName(CapabilityType.BrowserName, "BrowserName property"); | |
| this.AddKnownCapabilityName(CapabilityType.BrowserVersion, "BrowserVersion property"); | |
| this.AddKnownCapabilityName(CapabilityType.PlatformName, "PlatformName property"); | |
| this.AddKnownCapabilityName(CapabilityType.Proxy, "Proxy property"); | |
| this.AddKnownCapabilityName(CapabilityType.UnhandledPromptBehavior, "UnhandledPromptBehavior property"); | |
| this.AddKnownCapabilityName(CapabilityType.PageLoadStrategy, "PageLoadStrategy property"); | |
| this.AddKnownCapabilityName(CapabilityType.UseStrictFileInteractability, "UseStrictFileInteractability property"); | |
| this.AddKnownCapabilityName(CapabilityType.WebSocketUrl, "UseWebSocketUrl property"); | |
| this.AddKnownCapabilityName(CapabilityType.EnableDownloads, "EnableDownloads property"); | |
| } | |
| /// <summary> | |
| /// Gets or sets the name of the browser. | |
| /// </summary> | |
| public string? BrowserName { get; protected set; } | |
| /// <summary> | |
| /// Gets or sets the version of the browser. | |
| /// </summary> | |
| public string? BrowserVersion { get; set; } | |
| /// <summary> | |
| /// Gets or sets the name of the platform on which the browser is running. | |
| /// </summary> | |
| public string? PlatformName { get; set; } | |
| /// <summary> | |
| /// Gets or sets a value indicating whether the browser should accept self-signed | |
| /// SSL certificates. | |
| /// </summary> | |
| public bool? AcceptInsecureCertificates { get; set; } | |
| /// <summary> | |
| /// Gets or sets a value indicating whether the driver should request a URL to | |
| /// a WebSocket to be used for bidirectional communication. | |
| /// </summary> | |
| public bool? UseWebSocketUrl { get; set; } | |
| /// <summary> | |
| /// Gets or sets the value for describing how unexpected alerts are to be handled in the browser. | |
| /// Defaults to <see langword="null"/>, leaving the behavior unset. | |
| /// </summary> | |
| public UserPromptHandler? UnhandledPromptBehavior { get; set; } | |
| /// <summary> | |
| /// Gets or sets the value for describing how the browser is to wait for pages to load in the browser. | |
| /// Defaults to <see cref="PageLoadStrategy.Default"/>. | |
| /// </summary> | |
| public PageLoadStrategy PageLoadStrategy { get; set; } = PageLoadStrategy.Default; | |
| /// <summary> | |
| /// Gets or sets the <see cref="Proxy"/> to be used with this browser. | |
| /// </summary> | |
| public Proxy? Proxy { get; set; } | |
| /// <summary> | |
| /// Gets or sets a value indicating whether <input type='file'/> elements | |
| /// must be visible to allow uploading of files. | |
| /// </summary> | |
| public bool UseStrictFileInteractability { get; set; } | |
| /// <summary> | |
| /// Gets or sets a value indicating whether files may be downloaded from remote node. | |
| /// </summary> | |
| public bool? EnableDownloads { get; set; } | |
| /// <summary> | |
| /// Gets or sets the asynchronous script timeout, which is the amount | |
| /// of time the driver should wait when executing JavaScript asynchronously. | |
| /// This timeout only affects the <see cref="IJavaScriptExecutor.ExecuteAsyncScript(string, object[])"/> | |
| /// method. | |
| /// </summary> | |
| public TimeSpan? ScriptTimeout { get; set; } | |
| /// <summary> | |
| /// Gets or sets the page load timeout, which is the amount of time the driver | |
| /// should wait for a page to load when setting the <see cref="IWebDriver.Url"/> | |
| /// property. | |
| /// </summary> | |
| public TimeSpan? PageLoadTimeout { get; set; } | |
| /// <summary> | |
| /// Gets or sets the implicit wait timeout, which is the amount of time the | |
| /// driver should wait when searching for an element if it is not immediately | |
| /// present. | |
| /// </summary> | |
| /// <remarks> | |
| /// When searching for a single element, the driver should poll the page | |
| /// until the element has been found, or this timeout expires before throwing | |
| /// a <see cref="NoSuchElementException"/>. When searching for multiple elements, | |
| /// the driver should poll the page until at least one element has been found | |
| /// or this timeout has expired. | |
| /// <para> | |
| /// Increasing the implicit wait timeout should be used judiciously as it | |
| /// will have an adverse effect on test run time, especially when used with | |
| /// slower location strategies like XPath. | |
| /// </para> | |
| /// </remarks> | |
| public TimeSpan? ImplicitWaitTimeout { get; set; } | |
| /// <summary> | |
| /// Set or Get the location of the browser | |
| /// Override in subclass | |
| /// </summary> | |
| public virtual string? BinaryLocation | |
| { | |
| get => null; | |
| set => throw new NotImplementedException(); | |
| } | |
| /// <summary> | |
| /// Provides a means to add additional capabilities not yet added as type safe options | |
| /// for the specific browser 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="AddAdditionalOption(string, object)"/> | |
| /// where <paramref name="optionName"/> has already been added will overwrite the | |
| /// existing value with the new value in <paramref name="optionValue"/>. | |
| /// </remarks> | |
| public virtual void AddAdditionalOption(string optionName, object optionValue) | |
| { | |
| this.ValidateCapabilityName(optionName); | |
| this.additionalCapabilities[optionName] = optionValue; | |
| } | |
| /// <summary> | |
| /// Returns the <see cref="ICapabilities"/> for the specific browser driver with these | |
| /// options included as capabilities. This does not copy the options. Further | |
| /// changes will be reflected in the returned capabilities. | |
| /// </summary> | |
| /// <returns>The <see cref="ICapabilities"/> for browser driver with these options.</returns> | |
| public abstract ICapabilities ToCapabilities(); | |
| /// <summary> | |
| /// Compares this <see cref="DriverOptions"/> object with another to see if there | |
| /// are merge conflicts between them. | |
| /// </summary> | |
| /// <param name="other">The <see cref="DriverOptions"/> object to compare with.</param> | |
| /// <returns>A <see cref="DriverOptionsMergeResult"/> object containing the status of the attempted merge.</returns> | |
| /// <exception cref="ArgumentNullException">If <paramref name="other"/> is <see langword="null"/>.</exception> | |
| public virtual DriverOptionsMergeResult GetMergeResult(DriverOptions other) | |
| { | |
| ArgumentNullException.ThrowIfNull(other); | |
| DriverOptionsMergeResult result = new DriverOptionsMergeResult(); | |
| if (this.BrowserName != null && other.BrowserName != null) | |
| { | |
| result.IsMergeConflict = true; | |
| result.MergeConflictOptionName = "BrowserName"; | |
| return result; | |
| } | |
| if (this.BrowserVersion != null && other.BrowserVersion != null) | |
| { | |
| result.IsMergeConflict = true; | |
| result.MergeConflictOptionName = "BrowserVersion"; | |
| return result; | |
| } | |
| if (this.PlatformName != null && other.PlatformName != null) | |
| { | |
| result.IsMergeConflict = true; | |
| result.MergeConflictOptionName = "PlatformName"; | |
| return result; | |
| } | |
| if (this.Proxy != null && other.Proxy != null) | |
| { | |
| result.IsMergeConflict = true; | |
| result.MergeConflictOptionName = "Proxy"; | |
| return result; | |
| } | |
| if (this.UnhandledPromptBehavior != other.UnhandledPromptBehavior) | |
| { | |
| result.IsMergeConflict = true; | |
| result.MergeConflictOptionName = "UnhandledPromptBehavior"; | |
| return result; | |
| } | |
| if (this.PageLoadStrategy != PageLoadStrategy.Default && other.PageLoadStrategy != PageLoadStrategy.Default) | |
| { | |
| result.IsMergeConflict = true; | |
| result.MergeConflictOptionName = "PageLoadStrategy"; | |
| return result; | |
| } | |
| return result; | |
| } | |
| /// <summary> | |
| /// Sets the logging preferences for this driver. | |
| /// </summary> | |
| /// <param name="logType">The type of log for which to set the preference. | |
| /// Known log types can be found in the <see cref="LogType"/> class.</param> | |
| /// <param name="logLevel">The <see cref="LogLevel"/> value to which to set the log level.</param> | |
| public void SetLoggingPreference(string logType, LogLevel logLevel) | |
| { | |
| this.loggingPreferences[logType] = logLevel; | |
| } | |
| /// <summary> | |
| /// Returns the current options as a <see cref="Dictionary{TKey, TValue}"/>. | |
| /// </summary> | |
| /// <returns>The current options as a <see cref="Dictionary{TKey, TValue}"/>.</returns> | |
| internal IDictionary<string, object>? ToDictionary() | |
| { | |
| ICapabilities? capabilities = this.ToCapabilities(); | |
| if (capabilities is not IHasCapabilitiesDictionary desired) | |
| { | |
| return null; | |
| } | |
| return desired.CapabilitiesDictionary; | |
| } | |
| /// <summary> | |
| /// Validates the name of the capability to verify it is not a capability | |
| /// for which a type-safe property or method already exists. | |
| /// </summary> | |
| /// <param name="capabilityName">The name of the capability to validate.</param> | |
| /// <exception cref="ArgumentException"> | |
| /// thrown when attempting to add a capability for which there is already a type safe option, or | |
| /// when <paramref name="capabilityName"/> is <see langword="null"/> or the empty string. | |
| /// </exception> | |
| protected void ValidateCapabilityName([NotNull] string? capabilityName) | |
| { | |
| if (capabilityName is null || string.IsNullOrEmpty(capabilityName)) | |
| { | |
| throw new ArgumentException("Capability name may not be null an empty string.", nameof(capabilityName)); | |
| } | |
| if (this.TryGetKnownCapability(capabilityName!, out string? typeSafeOptionName)) | |
| { | |
| string message = string.Format(CultureInfo.InvariantCulture, "There is already an option for the {0} capability. Please use the {1} instead.", capabilityName, typeSafeOptionName); | |
| throw new ArgumentException(message, nameof(capabilityName)); | |
| } | |
| } | |
| /// <summary> | |
| /// Adds a known capability to the list of known capabilities and associates it | |
| /// with the type-safe property name of the options class to be used instead. | |
| /// </summary> | |
| /// <param name="capabilityName">The name of the capability.</param> | |
| /// <param name="typeSafeOptionName">The name of the option property or method to be used instead.</param> | |
| protected void AddKnownCapabilityName(string capabilityName, string typeSafeOptionName) | |
| { | |
| this.knownCapabilityNames[capabilityName] = typeSafeOptionName; | |
| } | |
| /// <summary> | |
| /// Remove a capability from the list of known capabilities | |
| /// </summary> | |
| /// <param name="capabilityName">The name of the capability to be removed.</param> | |
| protected void RemoveKnownCapabilityName(string? capabilityName) | |
| { | |
| if (capabilityName is not null) | |
| { | |
| this.knownCapabilityNames.Remove(capabilityName); | |
| } | |
| } | |
| /// <summary> | |
| /// Gets a value indicating whether the specified capability name is a known capability name which has a type-safe option. | |
| /// </summary> | |
| /// <param name="capabilityName">The name of the capability to check.</param> | |
| /// <returns><see langword="true"/> if the capability name is known; otherwise <see langword="false"/>.</returns> | |
| protected bool IsKnownCapabilityName(string capabilityName) | |
| { | |
| return this.knownCapabilityNames.ContainsKey(capabilityName); | |
| } | |
| /// <summary> | |
| /// Gets a value indicating whether the specified capability name is a known capability name which has a type-safe option. | |
| /// </summary> | |
| /// <param name="capabilityName">The name of the capability to check.</param> | |
| /// <param name="typeSafeOptionName">The name of the type-safe option for the given capability name, or <see langword="null"/> if not found.</param> | |
| /// <returns><see langword="true"/> if the capability name is known; otherwise <see langword="false"/>.</returns> | |
| protected bool TryGetKnownCapability(string capabilityName, [NotNullWhen(true)] out string? typeSafeOptionName) | |
| { | |
| return this.knownCapabilityNames.TryGetValue(capabilityName, out typeSafeOptionName); | |
| } | |
| /// <summary> | |
| /// Gets the name of the type-safe option for a given capability name. | |
| /// </summary> | |
| /// <param name="capabilityName">The name of the capability to check.</param> | |
| /// <returns>The name of the type-safe option for the given capability name.</returns> | |
| protected string GetTypeSafeOptionName(string capabilityName) | |
| { | |
| if (!this.IsKnownCapabilityName(capabilityName)) | |
| { | |
| return string.Empty; | |
| } | |
| return this.knownCapabilityNames[capabilityName]; | |
| } | |
| /// <summary> | |
| /// Generates the logging preferences dictionary for transmission as a desired capability. | |
| /// </summary> | |
| /// <returns>The dictionary containing the logging preferences.</returns> | |
| protected Dictionary<string, object>? GenerateLoggingPreferencesDictionary() | |
| { | |
| if (this.loggingPreferences.Count == 0) | |
| { | |
| return null; | |
| } | |
| Dictionary<string, object> loggingPreferenceCapability = new Dictionary<string, object>(); | |
| foreach (string logType in this.loggingPreferences.Keys) | |
| { | |
| loggingPreferenceCapability[logType] = this.loggingPreferences[logType].ToString().ToUpperInvariant(); | |
| } | |
| return loggingPreferenceCapability; | |
| } | |
| /// <summary> | |
| /// Generates the current options as a capabilities object for further processing. | |
| /// </summary> | |
| /// <param name="isSpecificationCompliant">A value indicating whether to generate capabilities compliant with the W3C WebDriver Specification.</param> | |
| /// <returns>A <see cref="IWritableCapabilities"/> object representing the current options for further processing.</returns> | |
| protected IWritableCapabilities GenerateDesiredCapabilities(bool isSpecificationCompliant) | |
| { | |
| DesiredCapabilities capabilities = new DesiredCapabilities(); | |
| if (!string.IsNullOrEmpty(this.BrowserName)) | |
| { | |
| capabilities.SetCapability(CapabilityType.BrowserName, this.BrowserName!); | |
| } | |
| if (!string.IsNullOrEmpty(this.BrowserVersion)) | |
| { | |
| capabilities.SetCapability(CapabilityType.BrowserVersion, this.BrowserVersion!); | |
| } | |
| if (!string.IsNullOrEmpty(this.PlatformName)) | |
| { | |
| capabilities.SetCapability(CapabilityType.PlatformName, this.PlatformName!); | |
| } | |
| if (this.AcceptInsecureCertificates.HasValue) | |
| { | |
| capabilities.SetCapability(CapabilityType.AcceptInsecureCertificates, this.AcceptInsecureCertificates); | |
| } | |
| if (this.UseWebSocketUrl.HasValue) | |
| { | |
| capabilities.SetCapability(CapabilityType.WebSocketUrl, this.UseWebSocketUrl); | |
| } | |
| if (this.EnableDownloads.HasValue) | |
| { | |
| capabilities.SetCapability(CapabilityType.EnableDownloads, this.EnableDownloads); | |
| } | |
| if (this.UseStrictFileInteractability) | |
| { | |
| capabilities.SetCapability(CapabilityType.UseStrictFileInteractability, true); | |
| } | |
| if (this.PageLoadStrategy != PageLoadStrategy.Default) | |
| { | |
| string pageLoadStrategySetting = "normal"; | |
| switch (this.PageLoadStrategy) | |
| { | |
| case PageLoadStrategy.Eager: | |
| pageLoadStrategySetting = "eager"; | |
| break; | |
| case PageLoadStrategy.None: | |
| pageLoadStrategySetting = "none"; | |
| break; | |
| } | |
| capabilities.SetCapability(CapabilityType.PageLoadStrategy, pageLoadStrategySetting); | |
| } | |
| var unhandledPromptBehaviorCapability = this.UnhandledPromptBehavior?.ToCapabilities(); | |
| if (unhandledPromptBehaviorCapability != null) | |
| { | |
| capabilities.SetCapability(CapabilityType.UnhandledPromptBehavior, unhandledPromptBehaviorCapability); | |
| } | |
| if (this.Proxy != null) | |
| { | |
| Dictionary<string, object?>? proxyCapability = this.Proxy.ToCapability(); | |
| if (!isSpecificationCompliant) | |
| { | |
| proxyCapability = this.Proxy.ToLegacyCapability(); | |
| } | |
| if (proxyCapability != null) | |
| { | |
| capabilities.SetCapability(CapabilityType.Proxy, proxyCapability); | |
| } | |
| } | |
| if (this.ScriptTimeout.HasValue || this.PageLoadTimeout.HasValue || this.ImplicitWaitTimeout.HasValue) | |
| { | |
| var timeouts = new Timeout | |
| { | |
| Script = this.ScriptTimeout, | |
| PageLoad = this.PageLoadTimeout, | |
| ImplicitWait = this.ImplicitWaitTimeout | |
| }; | |
| capabilities.SetCapability(CapabilityType.Timeouts, timeouts.ToCapabilities()); | |
| } | |
| foreach (KeyValuePair<string, object> pair in this.additionalCapabilities) | |
| { | |
| capabilities.SetCapability(pair.Key, pair.Value); | |
| } | |
| return capabilities; | |
| } | |
| } |