[dotnet] Annotate nullability on Navigate() and SwitchTo() (SeleniumHQ#15211)

Author: RenderMichael

dotnet/src/webdriver/INavigation.cs

@@ -20,6 +20,8 @@
 using System;
 using System.Threading.Tasks;
 
+#nullable enable
+
 namespace OpenQA.Selenium
 {
     /// <summary>
@@ -64,13 +66,15 @@ public interface INavigation
         /// should the underlying page change while your test is executing the results of
         /// future calls against this interface will be against the freshly loaded page.
         /// </remarks>
+        /// <exception cref="ArgumentNullException">If <paramref name="url"/> is null.</exception>
         void GoToUrl(string url);
 
         /// <summary>
         /// Navigate to a url as an asynchronous task.
         /// </summary>
         /// <param name="url">String of where you want the browser to go.</param>
         /// <returns>A task object representing the asynchronous operation.</returns>
+        /// <exception cref="ArgumentNullException">If <paramref name="url"/> is null.</exception>
         Task GoToUrlAsync(string url);
 
         /// <summary>
@@ -86,13 +90,15 @@ public interface INavigation
         /// should the underlying page change while your test is executing the results of
         /// future calls against this interface will be against the freshly loaded page.
         /// </remarks>
+        /// <exception cref="ArgumentNullException">If <paramref name="url"/> is null.</exception>
         void GoToUrl(Uri url);
 
         /// <summary>
         /// Navigate to a url as an asynchronous task.
         /// </summary>
         /// <param name="url">Uri object of where you want the browser to go.</param>
         /// <returns>A task object representing the asynchronous operation.</returns>
+        /// <exception cref="ArgumentNullException">If <paramref name="url"/> is null.</exception>
         Task GoToUrlAsync(Uri url);
 
         /// <summary>

dotnet/src/webdriver/ITargetLocator.cs

@@ -17,6 +17,10 @@
 // under the License.
 // </copyright>
 
+#nullable enable
+
+using System;
+
 namespace OpenQA.Selenium
 {
     /// <summary>
@@ -38,6 +42,7 @@ public interface ITargetLocator
         /// <param name="frameName">The name of the frame to select.</param>
         /// <returns>An <see cref="IWebDriver"/> instance focused on the specified frame.</returns>
         /// <exception cref="NoSuchFrameException">If the frame cannot be found.</exception>
+        /// <exception cref="ArgumentNullException">If <paramref name="frameName"/> is <see langword="null"/>.</exception>
         IWebDriver Frame(string frameName);
 
         /// <summary>
@@ -47,6 +52,8 @@ public interface ITargetLocator
         /// <returns>An <see cref="IWebDriver"/> instance focused on the specified frame.</returns>
         /// <exception cref="NoSuchFrameException">If the element is neither a FRAME nor an IFRAME element.</exception>
         /// <exception cref="StaleElementReferenceException">If the element is no longer valid.</exception>
+        /// <exception cref="ArgumentNullException">If <paramref name="frameElement"/> is <see langword="null"/>.</exception>
+        /// <exception cref="ArgumentException">If <paramref name="frameElement"/> cannot be converted to an <see cref="IWebDriverObjectReference"/>.</exception>
         IWebDriver Frame(IWebElement frameElement);
 
         /// <summary>
@@ -61,6 +68,7 @@ public interface ITargetLocator
         /// <param name="windowName">The name of the window to select.</param>
         /// <returns>An <see cref="IWebDriver"/> instance focused on the given window.</returns>
         /// <exception cref="NoSuchWindowException">If the window cannot be found.</exception>
+        /// <exception cref="ArgumentNullException">If <paramref name="windowName"/> is <see langword="null"/>.</exception>
         IWebDriver Window(string windowName);
 
         /// <summary>

dotnet/src/webdriver/Navigator.cs

@@ -21,22 +21,25 @@
 using System.Collections.Generic;
 using System.Threading.Tasks;
 
+#nullable enable
+
 namespace OpenQA.Selenium
 {
     /// <summary>
     /// Provides a mechanism for Navigating with the driver.
     /// </summary>
-    internal class Navigator : INavigation
+    internal sealed class Navigator : INavigation
     {
-        private WebDriver driver;
+        private readonly WebDriver driver;
 
         /// <summary>
         /// Initializes a new instance of the <see cref="Navigator"/> class
         /// </summary>
         /// <param name="driver">Driver in use</param>
+        /// <exception cref="ArgumentNullException">If <paramref name="driver"/> is null.</exception>
         public Navigator(WebDriver driver)
         {
-            this.driver = driver;
+            this.driver = driver ?? throw new ArgumentNullException(nameof(driver));
         }
 
         /// <summary>
@@ -83,6 +86,7 @@ public async Task ForwardAsync()
         /// Navigate to a url.
         /// </summary>
         /// <param name="url">String of where you want the browser to go to</param>
+        /// <exception cref="ArgumentNullException">If <paramref name="url"/> is null.</exception>
         public void GoToUrl(string url)
         {
             Task.Run(async delegate
@@ -96,6 +100,7 @@ public void GoToUrl(string url)
         /// </summary>
         /// <param name="url">String of where you want the browser to go.</param>
         /// <returns>A task object representing the asynchronous operation.</returns>
+        /// <exception cref="ArgumentNullException">If <paramref name="url"/> is null.</exception>
         public async Task GoToUrlAsync(string url)
         {
             if (url == null)
@@ -114,6 +119,7 @@ public async Task GoToUrlAsync(string url)
         /// Navigate to a url.
         /// </summary>
         /// <param name="url">Uri object of where you want the browser to go.</param>
+        /// <exception cref="ArgumentNullException">If <paramref name="url"/> is null.</exception>
         public void GoToUrl(Uri url)
         {
             Task.Run(async delegate
@@ -127,6 +133,7 @@ public void GoToUrl(Uri url)
         /// </summary>
         /// <param name="url">Uri object of where you want the browser to go.</param>
         /// <returns>A task object representing the asynchronous operation.</returns>
+        /// <exception cref="ArgumentNullException">If <paramref name="url"/> is null.</exception>
         public async Task GoToUrlAsync(Uri url)
         {
             if (url == null)

dotnet/src/webdriver/TargetLocator.cs

@@ -23,22 +23,25 @@
 using System.Collections.ObjectModel;
 using System.Text.RegularExpressions;
 
+#nullable enable
+
 namespace OpenQA.Selenium
 {
     /// <summary>
     /// Provides a mechanism for finding elements on the page with locators.
     /// </summary>
-    internal class TargetLocator : ITargetLocator
+    internal sealed class TargetLocator : ITargetLocator
     {
-        private WebDriver driver;
+        private readonly WebDriver driver;
 
         /// <summary>
         /// Initializes a new instance of the <see cref="TargetLocator"/> class
         /// </summary>
         /// <param name="driver">The driver that is currently in use</param>
+        /// <exception cref="ArgumentNullException">If <paramref name="driver"/> is <see langword="null"/>.</exception>
         public TargetLocator(WebDriver driver)
         {
-            this.driver = driver;
+            this.driver = driver ?? throw new ArgumentNullException(nameof(driver));
         }
 
         /// <summary>
@@ -59,6 +62,7 @@ public IWebDriver Frame(int frameIndex)
         /// </summary>
         /// <param name="frameName">name of the frame</param>
         /// <returns>A WebDriver instance that is currently in use</returns>
+        /// <exception cref="ArgumentNullException">If <paramref name="frameName"/> is <see langword="null"/>.</exception>
         public IWebDriver Frame(string frameName)
         {
             if (frameName == null)
@@ -85,26 +89,27 @@ public IWebDriver Frame(string frameName)
         /// </summary>
         /// <param name="frameElement">a previously found FRAME or IFRAME element.</param>
         /// <returns>A WebDriver instance that is currently in use.</returns>
+        /// <exception cref="ArgumentNullException">If <paramref name="frameElement"/> is <see langword="null"/>.</exception>
+        /// <exception cref="ArgumentException">If <paramref name="frameElement"/> cannot be converted to an <see cref="IWebDriverObjectReference"/>.</exception>
         public IWebDriver Frame(IWebElement frameElement)
         {
             if (frameElement == null)
             {
                 throw new ArgumentNullException(nameof(frameElement), "Frame element cannot be null");
             }
 
-            IWebDriverObjectReference elementReference = frameElement as IWebDriverObjectReference;
+            IWebDriverObjectReference? elementReference = frameElement as IWebDriverObjectReference;
             if (elementReference == null)
             {
-                IWrapsElement elementWrapper = frameElement as IWrapsElement;
-                if (elementWrapper != null)
+                if (frameElement is IWrapsElement elementWrapper)
                 {
                     elementReference = elementWrapper.WrappedElement as IWebDriverObjectReference;
                 }
             }
 
             if (elementReference == null)
             {
-                throw new ArgumentException("frameElement cannot be converted to IWebElementReference", nameof(frameElement));
+                throw new ArgumentException($"{nameof(frameElement)} cannot be converted to {nameof(IWebDriverObjectReference)}", nameof(frameElement));
             }
 
             Dictionary<string, object> elementDictionary = elementReference.ToDictionary();
@@ -131,8 +136,14 @@ public IWebDriver ParentFrame()
         /// </summary>
         /// <param name="windowHandleOrName">Window handle or name of the window that you wish to move to</param>
         /// <returns>A WebDriver instance that is currently in use</returns>
+        /// <exception cref="ArgumentNullException">If <paramref name="windowHandleOrName"/> is <see langword="null"/>.</exception>
         public IWebDriver Window(string windowHandleOrName)
         {
+            if (windowHandleOrName is null)
+            {
+                throw new ArgumentNullException(nameof(windowHandleOrName));
+            }
+
             Dictionary<string, object> parameters = new Dictionary<string, object>();
             parameters.Add("handle", windowHandleOrName);
             try
@@ -143,7 +154,7 @@ public IWebDriver Window(string windowHandleOrName)
             catch (NoSuchWindowException)
             {
                 // simulate search by name
-                string original = null;
+                string? original = null;
                 try
                 {
                     original = this.driver.CurrentWindowHandle;
@@ -183,10 +194,13 @@ public IWebDriver NewWindow(WindowType typeHint)
         {
             Dictionary<string, object> parameters = new Dictionary<string, object>();
             parameters.Add("type", typeHint.ToString().ToLowerInvariant());
+
             Response response = this.driver.InternalExecute(DriverCommand.NewWindow, parameters);
-            Dictionary<string, object> result = response.Value as Dictionary<string, object>;
-            string newWindowHandle = result["handle"].ToString();
+
+            Dictionary<string, object> result = (Dictionary<string, object>)response.Value!;
+            string newWindowHandle = result["handle"].ToString()!;
             this.Window(newWindowHandle);
+
             return this.driver;
         }
 
@@ -196,7 +210,7 @@ public IWebDriver NewWindow(WindowType typeHint)
         /// <returns>Element of the default</returns>
         public IWebDriver DefaultContent()
         {
-            Dictionary<string, object> parameters = new Dictionary<string, object>();
+            Dictionary<string, object?> parameters = new Dictionary<string, object?>();
             parameters.Add("id", null);
             this.driver.InternalExecute(DriverCommand.SwitchToFrame, parameters);
             return this.driver;