WebDriver.cs

// <copyright file="WebDriver.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 OpenQA.Selenium.Interactions;
using OpenQA.Selenium.Internal;
using OpenQA.Selenium.VirtualAuth;
using System;
using System.Collections;
using System.Collections.Generic;
using System.Collections.ObjectModel;
using System.Diagnostics.CodeAnalysis;
using System.Globalization;
using System.Threading.Tasks;

namespace OpenQA.Selenium
{
    /// <summary>
    /// A base class representing a driver for a web browser.
    /// </summary>
    public class WebDriver : IWebDriver, ISearchContext, IJavaScriptExecutor, IFindsElement, ITakesScreenshot, ISupportsPrint, IActionExecutor, IAllowsFileDetection, IHasCapabilities, IHasCommandExecutor, IHasSessionId, ICustomDriverCommandExecutor, IHasVirtualAuthenticator
    {
        /// <summary>
        /// The default command timeout for HTTP requests in a RemoteWebDriver instance.
        /// </summary>
        protected static readonly TimeSpan DefaultCommandTimeout = TimeSpan.FromSeconds(60);
        private IFileDetector fileDetector = new DefaultFileDetector();
        private NetworkManager network;
        private WebElementFactory elementFactory;

        private readonly List<string> registeredCommands = new List<string>();

        /// <summary>
        /// Initializes a new instance of the <see cref="WebDriver"/> class.
        /// </summary>
        /// <param name="executor">The <see cref="ICommandExecutor"/> object used to execute commands.</param>
        /// <param name="capabilities">The <see cref="ICapabilities"/> object used to configure the driver session.</param>
        protected WebDriver(ICommandExecutor executor, ICapabilities capabilities)
        {
            this.CommandExecutor = executor;

            try
            {
                this.StartSession(capabilities);
            }
            catch (Exception)
            {
                try
                {
                    // Failed to start driver session, disposing of driver
                    this.Quit();
                }
                catch
                {
                    // Ignore the clean-up exception. We'll propagate the original failure.
                }
                throw;
            }

            this.elementFactory = new WebElementFactory(this);
            this.registeredCommands.AddRange(DriverCommand.KnownCommands);

            if (this is ISupportsLogs)
            {
                // Only add the legacy log commands if the driver supports
                // retrieving the logs via the extension end points.
                this.RegisterDriverCommand(DriverCommand.GetAvailableLogTypes, new HttpCommandInfo(HttpCommandInfo.GetCommand, "/session/{sessionId}/se/log/types"), true);
                this.RegisterDriverCommand(DriverCommand.GetLog, new HttpCommandInfo(HttpCommandInfo.PostCommand, "/session/{sessionId}/se/log"), true);
            }
        }

        /// <summary>
        /// Gets the <see cref="ICommandExecutor"/> which executes commands for this driver.
        /// </summary>
        public ICommandExecutor CommandExecutor { get; }

        /// <summary>
        /// Gets the <see cref="ICapabilities"/> that the driver session was created with, which may be different from those requested.
        /// </summary>
        public ICapabilities Capabilities { get; private set; }

        /// <summary>
        /// Gets or sets the URL the browser is currently displaying.
        /// </summary>
        /// <seealso cref="IWebDriver.Url"/>
        /// <seealso cref="INavigation.GoToUrl(string)"/>
        /// <seealso cref="INavigation.GoToUrl(System.Uri)"/>
        public string Url
        {
            get
            {
                Response commandResponse = this.Execute(DriverCommand.GetCurrentUrl, null);

                commandResponse.EnsureValueIsNotNull();
                return commandResponse.Value.ToString()!;
            }

            set => new Navigator(this).GoToUrl(value);
        }

        /// <summary>
        /// Gets the title of the current browser window.
        /// </summary>
        public string Title
        {
            get
            {
                Response commandResponse = this.Execute(DriverCommand.GetTitle, null);

                return commandResponse.Value?.ToString() ?? string.Empty;
            }
        }

        /// <summary>
        /// Gets the source of the page last loaded by the browser.
        /// </summary>
        public string PageSource
        {
            get
            {
                Response commandResponse = this.Execute(DriverCommand.GetPageSource, null);

                commandResponse.EnsureValueIsNotNull();
                return commandResponse.Value.ToString()!;
            }
        }

        /// <summary>
        /// Gets the current window handle, which is an opaque handle to this
        /// window that uniquely identifies it within this driver instance.
        /// </summary>
        public string CurrentWindowHandle
        {
            get
            {
                Response commandResponse = this.Execute(DriverCommand.GetCurrentWindowHandle, null);

                commandResponse.EnsureValueIsNotNull();
                return commandResponse.Value.ToString()!;
            }
        }

        /// <summary>
        /// Gets the window handles of open browser windows.
        /// </summary>
        public ReadOnlyCollection<string> WindowHandles
        {
            get
            {
                Response commandResponse = this.Execute(DriverCommand.GetWindowHandles, null);

                commandResponse.EnsureValueIsNotNull();
                object?[] handles = (object?[])commandResponse.Value;
                List<string> handleList = new List<string>(handles.Length);
                foreach (object? handle in handles)
                {
                    handleList.Add(handle!.ToString()!);
                }

                return handleList.AsReadOnly();
            }
        }

