| // <copyright file="ChromiumDriver.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.Collections.ObjectModel; | |
| using System.Diagnostics.CodeAnalysis; | |
| using OpenQA.Selenium.DevTools; | |
| using OpenQA.Selenium.Remote; | |
| namespace OpenQA.Selenium.Chromium; | |
| /// <summary> | |
| /// Provides an abstract way to access Chromium-based browsers to run tests. | |
| /// </summary> | |
| public class ChromiumDriver : WebDriver, ISupportsLogs, IDevTools | |
| { | |
| /// <summary> | |
| /// Accept untrusted SSL Certificates | |
| /// </summary> | |
| protected static readonly bool AcceptUntrustedCertificates = true; | |
| /// <summary> | |
| /// Command for executing a Chrome DevTools Protocol command in a driver for a Chromium-based browser. | |
| /// </summary> | |
| protected static readonly string ExecuteCdp = "executeCdpCommand"; | |
| /// <summary> | |
| /// Command for getting cast sinks in a driver for a Chromium-based browser. | |
| /// </summary> | |
| protected static readonly string GetCastSinksCommand = "getCastSinks"; | |
| /// <summary> | |
| /// Command for selecting a cast sink in a driver for a Chromium-based browser. | |
| /// </summary> | |
| protected static readonly string SelectCastSinkCommand = "selectCastSink"; | |
| /// <summary> | |
| /// Command for starting cast tab mirroring in a driver for a Chromium-based browser. | |
| /// </summary> | |
| protected static readonly string StartCastTabMirroringCommand = "startCastTabMirroring"; | |
| /// <summary> | |
| /// Command for starting cast desktop mirroring in a driver for a Chromium-based browser. | |
| /// </summary> | |
| protected static readonly string StartCastDesktopMirroringCommand = "startCastDesktopMirroring"; | |
| /// <summary> | |
| /// Command for getting a cast issued message in a driver for a Chromium-based browser. | |
| /// </summary> | |
| protected static readonly string GetCastIssueMessageCommand = "getCastIssueMessage"; | |
| /// <summary> | |
| /// Command for stopping casting in a driver for a Chromium-based browser. | |
| /// </summary> | |
| protected static readonly string StopCastingCommand = "stopCasting"; | |
| /// <summary> | |
| /// Command for getting the simulated network conditions in a driver for a Chromium-based browser. | |
| /// </summary> | |
| protected static readonly string GetNetworkConditionsCommand = "getNetworkConditions"; | |
| /// <summary> | |
| /// Command for setting the simulated network conditions in a driver for a Chromium-based browser. | |
| /// </summary> | |
| protected static readonly string SetNetworkConditionsCommand = "setNetworkConditions"; | |
| /// <summary> | |
| /// Command for deleting the simulated network conditions in a driver for a Chromium-based browser. | |
| /// </summary> | |
| protected static readonly string DeleteNetworkConditionsCommand = "deleteNetworkConditions"; | |
| /// <summary> | |
| /// Command for executing a Chrome DevTools Protocol command in a driver for a Chromium-based browser. | |
| /// </summary> | |
| protected static readonly string SendChromeCommand = "sendChromeCommand"; | |
| /// <summary> | |
| /// Command for executing a Chrome DevTools Protocol command that returns a result in a driver for a Chromium-based browser. | |
| /// </summary> | |
| protected static readonly string SendChromeCommandWithResult = "sendChromeCommandWithResult"; | |
| /// <summary> | |
| /// Command for launching an app in a driver for a Chromium-based browser. | |
| /// </summary> | |
| protected static readonly string LaunchAppCommand = "launchAppCommand"; | |
| /// <summary> | |
| /// Command for setting permissions in a driver for a Chromium-based browser. | |
| /// </summary> | |
| protected static readonly string SetPermissionCommand = "setPermission"; | |
| private readonly string optionsCapabilityName; | |
| private DevToolsSession? devToolsSession; | |
| private static readonly Dictionary<string, CommandInfo> chromiumCustomCommands = new Dictionary<string, CommandInfo>() | |
| { | |
| { GetNetworkConditionsCommand, new HttpCommandInfo(HttpCommandInfo.GetCommand, "/session/{sessionId}/chromium/network_conditions") }, | |
| { SetNetworkConditionsCommand, new HttpCommandInfo(HttpCommandInfo.PostCommand, "/session/{sessionId}/chromium/network_conditions") }, | |
| { DeleteNetworkConditionsCommand, new HttpCommandInfo(HttpCommandInfo.DeleteCommand, "/session/{sessionId}/chromium/network_conditions") }, | |
| { SendChromeCommand, new HttpCommandInfo(HttpCommandInfo.PostCommand, "/session/{sessionId}/chromium/send_command") }, | |
| { SendChromeCommandWithResult, new HttpCommandInfo(HttpCommandInfo.PostCommand, "/session/{sessionId}/chromium/send_command_and_get_result") }, | |
| { LaunchAppCommand, new HttpCommandInfo(HttpCommandInfo.PostCommand, "/session/{sessionId}/chromium/launch_app") }, | |
| { SetPermissionCommand, new HttpCommandInfo(HttpCommandInfo.PostCommand, "/session/{sessionId}/permissions") } | |
| }; | |
| /// <summary> | |
| /// Initializes a new instance of the <see cref="ChromiumDriver"/> class using the specified <see cref="ChromiumDriverService"/>. | |
| /// </summary> | |
| /// <param name="service">The <see cref="ChromiumDriverService"/> to use.</param> | |
| /// <param name="options">The <see cref="ChromiumOptions"/> to be used with the ChromiumDriver.</param> | |
| /// <param name="commandTimeout">The maximum amount of time to wait for each command.</param> | |
| /// <exception cref="ArgumentNullException">If <paramref name="service"/> or <paramref name="options"/> are <see langword="null"/>.</exception> | |
| /// <exception cref="ArgumentException">If the Chromium options capability name is <see langword="null"/>.</exception> | |
| protected ChromiumDriver(ChromiumDriverService service, ChromiumOptions options, TimeSpan commandTimeout) | |
| : base(GenerateDriverServiceCommandExecutor(service, options, commandTimeout), ConvertOptionsToCapabilities(options)) | |
| { | |
| this.optionsCapabilityName = options.CapabilityName ?? throw new ArgumentException("No chromium options capability name specified", nameof(options)); | |
| } | |
| /// <summary> | |
| /// Gets the dictionary of custom Chromium commands registered with the driver. | |
| /// </summary> | |
| protected static IReadOnlyDictionary<string, CommandInfo> ChromiumCustomCommands => new ReadOnlyDictionary<string, CommandInfo>(chromiumCustomCommands); | |
| private static ICommandExecutor GenerateDriverServiceCommandExecutor(DriverService service, DriverOptions options, TimeSpan commandTimeout) | |
| { | |
| return Task.Run(async () => | |
| await GenerateDriverServiceCommandExecutorAsync(service, options, commandTimeout).ConfigureAwait(false)) | |
| .GetAwaiter().GetResult(); | |
| } | |
| private static async Task<ICommandExecutor> GenerateDriverServiceCommandExecutorAsync(DriverService service, DriverOptions options, TimeSpan commandTimeout) | |
| { | |
| if (service is null) | |
| { | |
| throw new ArgumentNullException(nameof(service)); | |
| } | |
| if (options is null) | |
| { | |
| throw new ArgumentNullException(nameof(options)); | |
| } | |
| if (service.DriverServicePath == null && service.DriverPathFromEnvironment == null) | |
| { | |
| DriverFinder finder = new DriverFinder(options); | |
| string fullServicePath = await finder.GetDriverPathAsync().ConfigureAwait(false); | |
| service.DriverServicePath = Path.GetDirectoryName(fullServicePath); | |
| service.DriverServiceExecutableName = Path.GetFileName(fullServicePath); | |
| string fullBrowserPath = await finder.GetBrowserPathAsync().ConfigureAwait(false); | |
| options.BinaryLocation = fullBrowserPath; | |
| options.BrowserVersion = null; | |
| } | |
| try | |
| { | |
| await service.StartAsync().ConfigureAwait(false); | |
| return new DriverServiceCommandExecutor(service, commandTimeout); | |
| } | |
| catch | |
| { | |
| try | |
| { | |
| await service.DisposeAsync().ConfigureAwait(false); | |
| } | |
| catch | |
| { | |
| // Ignore exceptions thrown while disposing the service to preserve the original exception. | |
| } | |
| throw; | |
| } | |
| } | |
| /// <summary> | |
| /// Gets or sets the <see cref="IFileDetector"/> responsible for detecting | |
| /// sequences of keystrokes representing file paths and names. | |
| /// </summary> | |
| /// <remarks>The Chromium driver does not allow a file detector to be set, | |
| /// as the server component of the Chromium driver only | |
| /// allows uploads from the local computer environment. Attempting to set | |
| /// this property has no effect, but does not throw an exception. If you | |
| /// are attempting to run the Chromium driver remotely, use <see cref="RemoteWebDriver"/> | |
| /// in conjunction with a standalone WebDriver server.</remarks> | |
| public override IFileDetector FileDetector | |
| { | |
| get => base.FileDetector; | |
| set { } | |
| } | |
| /// <summary> | |
| /// Gets a value indicating whether a DevTools session is active. | |
| /// </summary> | |
| [MemberNotNullWhen(true, nameof(devToolsSession))] | |
| public bool HasActiveDevToolsSession => this.devToolsSession != null; | |
| /// <summary> | |
| /// Gets or sets the network condition emulation for Chromium. | |
| /// </summary> | |
| /// <exception cref="ArgumentNullException">If the value is set to <see langword="null"/>.</exception> | |
| public ChromiumNetworkConditions NetworkConditions | |
| { | |
| get | |
| { | |
| Response response = this.Execute(GetNetworkConditionsCommand, null); | |
| if (response.Value is not Dictionary<string, object?> responseDictionary) | |
| { | |
| throw new WebDriverException($"GetNetworkConditions command returned successfully, but data was not an object: {response.Value}"); | |
| } | |
| return ChromiumNetworkConditions.FromDictionary(responseDictionary); | |
| } | |
| set | |
| { | |
| if (value == null) | |
| { | |
| throw new ArgumentNullException(nameof(value), "value must not be null"); | |
| } | |
| Dictionary<string, object?> parameters = new Dictionary<string, object?>(); | |
| parameters["network_conditions"] = value; | |
| this.Execute(SetNetworkConditionsCommand, parameters); | |
| } | |
| } | |
| /// <summary> | |
| /// Launches a Chromium based application. | |
| /// </summary> | |
| /// <param name="id">ID of the chromium app to launch.</param> | |
| /// <exception cref="ArgumentNullException">If <paramref name="id"/> is <see langword="null"/>.</exception> | |
| public void LaunchApp(string id) | |
| { | |
| if (id == null) | |
| { | |
| throw new ArgumentNullException(nameof(id), "id must not be null"); | |
| } | |
| Dictionary<string, object?> parameters = new Dictionary<string, object?>(); | |
| parameters["id"] = id; | |
| this.Execute(LaunchAppCommand, parameters); | |
| } | |
| /// <summary> | |
| /// Set supported permission on browser. | |
| /// </summary> | |
| /// <param name="permissionName">Name of item to set the permission on.</param> | |
| /// <param name="permissionValue">Value to set the permission to.</param> | |
| /// <exception cref="ArgumentNullException">If <paramref name="permissionName"/> or <paramref name="permissionValue"/> are <see langword="null"/>.</exception> | |
| public void SetPermission(string permissionName, string permissionValue) | |
| { | |
| if (permissionName == null) | |
| { | |
| throw new ArgumentNullException(nameof(permissionName), "name must not be null"); | |
| } | |
| if (permissionValue == null) | |
| { | |
| throw new ArgumentNullException(nameof(permissionValue), "value must not be null"); | |
| } | |
| Dictionary<string, object?> nameParameter = new Dictionary<string, object?>(); | |
| nameParameter["name"] = permissionName; | |
| Dictionary<string, object?> parameters = new Dictionary<string, object?>(); | |
| parameters["descriptor"] = nameParameter; | |
| parameters["state"] = permissionValue; | |
| this.Execute(SetPermissionCommand, parameters); | |
| } | |
| /// <summary> | |
| /// Executes a custom Chrome Dev Tools Protocol Command. | |
| /// </summary> | |
| /// <param name="commandName">Name of the command to execute.</param> | |
| /// <param name="commandParameters">Parameters of the command to execute.</param> | |
| /// <returns>An object representing the result of the command, if applicable.</returns> | |
| /// <exception cref="ArgumentNullException">If <paramref name="commandName"/> is <see langword="null"/>.</exception> | |
| public object? ExecuteCdpCommand(string commandName, Dictionary<string, object?> commandParameters) | |
| { | |
| if (commandName == null) | |
| { | |
| throw new ArgumentNullException(nameof(commandName), "commandName must not be null"); | |
| } | |
| Dictionary<string, object?> parameters = new Dictionary<string, object?>(); | |
| parameters["cmd"] = commandName; | |
| parameters["params"] = commandParameters; | |
| Response response = this.Execute(ExecuteCdp, parameters); | |
| return response.Value; | |
| } | |
| /// <summary> | |
| /// Creates a session to communicate with a browser using the Chromium Developer Tools debugging protocol. | |
| /// </summary> | |
| /// <returns>The active session to use to communicate with the Chromium Developer Tools debugging protocol.</returns> | |
| [RequiresUnreferencedCode(DevToolsSession.CDP_AOTIncompatibilityMessage)] | |
| [RequiresDynamicCode(DevToolsSession.CDP_AOTIncompatibilityMessage)] | |
| public DevToolsSession GetDevToolsSession() | |
| { | |
| return GetDevToolsSession(new DevToolsOptions() { ProtocolVersion = DevToolsSession.AutoDetectDevToolsProtocolVersion }); | |
| } | |
| /// <summary> | |
| /// Creates a session to communicate with a browser using the Chromium Developer Tools debugging protocol. | |
| /// </summary> | |
| /// <returns>The active session to use to communicate with the Chromium Developer Tools debugging protocol.</returns> | |
| [RequiresUnreferencedCode(DevToolsSession.CDP_AOTIncompatibilityMessage)] | |
| [RequiresDynamicCode(DevToolsSession.CDP_AOTIncompatibilityMessage)] | |
| public DevToolsSession GetDevToolsSession(DevToolsOptions options) | |
| { | |
| if (this.devToolsSession == null) | |
| { | |
| if (!this.Capabilities.HasCapability(this.optionsCapabilityName)) | |
| { | |
| throw new WebDriverException("Cannot find " + this.optionsCapabilityName + " capability for driver"); | |
| } | |
| object? optionsCapabilityObject = this.Capabilities.GetCapability(this.optionsCapabilityName); | |
| if (optionsCapabilityObject is not Dictionary<string, object?> optionsCapability) | |
| { | |
| throw new WebDriverException($"Found {this.optionsCapabilityName} capability, but is not an object: {optionsCapabilityObject}"); | |
| } | |
| if (!optionsCapability.TryGetValue("debuggerAddress", out object? debuggerAddress)) | |
| { | |
| throw new WebDriverException("Did not find debuggerAddress capability in " + this.optionsCapabilityName); | |
| } | |
| try | |
| { | |
| DevToolsSession session = new DevToolsSession(debuggerAddress?.ToString()!, options); | |
| Task.Run(async () => await session.StartSession()).GetAwaiter().GetResult(); | |
| this.devToolsSession = session; | |
| } | |
| catch (Exception e) | |
| { | |
| throw new WebDriverException("Unexpected error creating WebSocket DevTools session.", e); | |
| } | |
| } | |
| return this.devToolsSession; | |
| } | |
| /// <summary> | |
| /// Closes a DevTools session. | |
| /// </summary> | |
| [RequiresUnreferencedCode(DevToolsSession.CDP_AOTIncompatibilityMessage)] | |
| [RequiresDynamicCode(DevToolsSession.CDP_AOTIncompatibilityMessage)] | |
| public void CloseDevToolsSession() | |
| { | |
| if (this.devToolsSession != null) | |
| { | |
| Task.Run(async () => await this.devToolsSession.StopSession(manualDetach: true)).GetAwaiter().GetResult(); | |
| } | |
| } | |
| /// <summary> | |
| /// Clears simulated network conditions. | |
| /// </summary> | |
| public void ClearNetworkConditions() | |
| { | |
| this.Execute(DeleteNetworkConditionsCommand, null); | |
| } | |
| /// <summary> | |
| /// Returns the list of cast sinks (Cast devices) available to the Chrome media router. | |
| /// </summary> | |
| /// <returns>The list of available sinks.</returns> | |
| public List<Dictionary<string, string>> GetCastSinks() | |
| { | |
| List<Dictionary<string, string>> returnValue = new List<Dictionary<string, string>>(); | |
| Response response = this.Execute(GetCastSinksCommand, null); | |
| if (response.Value is object?[] responseValue) | |
| { | |
| foreach (object? entry in responseValue) | |
| { | |
| if (entry is Dictionary<string, object?> entryValue) | |
| { | |
| Dictionary<string, string> sink = new Dictionary<string, string>(); | |
| foreach (KeyValuePair<string, object?> pair in entryValue) | |
| { | |
| sink[pair.Key] = pair.Value!.ToString()!; | |
| } | |
| returnValue.Add(sink); | |
| } | |
| } | |
| } | |
| return returnValue; | |
| } | |
| /// <summary> | |
| /// Selects a cast sink (Cast device) as the recipient of media router intents (connect or play). | |
| /// </summary> | |
| /// <param name="deviceName">Name of the target sink (device).</param> | |
| public void SelectCastSink(string deviceName) | |
| { | |
| if (deviceName == null) | |
| { | |
| throw new ArgumentNullException(nameof(deviceName), "deviceName must not be null"); | |
| } | |
| Dictionary<string, object?> parameters = new Dictionary<string, object?>(); | |
| parameters["sinkName"] = deviceName; | |
| this.Execute(SelectCastSinkCommand, parameters); | |
| } | |
| /// <summary> | |
| /// Initiates tab mirroring for the current browser tab on the specified device. | |
| /// </summary> | |
| /// <param name="deviceName">Name of the target sink (device).</param> | |
| public void StartTabMirroring(string deviceName) | |
| { | |
| if (deviceName == null) | |
| { | |
| throw new ArgumentNullException(nameof(deviceName), "deviceName must not be null"); | |
| } | |
| Dictionary<string, object?> parameters = new Dictionary<string, object?>(); | |
| parameters["sinkName"] = deviceName; | |
| this.Execute(StartCastTabMirroringCommand, parameters); | |
| } | |
| /// <summary> | |
| /// Initiates mirroring of the desktop on the specified device. | |
| /// </summary> | |
| /// <param name="deviceName">Name of the target sink (device).</param> | |
| public void StartDesktopMirroring(string deviceName) | |
| { | |
| if (deviceName == null) | |
| { | |
| throw new ArgumentNullException(nameof(deviceName), "deviceName must not be null"); | |
| } | |
| Dictionary<string, object?> parameters = new Dictionary<string, object?>(); | |
| parameters["sinkName"] = deviceName; | |
| this.Execute(StartCastDesktopMirroringCommand, parameters); | |
| } | |
| /// <summary> | |
| /// Returns the error message if there is any issue in a Cast session. | |
| /// </summary> | |
| /// <returns>An error message.</returns> | |
| public string? GetCastIssueMessage() | |
| { | |
| Response response = this.Execute(GetCastIssueMessageCommand, null); | |
| return (string?)response.Value; | |
| } | |
| /// <summary> | |
| /// Stops casting from media router to the specified device, if connected. | |
| /// </summary> | |
| /// <param name="deviceName">Name of the target sink (device).</param> | |
| public void StopCasting(string deviceName) | |
| { | |
| if (deviceName == null) | |
| { | |
| throw new ArgumentNullException(nameof(deviceName), "deviceName must not be null"); | |
| } | |
| Dictionary<string, object?> parameters = new Dictionary<string, object?>(); | |
| parameters["sinkName"] = deviceName; | |
| this.Execute(StopCastingCommand, parameters); | |
| } | |
| /// <summary> | |
| /// Disposes of the resources used by the <see cref="ChromiumDriver"/> instance, including any active DevTools session. | |
| /// </summary> | |
| /// <param name="disposing">Indicates whether the method is being called from a Dispose method (true) or from a finalizer (false).</param> | |
| protected override void Dispose(bool disposing) | |
| { | |
| if (disposing) | |
| { | |
| if (this.devToolsSession != null) | |
| { | |
| this.devToolsSession.Dispose(); | |
| this.devToolsSession = null; | |
| } | |
| } | |
| base.Dispose(disposing); | |
| } | |
| /// <summary> | |
| /// Asynchronously disposes of the resources used by the <see cref="ChromiumDriver"/> instance, including any active DevTools session. | |
| /// </summary> | |
| /// <returns>A task representing the asynchronous dispose operation.</returns> | |
| protected override async ValueTask DisposeAsyncCore() | |
| { | |
| if (this.devToolsSession != null) | |
| { | |
| this.devToolsSession.Dispose(); | |
| this.devToolsSession = null; | |
| } | |
| await base.DisposeAsyncCore().ConfigureAwait(false); | |
| } | |
| private static ICapabilities ConvertOptionsToCapabilities(ChromiumOptions options) | |
| { | |
| if (options == null) | |
| { | |
| throw new ArgumentNullException(nameof(options), "options must not be null"); | |
| } | |
| return options.ToCapabilities(); | |
| } | |
| } |