Merge branch 'trunk' into update

Author: RenderMichael

dotnet/src/webdriver/Firefox/FirefoxExtension.cs

@@ -25,7 +25,7 @@
 using System.Text.Json.Nodes;
 using System.Xml;
 
-
+#nullable enable
 
 namespace OpenQA.Selenium.Firefox
 {
@@ -38,8 +38,8 @@ public class FirefoxExtension
         private const string RdfManifestFileName = "install.rdf";
         private const string JsonManifestFileName = "manifest.json";
 
-        private string extensionFileName;
-        private string extensionResourceId;
+        private readonly string extensionFileName;
+        private readonly string extensionResourceId;
 
         /// <summary>
         /// Initializes a new instance of the <see cref="FirefoxExtension"/> class.
@@ -48,6 +48,7 @@ public class FirefoxExtension
         /// <remarks>WebDriver attempts to resolve the <paramref name="fileName"/> parameter
         /// by looking first for the specified file in the directory of the calling assembly,
         /// then using the full path to the file, if a full path is provided.</remarks>
+        /// <exception cref="ArgumentNullException">If <paramref name="fileName"/> is <see langword="null"/>.</exception>
         public FirefoxExtension(string fileName)
             : this(fileName, string.Empty)
         {
@@ -65,16 +66,18 @@ public FirefoxExtension(string fileName)
         /// not found in the file system, WebDriver attempts to locate a resource in the
         /// executing assembly with the name specified by the <paramref name="resourceId"/>
         /// parameter.</remarks>
+        /// <exception cref="ArgumentNullException">If <paramref name="fileName"/> or <paramref name="resourceId"/> are <see langword="null"/>.</exception>
         internal FirefoxExtension(string fileName, string resourceId)
         {
-            this.extensionFileName = fileName;
-            this.extensionResourceId = resourceId;
+            this.extensionFileName = fileName ?? throw new ArgumentNullException(nameof(fileName));
+            this.extensionResourceId = resourceId ?? throw new ArgumentNullException(nameof(resourceId));
         }
 
         /// <summary>
         /// Installs the extension into a profile directory.
         /// </summary>
         /// <param name="profileDirectory">The Firefox profile directory into which to install the extension.</param>
+        /// <exception cref="ArgumentNullException">If <paramref name="profileDirectory"/> is <see langword="null"/>.</exception>
         public void Install(string profileDirectory)
         {
             DirectoryInfo info = new DirectoryInfo(profileDirectory);
@@ -132,7 +135,7 @@ private static string GetExtensionId(string root)
 
         private static string ReadIdFromInstallRdf(string root)
         {
-            string id = null;
+            string id;
             string installRdf = Path.Combine(root, "install.rdf");
             try
             {
@@ -143,11 +146,11 @@ private static string ReadIdFromInstallRdf(string root)
                 rdfNamespaceManager.AddNamespace("em", EmNamespaceUri);
                 rdfNamespaceManager.AddNamespace("RDF", "http://www.w3.org/1999/02/22-rdf-syntax-ns#");
 
-                XmlNode node = rdfXmlDocument.SelectSingleNode("//em:id", rdfNamespaceManager);
+                XmlNode? node = rdfXmlDocument.SelectSingleNode("//em:id", rdfNamespaceManager);
                 if (node == null)
                 {
-                    XmlNode descriptionNode = rdfXmlDocument.SelectSingleNode("//RDF:Description", rdfNamespaceManager);
-                    XmlAttribute attribute = descriptionNode.Attributes["id", EmNamespaceUri];
+                    XmlNode? descriptionNode = rdfXmlDocument.SelectSingleNode("//RDF:Description", rdfNamespaceManager);
+                    XmlAttribute? attribute = descriptionNode?.Attributes?["id", EmNamespaceUri];
                     if (attribute == null)
                     {
                         throw new WebDriverException("Cannot locate node containing extension id: " + installRdf);
@@ -175,26 +178,19 @@ private static string ReadIdFromInstallRdf(string root)
 
         private static string ReadIdFromManifestJson(string root)
         {
-            string id = null;
+            string id = string.Empty;
             string manifestJsonPath = Path.Combine(root, JsonManifestFileName);
+
             var manifestObject = JsonNode.Parse(File.ReadAllText(manifestJsonPath));
-            if (manifestObject["applications"] != null)
+            if (manifestObject!["applications"]?["gecko"]?["id"] is { } idNode)
             {
-                var applicationObject = manifestObject["applications"];
-                if (applicationObject["gecko"] != null)
-                {
-                    var geckoObject = applicationObject["gecko"];
-                    if (geckoObject["id"] != null)
-                    {
-                        id = geckoObject["id"].ToString().Trim();
-                    }
-                }
+                id = idNode.ToString().Trim();
             }
 
             if (string.IsNullOrEmpty(id))
             {
-                string addInName = manifestObject["name"].ToString().Replace(" ", "");
-                string addInVersion = manifestObject["version"].ToString();
+                string addInName = manifestObject["name"]!.ToString().Replace(" ", "");
+                string addInVersion = manifestObject["version"]!.ToString();
                 id = string.Format(CultureInfo.InvariantCulture, "{0}@{1}", addInName, addInVersion);
             }
 

dotnet/src/webdriver/Firefox/FirefoxProfile.cs

@@ -114,8 +114,14 @@ public static FirefoxProfile FromBase64String(string base64)
         /// Adds a Firefox Extension to this profile
         /// </summary>
         /// <param name="extensionToInstall">The path to the new extension</param>
+        /// <exception cref="ArgumentNullException">If <paramref name="extensionToInstall"/> is <see langword="null"/>.</exception>
         public void AddExtension(string extensionToInstall)
         {
+            if (extensionToInstall is null)
+            {
+                throw new ArgumentNullException(nameof(extensionToInstall));
+            }
+
             this.extensions.Add(Path.GetFileNameWithoutExtension(extensionToInstall), new FirefoxExtension(extensionToInstall));
         }
 

py/selenium/webdriver/common/actions/action_builder.py

@@ -49,6 +49,17 @@ def __init__(
         self.driver = driver
 
     def get_device_with(self, name: str) -> Optional[Union["WheelInput", "PointerInput", "KeyInput"]]:
+        """Get the device with the given name.
+
+        Parameters:
+        ----------
+        name : str
+            The name of the device to get.
+
+        Returns:
+        --------
+        Optional[Union[WheelInput, PointerInput, KeyInput]] : The device with the given name.
+        """
         return next(filter(lambda x: x == name, self.devices), None)
 
     @property
@@ -72,21 +83,83 @@ def wheel_action(self) -> WheelActions:
         return self._wheel_action
 
     def add_key_input(self, name: str) -> KeyInput:
+        """Add a new key input device to the action builder.
+
+        Parameters:
+        ----------
+        name : str
+            The name of the key input device.
+
+        Returns:
+        --------
+        KeyInput : The newly created key input device.
+
+        Example:
+        --------
+        >>> action_builder = ActionBuilder(driver)
+        >>> action_builder.add_key_input(name="keyboard2")
+        """
         new_input = KeyInput(name)
         self._add_input(new_input)
         return new_input
 
     def add_pointer_input(self, kind: str, name: str) -> PointerInput:
+        """Add a new pointer input device to the action builder.
+
+        Parameters:
+        ----------
+        kind : str
+            The kind of pointer input device.
+                - "mouse"
+                - "touch"
+                - "pen"
+        name : str
+            The name of the pointer input device.
+
+        Returns:
+        --------
+        PointerInput : The newly created pointer input device.
+
+        Example:
+        --------
+        >>> action_builder = ActionBuilder(driver)
+        >>> action_builder.add_pointer_input(kind="mouse", name="mouse")
+        """
         new_input = PointerInput(kind, name)
         self._add_input(new_input)
         return new_input
 
     def add_wheel_input(self, name: str) -> WheelInput:
+        """Add a new wheel input device to the action builder.
+
+        Parameters:
+        ----------
+        name : str
+            The name of the wheel input device.
+
+        Returns:
+        --------
+        WheelInput : The newly created wheel input device.
+
+        Example:
+        --------
+        >>> action_builder = ActionBuilder(driver)
+        >>> action_builder.add_wheel_input(name="wheel2")
+        """
         new_input = WheelInput(name)
         self._add_input(new_input)
         return new_input
 
     def perform(self) -> None:
+        """Performs all stored actions.
+
+        Example:
+        --------
+        >>> action_builder = ActionBuilder(driver)
+        >>> keyboard = action_builder.key_input
+        >>> el = driver.find_element(id: "some_id")
+        >>> action_builder.click(el).pause(keyboard).pause(keyboard).pause(keyboard).send_keys('keys').perform()
+        """
         enc = {"actions": []}
         for device in self.devices:
             encoded = device.encode()
@@ -96,8 +169,24 @@ def perform(self) -> None:
         self.driver.execute(Command.W3C_ACTIONS, enc)
 
     def clear_actions(self) -> None:
-        """Clears actions that are already stored on the remote end."""
+        """Clears actions that are already stored on the remote end.
+
+        Example:
+        --------
+        >>> action_builder = ActionBuilder(driver)
+        >>> keyboard = action_builder.key_input
+        >>> el = driver.find_element(By.ID, "some_id")
+        >>> action_builder.click(el).pause(keyboard).pause(keyboard).pause(keyboard).send_keys('keys')
+        >>> action_builder.clear_actions()
+        """
         self.driver.execute(Command.W3C_CLEAR_ACTIONS)
 
     def _add_input(self, new_input: Union[KeyInput, PointerInput, WheelInput]) -> None:
+        """Add a new input device to the action builder.
+
+        Parameters:
+        ----------
+        new_input : Union[KeyInput, PointerInput, WheelInput]
+            The new input device to add.
+        """
         self.devices.append(new_input)