        /// <summary>
        /// Gets a value indicating whether this object is a valid action executor.
        /// </summary>
        public bool IsActionExecutor => true;

        /// <summary>
        /// Gets the <see cref="Selenium.SessionId"/> for the current session of this driver.
        /// </summary>
        public SessionId SessionId { get; private set; }

        /// <summary>
        /// Gets or sets the <see cref="IFileDetector"/> responsible for detecting
        /// sequences of keystrokes representing file paths and names.
        /// </summary>
        /// <exception cref="ArgumentNullException">If value is set to <see langword="null"/>.</exception>
        public virtual IFileDetector FileDetector
        {
            get => this.fileDetector;
            set => this.fileDetector = value ?? throw new ArgumentNullException(nameof(value), "FileDetector cannot be null");
        }

        internal INetwork Network => this.network ??= new NetworkManager(this);

        /// <summary>
        /// Gets or sets the factory object used to create instances of <see cref="WebElement"/>
        /// or its subclasses.
        /// </summary>
        /// <exception cref="ArgumentNullException">If value is set to <see langword="null"/>.</exception>
        protected WebElementFactory ElementFactory
        {
            get => this.elementFactory;
            set => this.elementFactory = value ?? throw new ArgumentNullException(nameof(value));
        }

        /// <summary>
        /// Closes the Browser
        /// </summary>
        public void Close()
        {
            this.Execute(DriverCommand.Close, null);
        }

        /// <summary>
        /// Dispose the WebDriver Instance
        /// </summary>
        public void Dispose()
        {
            this.Dispose(true);
            GC.SuppressFinalize(this);
        }

        /// <summary>
        /// Executes JavaScript "asynchronously" in the context of the currently selected frame or window,
        /// executing the callback function specified as the last argument in the list of arguments.
        /// </summary>
        /// <param name="script">The JavaScript code to execute.</param>
        /// <param name="args">The arguments to the script.</param>
        /// <returns>The value returned by the script.</returns>
        public object? ExecuteAsyncScript(string script, params object?[]? args)
        {
            return this.ExecuteScriptCommand(script, DriverCommand.ExecuteAsyncScript, args);
        }

        /// <summary>
        /// Executes JavaScript in the context of the currently selected frame or window
        /// </summary>
        /// <param name="script">The JavaScript code to execute.</param>
        /// <param name="args">The arguments to the script.</param>
        /// <returns>The value returned by the script.</returns>
        public object? ExecuteScript(string script, params object?[]? args)
        {
            return this.ExecuteScriptCommand(script, DriverCommand.ExecuteScript, args);
        }

        /// <summary>
        /// Executes JavaScript in the context of the currently selected frame or window
        /// </summary>
        /// <param name="script">A <see cref="PinnedScript"/> object containing the JavaScript code to execute.</param>
        /// <param name="args">The arguments to the script.</param>
        /// <returns>The value returned by the script.</returns>
        /// <exception cref="ArgumentNullException">If <paramref name="script" /> is <see langword="null"/>.</exception>
        public object? ExecuteScript(PinnedScript script, params object?[]? args)
        {
            if (script == null)
            {
                throw new ArgumentNullException(nameof(script));
            }

            return this.ExecuteScript(script.MakeExecutionScript(), args);
        }

        /// <summary>
        /// Finds the first element in the page that matches the <see cref="By"/> object
        /// </summary>
        /// <param name="by">By mechanism to find the object</param>
        /// <returns>IWebElement object so that you can interact with that object</returns>
        /// <exception cref="ArgumentNullException">If <paramref name="by" /> is <see langword="null"/>.</exception>
        /// <example>
        /// <code>
        /// IWebDriver driver = new InternetExplorerDriver();
        /// IWebElement elem = driver.FindElement(By.Name("q"));
        /// </code>
        /// </example>
        public IWebElement FindElement(By by)
        {
            if (by == null)
            {
                throw new ArgumentNullException(nameof(@by), "by cannot be null");
            }

            return by.FindElement(this);
        }

        /// <summary>
        /// Finds an element matching the given mechanism and value.
        /// </summary>
        /// <param name="mechanism">The mechanism by which to find the element.</param>
        /// <param name="value">The value to use to search for the element.</param>
        /// <returns>The first <see cref="IWebElement"/> matching the given criteria.</returns>
        public virtual IWebElement FindElement(string mechanism, string value)
        {
            Dictionary<string, object> parameters = new Dictionary<string, object>();
            parameters.Add("using", mechanism);
            parameters.Add("value", value);

            Response commandResponse = this.Execute(DriverCommand.FindElement, parameters);

            return this.GetElementFromResponse(commandResponse)!;
        }

        /// <summary>
        /// Finds the elements on the page by using the <see cref="By"/> object and returns a ReadOnlyCollection of the Elements on the page
        /// </summary>
        /// <param name="by">By mechanism to find the element</param>
        /// <returns>ReadOnlyCollection of IWebElement</returns>
        /// <example>
        /// <code>
        /// IWebDriver driver = new InternetExplorerDriver();
        /// ReadOnlyCollection<![CDATA[<IWebElement>]]> classList = driver.FindElements(By.ClassName("class"));
        /// </code>
        /// </example>
        public ReadOnlyCollection<IWebElement> FindElements(By by)
        {
            if (by == null)
            {
                throw new ArgumentNullException(nameof(@by), "by cannot be null");
            }

            return by.FindElements(this);
        }

        /// <summary>
        /// Finds all elements matching the given mechanism and value.
        /// </summary>
        /// <param name="mechanism">The mechanism by which to find the elements.</param>
        /// <param name="value">The value to use to search for the elements.</param>
        /// <returns>A collection of all of the <see cref="IWebElement">IWebElements</see> matching the given criteria.</returns>
        public virtual ReadOnlyCollection<IWebElement> FindElements(string mechanism, string value)
        {
            Dictionary<string, object> parameters = new Dictionary<string, object>();
            parameters.Add("using", mechanism);
            parameters.Add("value", value);

            Response commandResponse = this.Execute(DriverCommand.FindElements, parameters);

            return this.GetElementsFromResponse(commandResponse);
        }

        /// <summary>
        /// Gets a <see cref="Screenshot"/> object representing the image of the page on the screen.
        /// </summary>
        /// <returns>A <see cref="Screenshot"/> object containing the image.</returns>
        public Screenshot GetScreenshot()
        {
            Response screenshotResponse = this.Execute(DriverCommand.Screenshot, null);

            screenshotResponse.EnsureValueIsNotNull();
            string base64 = screenshotResponse.Value.ToString()!;
            return new Screenshot(base64);
        }

        /// <summary>
        /// Gets a <see cref="PrintDocument"/> object representing a PDF-formatted print representation of the page.
        /// </summary>
        /// <param name="printOptions">A <see cref="PrintOptions"/> object describing the options of the printed document.</param>
        /// <returns>The <see cref="PrintDocument"/> object containing the PDF-formatted print representation of the page.</returns>
        /// <exception cref="ArgumentNullException">If <paramref name="printOptions"/> is <see langword="null"/>.</exception>
        public PrintDocument Print(PrintOptions printOptions)
        {
            if (printOptions is null)
            {
                throw new ArgumentNullException(nameof(printOptions));
            }

            Response commandResponse = this.Execute(DriverCommand.Print, printOptions.ToDictionary());

            commandResponse.EnsureValueIsNotNull();
            string base64 = commandResponse.Value.ToString()!;
            return new PrintDocument(base64);
        }

        /// <summary>
        /// Performs the specified list of actions with this action executor.
        /// </summary>
        /// <param name="actionSequenceList">The list of action sequences to perform.</param>
        public void PerformActions(IList<ActionSequence> actionSequenceList)
        {
            if (actionSequenceList == null)
            {
                throw new ArgumentNullException(nameof(actionSequenceList), "List of action sequences must not be null");
            }

            List<object> objectList = new List<object>();
            foreach (ActionSequence sequence in actionSequenceList)
            {
                objectList.Add(sequence.ToDictionary());
            }

            Dictionary<string, object> parameters = new Dictionary<string, object>();
            parameters["actions"] = objectList;

            this.Execute(DriverCommand.Actions, parameters);
        }

        /// <summary>
        /// Resets the input state of the action executor.
        /// </summary>
        public void ResetInputState()
        {
            this.Execute(DriverCommand.CancelActions, null);
        }

        /// <summary>
        /// Close the Browser and Dispose of WebDriver
        /// </summary>
        public void Quit()
        {
            this.Dispose();
        }

        /// <summary>
        /// Method to give you access to switch frames and windows
        /// </summary>
        /// <returns>Returns an Object that allows you to Switch Frames and Windows</returns>
        /// <example>
        /// <code>
        /// IWebDriver driver = new InternetExplorerDriver();
        /// driver.SwitchTo().Frame("FrameName");
        /// </code>
        /// </example>
        public ITargetLocator SwitchTo()
        {
            return new TargetLocator(this);
        }

        /// <summary>
        /// Instructs the driver to change its settings.
        /// </summary>
        /// <returns>An <see cref="IOptions"/> object allowing the user to change
        /// the settings of the driver.</returns>
        public IOptions Manage()
        {
            return new OptionsManager(this);
        }

        /// <summary>
        /// Instructs the driver to navigate the browser to another location.
        /// </summary>
        /// <returns>An <see cref="INavigation"/> object allowing the user to access
        /// the browser's history and to navigate to a given URL.</returns>
        public INavigation Navigate()
        {
            return new Navigator(this);
        }

        /// <summary>
        /// Executes a command with this driver.
        /// </summary>
        /// <param name="driverCommandToExecute">The name of the command to execute. The command name must be registered with the command executor, and must not be a command name known to this driver type.</param>
        /// <param name="parameters">A <see cref="Dictionary{K, V}"/> containing the names and values of the parameters of the command.</param>
        /// <returns>A <see cref="Response"/> containing information about the success or failure of the command and any data returned by the command.</returns>
        /// <exception cref="WebDriverException">The command returned an exceptional value.</exception>
        public object? ExecuteCustomDriverCommand(string driverCommandToExecute, Dictionary<string, object> parameters)
        {
            if (this.registeredCommands.Contains(driverCommandToExecute))
            {
                throw new WebDriverException(string.Format(CultureInfo.InvariantCulture, "A command named '{0}' is predefined by the driver class and cannot be executed with ExecuteCustomDriverCommand. It should be executed using a named method instead.", driverCommandToExecute));
            }

            return this.Execute(driverCommandToExecute, parameters).Value;
        }

        /// <summary>
        /// Registers a set of commands to be executed with this driver instance.
        /// </summary>
        /// <param name="commands">An <see cref="IReadOnlyDictionary{String, CommandInfo}"/> where the keys are the names of the commands to register, and the values are the <see cref="CommandInfo"/> objects describing the commands.</param>
        public void RegisterCustomDriverCommands(IReadOnlyDictionary<string, CommandInfo> commands)
        {
            foreach (KeyValuePair<string, CommandInfo> entry in commands)
            {
                this.RegisterCustomDriverCommand(entry.Key, entry.Value);
            }
        }

        /// <summary>
        /// Registers a command to be executed with this driver instance.
        /// </summary>
        /// <param name="commandName">The unique name of the command to register.</param>
        /// <param name="commandInfo">The <see cref="CommandInfo"/> object describing the command.</param>
        /// <returns><see langword="true"/> if the command was registered; otherwise, <see langword="false"/>.</returns>
        public bool RegisterCustomDriverCommand(string commandName, [NotNullWhen(true)] CommandInfo? commandInfo)
        {
            return this.RegisterDriverCommand(commandName, commandInfo, false);
        }

        /// <summary>
        /// Registers a command to be executed with this driver instance.
        /// </summary>
        /// <param name="commandName">The unique name of the command to register.</param>
        /// <param name="commandInfo">The <see cref="CommandInfo"/> object describing the command.</param>
        /// <param name="isInternalCommand"><see langword="true"/> if the registered command is internal to the driver; otherwise <see langword="false"/>.</param>
        /// <returns><see langword="true"/> if the command was registered; otherwise, <see langword="false"/>.</returns>
        internal bool RegisterDriverCommand(string commandName, [NotNullWhen(true)] CommandInfo? commandInfo, bool isInternalCommand)
        {
            if (this.CommandExecutor.TryAddCommand(commandName, commandInfo))
            {
                if (isInternalCommand)
                {
                    this.registeredCommands.Add(commandName);
                }

                return true;
            }

            return false;
        }

        /// <summary>
        /// Find the element in the response
        /// </summary>
        /// <param name="response">Response from the browser</param>
        /// <returns>Element from the page, or <see langword="null"/> if the response does not contain a dictionary.</returns>
        internal IWebElement? GetElementFromResponse(Response response)
        {
            if (response.Value is Dictionary<string, object?> elementDictionary)
            {
                return this.elementFactory.CreateElement(elementDictionary);
            }

            return null;
        }

        /// <summary>
        /// Finds the elements that are in the response
        /// </summary>
        /// <param name="response">Response from the browser</param>
        /// <returns>Collection of elements</returns>
        internal ReadOnlyCollection<IWebElement> GetElementsFromResponse(Response response)
        {
            List<IWebElement> toReturn = new List<IWebElement>();
            if (response.Value is object?[] elements)
            {
                foreach (object? elementObject in elements)
                {
                    if (elementObject is Dictionary<string, object?> elementDictionary)
                    {
                        WebElement element = this.elementFactory.CreateElement(elementDictionary);
                        toReturn.Add(element);
                    }
                }
            }

            return toReturn.AsReadOnly();
        }

        /// <summary>
        /// Executes a command with this driver.
        /// </summary>
        /// <param name="driverCommandToExecute">A <see cref="DriverCommand"/> value representing the command to execute.</param>
        /// <param name="parameters">A <see cref="Dictionary{K, V}"/> containing the names and values of the parameters of the command.</param>
        /// <returns>A <see cref="Response"/> containing information about the success or failure of the command and any data returned by the command.</returns>
        /// <exception cref="ArgumentNullException">If <paramref name="driverCommandToExecute"/> is <see langword="null"/>.</exception>
        protected internal virtual Response Execute(string driverCommandToExecute, Dictionary<string,
#nullable disable
            object
#nullable enable
            >? parameters)
        {
            return Task.Run(() => this.ExecuteAsync(driverCommandToExecute, parameters)).GetAwaiter().GetResult();
        }

        /// <summary>
        /// Executes a command with this driver.
        /// </summary>
        /// <param name="driverCommandToExecute">A <see cref="DriverCommand"/> value representing the command to execute.</param>
        /// <param name="parameters">A <see cref="Dictionary{K, V}"/> containing the names and values of the parameters of the command.</param>
        /// <returns>A <see cref="Response"/> containing information about the success or failure of the command and any data returned by the command.</returns>
        /// <exception cref="ArgumentNullException">If <paramref name="driverCommandToExecute"/> is <see langword="null"/>.</exception>
        protected internal virtual async Task<Response> ExecuteAsync(string driverCommandToExecute, Dictionary<string,
#nullable disable
            object
#nullable enable
            >? parameters)
        {
            Command commandToExecute = new Command(SessionId, driverCommandToExecute, parameters);

            Response commandResponse = await this.CommandExecutor.ExecuteAsync(commandToExecute).ConfigureAwait(false);

            if (commandResponse.Status != WebDriverResult.Success)
            {
                UnpackAndThrowOnError(commandResponse, driverCommandToExecute);
            }

            return commandResponse;
        }

        /// <summary>
        /// Starts a session with the driver
        /// </summary>
        /// <param name="capabilities">Capabilities of the browser</param>
        [MemberNotNull(nameof(SessionId))]
        [MemberNotNull(nameof(Capabilities))]
        protected void StartSession(ICapabilities capabilities)
        {
            Dictionary<string, object> parameters = new Dictionary<string, object>();

            // If the object passed into the RemoteWebDriver constructor is a
            // RemoteSessionSettings object, it is expected that all intermediate
            // and end nodes are compliant with the W3C WebDriver Specification,
            // and therefore will already contain all of the appropriate values
            // for establishing a session.
            if (capabilities is not RemoteSessionSettings remoteSettings)
            {
                Dictionary<string, object> matchCapabilities = this.GetCapabilitiesDictionary(capabilities);

                List<object> firstMatchCapabilitiesList = new List<object>();
                firstMatchCapabilitiesList.Add(matchCapabilities);

                Dictionary<string, object> specCompliantCapabilitiesDictionary = new Dictionary<string, object>();
                specCompliantCapabilitiesDictionary["firstMatch"] = firstMatchCapabilitiesList;

                parameters.Add("capabilities", specCompliantCapabilitiesDictionary);
            }
            else
            {
                parameters.Add("capabilities", remoteSettings.ToDictionary());
            }

            Response response = this.Execute(DriverCommand.NewSession, parameters);

            response.EnsureValueIsNotNull();
            if (response.Value is not Dictionary<string, object> rawCapabilities)
            {
                string errorMessage = string.Format(CultureInfo.InvariantCulture, "The new session command returned a value ('{0}') that is not a valid JSON object.", response.Value);
                throw new WebDriverException(errorMessage);
            }

            this.Capabilities = new ReturnedCapabilities(rawCapabilities);

            string sessionId = response.SessionId ?? throw new WebDriverException($"The remote end did not respond with ID of a session when it was required. {response.Value}");
            this.SessionId = new SessionId(sessionId);
        }

        /// <summary>
        /// Gets the capabilities as a dictionary.
        /// </summary>
        /// <param name="capabilitiesToConvert">The dictionary to return.</param>
        /// <returns>A Dictionary consisting of the capabilities requested.</returns>
        /// <remarks>This method is only transitional. Do not rely on it. It will be removed
        /// once browser driver capability formats stabilize.</remarks>
        /// <exception cref="ArgumentNullException">If <paramref name="capabilitiesToConvert"/> is <see langword="null"/>.</exception>
        protected virtual Dictionary<string, object> GetCapabilitiesDictionary(ICapabilities capabilitiesToConvert)
        {
            if (capabilitiesToConvert is null)
            {
                throw new ArgumentNullException(nameof(capabilitiesToConvert));
            }

            Dictionary<string, object> capabilitiesDictionary = new Dictionary<string, object>();

            foreach (KeyValuePair<string, object> entry in ((IHasCapabilitiesDictionary)capabilitiesToConvert).CapabilitiesDictionary)
            {
                if (CapabilityType.IsSpecCompliantCapabilityName(entry.Key))
                {
                    capabilitiesDictionary.Add(entry.Key, entry.Value);
                }
            }

            return capabilitiesDictionary;
        }

        /// <summary>
        /// Registers a command to be executed with this driver instance as an internally known driver command.
        /// </summary>
        /// <param name="commandName">The unique name of the command to register.</param>
        /// <param name="commandInfo">The <see cref="CommandInfo"/> object describing the command.</param>
        /// <returns><see langword="true"/> if the command was registered; otherwise, <see langword="false"/>.</returns>
        protected bool RegisterInternalDriverCommand(string commandName, [NotNullWhen(true)] CommandInfo? commandInfo)
        {
            return this.RegisterDriverCommand(commandName, commandInfo, true);
        }

        /// <summary>
        /// Stops the client from running
        /// </summary>
        /// <param name="disposing">if its in the process of disposing</param>
        protected virtual void Dispose(bool disposing)
        {
            try
            {
                if (this.SessionId is not null)
                {
                    this.Execute(DriverCommand.Quit, null);
                }
            }
            catch (NotImplementedException)
            {
            }
            catch (InvalidOperationException)
            {
            }
            catch (WebDriverException)
            {
            }
            finally
            {
                this.SessionId = null!;
            }

            this.CommandExecutor.Dispose();
        }

        private static void UnpackAndThrowOnError(Response errorResponse, string commandToExecute)
        {
            // Check the status code of the error, and only handle if not success.
            if (errorResponse.Status != WebDriverResult.Success)
            {
                if (errorResponse.Value is Dictionary<string, object?> errorAsDictionary)
                {
                    ErrorResponse errorResponseObject = new ErrorResponse(errorAsDictionary);
                    string errorMessage = errorResponseObject.Message;
                    switch (errorResponse.Status)
                    {
                        case WebDriverResult.NoSuchElement:
                            throw new NoSuchElementException(errorMessage);

                        case WebDriverResult.NoSuchFrame:
                            throw new NoSuchFrameException(errorMessage);

                        case WebDriverResult.UnknownCommand:
                            throw new NotImplementedException(errorMessage);

                        case WebDriverResult.ObsoleteElement:
                            throw new StaleElementReferenceException(errorMessage);

                        case WebDriverResult.ElementClickIntercepted:
                            throw new ElementClickInterceptedException(errorMessage);

                        case WebDriverResult.ElementNotInteractable:
                            throw new ElementNotInteractableException(errorMessage);

                        case WebDriverResult.InvalidElementState:
                            throw new InvalidElementStateException(errorMessage);

                        case WebDriverResult.Timeout:
                            throw new WebDriverTimeoutException(errorMessage);

                        case WebDriverResult.NoSuchWindow:
                            throw new NoSuchWindowException(errorMessage);

                        case WebDriverResult.InvalidCookieDomain:
                            throw new InvalidCookieDomainException(errorMessage);

                        case WebDriverResult.UnableToSetCookie:
                            throw new UnableToSetCookieException(errorMessage);

                        case WebDriverResult.AsyncScriptTimeout:
                            throw new WebDriverTimeoutException(errorMessage);

                        case WebDriverResult.UnexpectedAlertOpen:
                            // TODO(JimEvans): Handle the case where the unexpected alert setting
                            // has been set to "ignore", so there is still a valid alert to be
                            // handled.
                            string? alertText = null;
                            if (errorAsDictionary.TryGetValue("alert", out object? alert))
                            {
                                if (alert is Dictionary<string, object?> alertDescription
                                    && alertDescription.TryGetValue("text", out object? text))
                                {
                                    alertText = text?.ToString();
                                }
                            }
                            else if (errorAsDictionary.TryGetValue("data", out object? data))
                            {
                                if (data is Dictionary<string, object?> alertData
                                    && alertData.TryGetValue("text", out object? dataText))
                                {
                                    alertText = dataText?.ToString();
                                }
                            }

                            throw new UnhandledAlertException(errorMessage, alertText ?? string.Empty);

                        case WebDriverResult.NoAlertPresent:
                            throw new NoAlertPresentException(errorMessage);

                        case WebDriverResult.InvalidSelector:
                            throw new InvalidSelectorException(errorMessage);

                        case WebDriverResult.NoSuchDriver:
                            throw new WebDriverException(errorMessage);

                        case WebDriverResult.InvalidArgument:
                            throw new WebDriverArgumentException(errorMessage);

                        case WebDriverResult.UnexpectedJavaScriptError:
                            throw new JavaScriptException(errorMessage);

                        case WebDriverResult.MoveTargetOutOfBounds:
                            throw new MoveTargetOutOfBoundsException(errorMessage);

                        case WebDriverResult.NoSuchShadowRoot:
                            throw new NoSuchShadowRootException(errorMessage);

                        case WebDriverResult.DetachedShadowRoot:
                            throw new DetachedShadowRootException(errorMessage);

                        case WebDriverResult.InsecureCertificate:
                            throw new InsecureCertificateException(errorMessage);

                        case WebDriverResult.UnknownError:
                            throw new UnknownErrorException(errorMessage);

                        case WebDriverResult.UnknownMethod:
                            throw new UnknownMethodException(errorMessage);

                        case WebDriverResult.UnsupportedOperation:
                            throw new UnsupportedOperationException(errorMessage);

                        case WebDriverResult.NoSuchCookie:
                            throw new NoSuchCookieException(errorMessage);

                        default:
                            throw new InvalidOperationException(string.Format(CultureInfo.InvariantCulture, "{0} ({1})", errorMessage, errorResponse.Status));
                    }
                }

                throw new WebDriverException($"The {commandToExecute} command returned an unexpected error. {errorResponse.Value}");
            }
        }

        /// <summary>
        /// Executes JavaScript in the context of the currently selected frame or window using a specific command.
        /// </summary>
        /// <param name="script">The JavaScript code to execute.</param>
        /// <param name="commandName">The name of the command to execute.</param>
        /// <param name="args">The arguments to the script.</param>
        /// <returns>The value returned by the script.</returns>
        protected object? ExecuteScriptCommand(string script, string commandName, params object?[]? args)
        {
            object?[] convertedArgs = ConvertArgumentsToJavaScriptObjects(args);

            Dictionary<string, object> parameters = new Dictionary<string, object>();
            parameters.Add("script", script);

            if (convertedArgs != null && convertedArgs.Length > 0)
            {
                parameters.Add("args", convertedArgs);
            }
            else
            {
                parameters.Add("args", new object[] { });
            }

            Response commandResponse = this.Execute(commandName, parameters);
            return this.ParseJavaScriptReturnValue(commandResponse.Value);
        }

        private static object? ConvertObjectToJavaScriptObject(object? arg)
        {
            IWebDriverObjectReference? argAsObjectReference = arg as IWebDriverObjectReference;

            if (argAsObjectReference == null && arg is IWrapsElement argAsWrapsElement)
            {
                argAsObjectReference = argAsWrapsElement.WrappedElement as IWebDriverObjectReference;
            }

            object? converted;

            if (arg is string || arg is float || arg is double || arg is int || arg is long || arg is bool || arg == null)
            {
                converted = arg;
            }
            else if (argAsObjectReference != null)
            {
                Dictionary<string, object> webDriverObjectReferenceDictionary = argAsObjectReference.ToDictionary();
                converted = webDriverObjectReferenceDictionary;
            }
            else if (arg is IDictionary argAsDictionary)
            {
                // Note that we must check for the argument being a dictionary before
                // checking for IEnumerable, since dictionaries also implement IEnumerable.
                // Additionally, JavaScript objects have property names as strings, so all
                // keys will be converted to strings.
                Dictionary<string, object?> dictionary = new Dictionary<string, object?>();
                foreach (DictionaryEntry argEntry in argAsDictionary)
                {
                    dictionary.Add(argEntry.Key.ToString()!, ConvertObjectToJavaScriptObject(argEntry.Value));
                }

                converted = dictionary;
            }
            else if (arg is IEnumerable argAsEnumerable)
            {
                List<object?> objectList = new List<object?>();
                foreach (object? item in argAsEnumerable)
                {
                    objectList.Add(ConvertObjectToJavaScriptObject(item));
                }

                converted = objectList.ToArray();
            }
            else
            {
                throw new ArgumentException("Argument is of an illegal type: " + arg.ToString(), nameof(arg));
            }

            return converted;
        }

        /// <summary>
        /// Converts the arguments to JavaScript objects.
        /// </summary>
        /// <param name="args">The arguments.</param>
        /// <returns>The list of the arguments converted to JavaScript objects.</returns>
        private static object?[] ConvertArgumentsToJavaScriptObjects(object?[]? args)
        {
            if (args == null)
            {
                return new object?[] { null };
            }

            for (int i = 0; i < args.Length; i++)
            {
                args[i] = ConvertObjectToJavaScriptObject(args[i]);
            }

            return args;
        }

        private object? ParseJavaScriptReturnValue(object? responseValue)
        {
            object? returnValue;

            if (responseValue is Dictionary<string, object?> resultAsDictionary)
            {
                if (this.elementFactory.ContainsElementReference(resultAsDictionary))
                {
                    returnValue = this.elementFactory.CreateElement(resultAsDictionary);
                }
                else if (ShadowRoot.TryCreate(this, resultAsDictionary, out ShadowRoot? shadowRoot))
                {
                    returnValue = shadowRoot;
                }
                else
                {
                    // Recurse through the dictionary, re-parsing each value.
                    string[] keyCopy = new string[resultAsDictionary.Keys.Count];
                    resultAsDictionary.Keys.CopyTo(keyCopy, 0);
                    foreach (string key in keyCopy)
                    {
                        resultAsDictionary[key] = this.ParseJavaScriptReturnValue(resultAsDictionary[key]);
                    }

                    returnValue = resultAsDictionary;
                }
            }
            else if (responseValue is object?[] resultAsArray)
            {
                bool allElementsAreWebElements = true;
                List<object?> toReturn = new List<object?>(resultAsArray.Length);
                foreach (object? item in resultAsArray)
                {
                    object? parsedItem = this.ParseJavaScriptReturnValue(item);
                    if (parsedItem is not IWebElement)
                    {
                        allElementsAreWebElements = false;
                    }

                    toReturn.Add(parsedItem);
                }

                if (toReturn.Count > 0 && allElementsAreWebElements)
                {
                    List<IWebElement> elementList = new List<IWebElement>(resultAsArray.Length);
                    foreach (object? listItem in toReturn)
                    {
                        elementList.Add((IWebElement)listItem!);
                    }

                    returnValue = elementList.AsReadOnly();
                }
                else
                {
                    returnValue = toReturn.AsReadOnly();
                }
            }
            else
            {
                returnValue = responseValue;
            }

            return returnValue;
        }

        /// <summary>
        /// Creates a Virtual Authenticator.
        /// </summary>
        /// <param name="options"><see href="https://w3c.github.io/webauthn/#sctn-automation-virtual-authenticators">Virtual Authenticator Options</see>.</param>
        /// <returns> Authenticator id as string </returns>
        /// <exception cref="ArgumentNullException">If <paramref name="options"/> is <see langword="null"/>.</exception>
        public string AddVirtualAuthenticator(VirtualAuthenticatorOptions options)
        {
            if (options is null)
            {
                throw new ArgumentNullException(nameof(options));
            }

            Response commandResponse = this.Execute(DriverCommand.AddVirtualAuthenticator, options.ToDictionary());

            commandResponse.EnsureValueIsNotNull();
            string id = (string)commandResponse.Value;
            this.AuthenticatorId = id;
            return id;
        }

        /// <summary>
        /// Removes the Virtual Authenticator
        /// </summary>
        /// <param name="authenticatorId">Id as string that uniquely identifies a Virtual Authenticator.</param>
        /// <exception cref="ArgumentNullException">If <paramref name="authenticatorId"/> is <see langword="null"/>.</exception>
        public void RemoveVirtualAuthenticator(string authenticatorId)
        {
            if (authenticatorId is null)
            {
                throw new ArgumentNullException(nameof(authenticatorId));
            }

            Dictionary<string, object> parameters = new Dictionary<string, object>();
            parameters.Add("authenticatorId", authenticatorId);

            this.Execute(DriverCommand.RemoveVirtualAuthenticator, parameters);
            this.AuthenticatorId = null;
        }

        /// <summary>
        /// Gets the cached virtual authenticator ID, or <see langword="null"/> if no authenticator ID is set.
        /// </summary>
        public string? AuthenticatorId { get; private set; }

        /// <summary>
        /// Add a credential to the Virtual Authenticator/
        /// </summary>
        /// <param name="credential"> The credential to be stored in the Virtual Authenticator</param>
        /// <exception cref="ArgumentNullException">If <paramref name="credential"/> is <see langword="null"/>.</exception>
        /// <exception cref="InvalidOperationException">If a Virtual Authenticator has not been added yet.</exception>
        public void AddCredential(Credential credential)
        {
            if (credential is null)
            {
                throw new ArgumentNullException(nameof(credential));
            }

            string authenticatorId = this.AuthenticatorId ?? throw new InvalidOperationException("Virtual Authenticator needs to be added before it can perform operations");

            Dictionary<string, object> parameters = new Dictionary<string, object>(credential.ToDictionary());
            parameters.Add("authenticatorId", authenticatorId);

            this.Execute(driverCommandToExecute: DriverCommand.AddCredential, parameters);
        }

        /// <summary>
        /// Retrieves all the credentials stored in the Virtual Authenticator
        /// </summary>
        /// <returns> List of credentials </returns>
        /// <exception cref="InvalidOperationException">If a Virtual Authenticator has not been added yet.</exception>
        public List<Credential> GetCredentials()
        {
            string authenticatorId = this.AuthenticatorId ?? throw new InvalidOperationException("Virtual Authenticator needs to be added before it can perform operations");

            Dictionary<string, object> parameters = new Dictionary<string, object>();
            parameters.Add("authenticatorId", authenticatorId);

            Response getCredentialsResponse = this.Execute(driverCommandToExecute: DriverCommand.GetCredentials, parameters);

            getCredentialsResponse.EnsureValueIsNotNull();
            if (getCredentialsResponse.Value is not object?[] credentialsList)
            {
                throw new WebDriverException($"Get credentials call succeeded, but the response was not a list of credentials: {getCredentialsResponse.Value}");
            }

            List<Credential> credentials = new List<Credential>(credentialsList.Length);
            foreach (object? dictionary in credentialsList)
            {
                Credential credential = Credential.FromDictionary((Dictionary<string, object>)dictionary!);
                credentials.Add(credential);
            }

            return credentials;
        }

        /// <summary>
        /// Removes the credential identified by the credentialId from the Virtual Authenticator.
        /// </summary>
        /// <param name="credentialId"> The id as byte array that uniquely identifies a credential </param>
        /// <exception cref="ArgumentNullException">If <paramref name="credentialId"/> is <see langword="null"/>.</exception>
        /// <exception cref="InvalidOperationException">If a Virtual Authenticator has not been added yet.</exception>
        public void RemoveCredential(byte[] credentialId)
        {
            RemoveCredential(Base64UrlEncoder.Encode(credentialId));
        }

        /// <summary>
        /// Removes the credential identified by the credentialId from the Virtual Authenticator.
        /// </summary>
        /// <param name="credentialId"> The id as string that uniquely identifies a credential </param>
        /// <exception cref="ArgumentNullException">If <paramref name="credentialId"/> is <see langword="null"/>.</exception>
        /// <exception cref="InvalidOperationException">If a Virtual Authenticator has not been added yet.</exception>
        public void RemoveCredential(string credentialId)
        {
            if (credentialId is null)
            {
                throw new ArgumentNullException(nameof(credentialId));
            }

            string authenticatorId = this.AuthenticatorId ?? throw new InvalidOperationException("Virtual Authenticator needs to be added before it can perform operations");

            Dictionary<string, object> parameters = new Dictionary<string, object>();
            parameters.Add("authenticatorId", authenticatorId);
            parameters.Add("credentialId", credentialId);

            this.Execute(driverCommandToExecute: DriverCommand.RemoveCredential, parameters);
        }

        /// <summary>
        /// Removes all the credentials stored in the Virtual Authenticator.
        /// </summary>
        /// <exception cref="InvalidOperationException">If a Virtual Authenticator has not been added yet.</exception>
        public void RemoveAllCredentials()
        {
            string authenticatorId = this.AuthenticatorId ?? throw new InvalidOperationException("Virtual Authenticator needs to be added before it can perform operations");

            Dictionary<string, object> parameters = new Dictionary<string, object>();
            parameters.Add("authenticatorId", authenticatorId);

            this.Execute(driverCommandToExecute: DriverCommand.RemoveAllCredentials, parameters);
        }

        /// <summary>
        ///  Sets the isUserVerified property for the Virtual Authenticator.
        /// </summary>
        /// <param name="verified">The boolean value representing value to be set </param>
        public void SetUserVerified(bool verified)
        {
            string authenticatorId = this.AuthenticatorId ?? throw new InvalidOperationException("Virtual Authenticator needs to be added before it can perform operations");

            Dictionary<string, object> parameters = new Dictionary<string, object>();
            parameters.Add("authenticatorId", authenticatorId);
            parameters.Add("isUserVerified", verified);

            this.Execute(driverCommandToExecute: DriverCommand.SetUserVerified, parameters);
        }
    }
}