Align webdriver errors with spec, mitigate breaking change

Author: RenderMichael

dotnet/src/webdriver/UnknownMethodException.cs

@@ -0,0 +1,49 @@
+// <copyright file="UnknownMethodException.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;
+
+#nullable enable
+
+namespace OpenQA.Selenium
+{
+    /// <summary>
+    /// Exception that is thrown when the requested command matched a known URL but did not match any method for that URL.
+    /// </summary>
+    [Serializable]
+    public class UnknownMethodException : WebDriverException
+    {
+        /// <summary>
+        /// Initializes a new instance of the <see cref="UnknownMethodException"/> class with the specified message.
+        /// </summary>
+        /// <param name="message">The message of the exception.</param>
+        public UnknownMethodException(string? message) : base(message)
+        {
+        }
+
+        /// <summary>
+        /// Initializes a new instance of the <see cref="UnknownMethodException"/> class with the specified message and inner exception.
+        /// </summary>
+        /// <param name="message">The message of the exception.</param>
+        /// <param name="innerException">The inner exception for this exception.</param>
+        public UnknownMethodException(string? message, Exception? innerException) : base(message, innerException)
+        {
+        }
+    }
+}

dotnet/src/webdriver/WebDriver.cs

@@ -854,6 +854,9 @@ private static void UnpackAndThrowOnError(Response errorResponse, string command
                         case WebDriverResult.UnknownError:
                             throw new UnknownErrorException(errorMessage);
 
+                        case WebDriverResult.UnknownMethod:
+                            throw new UnknownMethodException(errorMessage);
+
                         case WebDriverResult.UnsupportedOperation:
                             throw new UnsupportedOperationException(errorMessage);
 

dotnet/src/webdriver/WebDriverError.cs

@@ -27,32 +27,16 @@ namespace OpenQA.Selenium
     /// </summary>
     internal static class WebDriverError
     {
-        /// <summary>
-        /// Represents the detached shadow root error.
-        /// </summary>
-        public const string DetachedShadowRoot = "detached shadow root";
-
         /// <summary>
         /// Represents the element click intercepted error.
         /// </summary>
         public const string ElementClickIntercepted = "element click intercepted";
 
-        /// <summary>
-        /// Represents the element not selectable error.
-        /// </summary>
-        public const string ElementNotSelectable = "element not selectable";
-
         /// <summary>
         /// Represents the element not interactable error.
         /// </summary>
         public const string ElementNotInteractable = "element not interactable";
 
-        /// <summary>
-        /// Represents the element not visible error.
-        /// </summary>
-        /// TODO: Remove this string; it is no longer valid in the specification.
-        public const string ElementNotVisible = "element not visible";
-
         /// <summary>
         /// Represents the insecure certificate error.
         /// </summary>
@@ -68,17 +52,6 @@ internal static class WebDriverError
         /// </summary>
         public const string InvalidCookieDomain = "invalid cookie domain";
 
-        /// <summary>
-        /// Represents the invalid coordinates error.
-        /// </summary>
-        public const string InvalidCoordinates = "invalid coordinates";
-
-        /// <summary>
-        /// Represents the invalid element coordinates error.
-        /// </summary>
-        /// TODO: Remove this string; it is no longer valid in the specification.
-        public const string InvalidElementCoordinates = "invalid element coordinates";
-
         /// <summary>
         /// Represents the invalid element state error.
         /// </summary>
@@ -149,6 +122,11 @@ internal static class WebDriverError
         /// </summary>
         public const string StaleElementReference = "stale element reference";
 
+        /// <summary>
+        /// Represents the detached shadow root error.
+        /// </summary>
+        public const string DetachedShadowRoot = "detached shadow root";
+
         /// <summary>
         /// Represents the timeout error.
         /// </summary>
@@ -189,21 +167,38 @@ internal static class WebDriverError
         /// </summary>
         public const string UnsupportedOperation = "unsupported operation";
 
+        /// <summary>
+        /// Represents the element not selectable error.
+        /// </summary>
+        public const string ElementNotSelectable = "element not selectable";
+
+        /// <summary>
+        /// Represents the element not visible error.
+        /// </summary>
+        /// TODO: Remove this string; it is no longer valid in the specification.
+        public const string ElementNotVisible = "element not visible";
+
+        /// <summary>
+        /// Represents the invalid coordinates error.
+        /// </summary>
+        public const string InvalidCoordinates = "invalid coordinates";
+
+        /// <summary>
+        /// Represents the invalid element coordinates error.
+        /// </summary>
+        /// TODO: Remove this string; it is no longer valid in the specification.
+        public const string InvalidElementCoordinates = "invalid element coordinates";
+
         private static readonly Dictionary<string, WebDriverResult> resultMap;
 
         static WebDriverError()
         {
             resultMap = new Dictionary<string, WebDriverResult>();
-            resultMap[DetachedShadowRoot] = WebDriverResult.DetachedShadowRoot;
             resultMap[ElementClickIntercepted] = WebDriverResult.ElementClickIntercepted;
-            resultMap[ElementNotSelectable] = WebDriverResult.ElementNotSelectable;
-            resultMap[ElementNotVisible] = WebDriverResult.ElementNotDisplayed;
             resultMap[ElementNotInteractable] = WebDriverResult.ElementNotInteractable;
             resultMap[InsecureCertificate] = WebDriverResult.InsecureCertificate;
             resultMap[InvalidArgument] = WebDriverResult.InvalidArgument;
             resultMap[InvalidCookieDomain] = WebDriverResult.InvalidCookieDomain;
-            resultMap[InvalidCoordinates] = WebDriverResult.InvalidElementCoordinates;
-            resultMap[InvalidElementCoordinates] = WebDriverResult.InvalidElementCoordinates;
             resultMap[InvalidElementState] = WebDriverResult.InvalidElementState;
             resultMap[InvalidSelector] = WebDriverResult.InvalidSelector;
             resultMap[InvalidSessionId] = WebDriverResult.NoSuchDriver;
@@ -218,14 +213,21 @@ static WebDriverError()
             resultMap[ScriptTimeout] = WebDriverResult.AsyncScriptTimeout;
             resultMap[SessionNotCreated] = WebDriverResult.SessionNotCreated;
             resultMap[StaleElementReference] = WebDriverResult.ObsoleteElement;
+            resultMap[DetachedShadowRoot] = WebDriverResult.DetachedShadowRoot;
             resultMap[Timeout] = WebDriverResult.Timeout;
             resultMap[UnableToSetCookie] = WebDriverResult.UnableToSetCookie;
             resultMap[UnableToCaptureScreen] = WebDriverResult.UnableToCaptureScreen;
             resultMap[UnexpectedAlertOpen] = WebDriverResult.UnexpectedAlertOpen;
             resultMap[UnknownCommand] = WebDriverResult.UnknownCommand;
             resultMap[UnknownError] = WebDriverResult.UnknownError;
-            resultMap[UnknownMethod] = WebDriverResult.UnknownCommand;
+            resultMap[UnknownMethod] = WebDriverResult.UnknownMethod;
             resultMap[UnsupportedOperation] = WebDriverResult.UnsupportedOperation;
+
+            // TODO: Remove these strings; it is no longer valid in the specification.
+            resultMap[ElementNotSelectable] = WebDriverResult.ElementNotSelectable;
+            resultMap[ElementNotVisible] = WebDriverResult.ElementNotDisplayed;
+            resultMap[InvalidCoordinates] = WebDriverResult.InvalidElementCoordinates;
+            resultMap[InvalidElementCoordinates] = WebDriverResult.InvalidElementCoordinates;
         }
 
         /// <summary>

dotnet/src/webdriver/WebDriverResult.cs

@@ -17,6 +17,8 @@
 // under the License.
 // </copyright>
 
+using System;
+
 namespace OpenQA.Selenium
 {
     /// <summary>
@@ -55,27 +57,27 @@ public enum WebDriverResult
         NoStringWrapper = 5,
 
         /// <summary>
-        /// No driver matching the criteria exists.
+        /// Occurs if the given <see href="https://www.w3.org/TR/webdriver2/#dfn-session-id">session id</see> is not in the list of <see href="https://www.w3.org/TR/webdriver2/#dfn-active-sessions">active sessions</see>, meaning the session either does not exist or that it's not active.
         /// </summary>
         NoSuchDriver = 6,
 
         /// <summary>
-        /// No element matching the criteria exists.
+        /// An element could not be located on the page using the given search parameters.
         /// </summary>
         NoSuchElement = 7,
 
         /// <summary>
-        /// No frame matching the criteria exists.
+        /// A command to switch to a frame could not be satisfied because the frame could not be found.
         /// </summary>
         NoSuchFrame = 8,
 
         /// <summary>
-        /// The functionality is not supported.
+        /// A command could not be executed because the <see href="https://www.w3.org/TR/webdriver2/#dfn-remote-ends">remote end</see> is not aware of it.
         /// </summary>
         UnknownCommand = 9,
 
         /// <summary>
-        /// The specified element is no longer valid.
+        /// A command failed because the referenced element is no longer attached to the DOM.
         /// </summary>
         ObsoleteElement = 10,
 
@@ -85,15 +87,21 @@ public enum WebDriverResult
         ElementNotDisplayed = 11,
 
         /// <summary>
-        /// The specified element is not enabled.
+        /// A command could not be completed because the element is in an invalid state, e.g. attempting to <see href="https://www.w3.org/TR/webdriver2/#dfn-element-clear">clear</see> an element that isn't both <see href="https://www.w3.org/TR/webdriver2/#dfn-editable">editable</see> and <see href="https://www.w3.org/TR/webdriver2/#dfn-resettable-elements">resettable</see>.
         /// </summary>
         InvalidElementState = 12,
 
         /// <summary>
-        /// An unknown error occurred in the remote end while processing the command.
+        /// An unknown error occurred in the <see href="https://www.w3.org/TR/webdriver2/#dfn-remote-ends">remote end</see> while processing the command.
         /// </summary>
         UnknownError = 13,
 
+        /// <summary>
+        /// An unhandled error occurred.
+        /// </summary>
+        [Obsolete("This value is no longer set for unknown errors: use UnknownError instead")]
+        UnhandledError = UnknownError,
+
         /// <summary>
         /// An error occurred, but it was expected.
         /// </summary>
@@ -110,7 +118,7 @@ public enum WebDriverResult
         NoSuchDocument = 16,
 
         /// <summary>
-        /// An unexpected JavaScript error occurred.
+        /// An error occurred while executing JavaScript supplied by the user.
         /// </summary>
         UnexpectedJavaScriptError = 17,
 
@@ -130,7 +138,7 @@ public enum WebDriverResult
         NoSuchCollection = 20,
 
         /// <summary>
-        /// A timeout occurred.
+        /// An operation did not complete before its timeout expired.
         /// </summary>
         Timeout = 21,
 
@@ -140,32 +148,32 @@ public enum WebDriverResult
         NullPointer = 22,
 
         /// <summary>
-        /// No window matching the criteria exists.
+        /// A command to switch to a window could not be satisfied because the window could not be found.
         /// </summary>
         NoSuchWindow = 23,
 
         /// <summary>
-        /// An illegal attempt was made to set a cookie under a different domain than the current page.
+        /// An illegal attempt was made to set a cookie under a different domain than the current page..
         /// </summary>
         InvalidCookieDomain = 24,
 
         /// <summary>
-        /// A request to set a cookie's value could not be satisfied.
+        /// A command to set a cookie's value could not be satisfied.
         /// </summary>
         UnableToSetCookie = 25,
 
         /// <summary>
-        /// An alert was found open unexpectedly.
+        /// A modal dialog was open, blocking this operation.
         /// </summary>
         UnexpectedAlertOpen = 26,
 
         /// <summary>
-        /// A request was made to switch to an alert, but no alert is currently open.
+        /// An attempt was made to operate on a modal dialog when one was not open.
         /// </summary>
         NoAlertPresent = 27,
 
         /// <summary>
-        /// An asynchronous JavaScript execution timed out.
+        /// A script did not complete before its timeout expired.
         /// </summary>
         AsyncScriptTimeout = 28,
 
@@ -175,17 +183,17 @@ public enum WebDriverResult
         InvalidElementCoordinates = 29,
 
         /// <summary>
-        /// The selector used (CSS/XPath) was invalid.
+        /// Argument was an invalid selector.
         /// </summary>
         InvalidSelector = 32,
 
         /// <summary>
-        /// A session was not created by the driver
+        /// A new <see href="https://www.w3.org/TR/webdriver2/#dfn-sessions">session</see> could not be created.
         /// </summary>
         SessionNotCreated = 33,
 
         /// <summary>
-        /// The requested move was outside the active view port
+        /// The target for mouse interaction is not in the browser's viewport and cannot be brought into that viewport.
         /// </summary>
         MoveTargetOutOfBounds = 34,
 
@@ -195,32 +203,32 @@ public enum WebDriverResult
         InvalidXPathSelector = 51,
 
         /// <summary>
-        /// An insecure SSl certificate was specified.
+        /// Navigation caused the user agent to hit a certificate warning, which is usually the result of an expired or invalid TLS certificate.
         /// </summary>
         InsecureCertificate = 59,
 
         /// <summary>
-        /// The element was not interactable
+        /// A command could not be completed because the element is not <see href="https://www.w3.org/TR/webdriver2/#dfn-pointer-interactable">pointer</see>- or <see href="https://www.w3.org/TR/webdriver2/#dfn-keyboard-interactable">keyboard</see> interactable.
         /// </summary>
         ElementNotInteractable = 60,
 
         /// <summary>
-        /// An invalid argument was passed to the command.
+        /// The arguments passed to a command are either invalid or malformed.
         /// </summary>
         InvalidArgument = 61,
 
         /// <summary>
-        /// No cookie was found matching the name requested.
+        /// No cookie matching the given path name was found amongst the <see href="https://www.w3.org/TR/webdriver2/#dfn-associated-cookies">associated cookies</see> of session's current browsing context's active document.
         /// </summary>
         NoSuchCookie = 62,
 
         /// <summary>
-        /// The driver was unable to capture the screen.
+        /// A screen capture was made impossible.
         /// </summary>
         UnableToCaptureScreen = 63,
 
         /// <summary>
-        /// The click on the element was intercepted by a different element.
+        /// The <see href="https://www.w3.org/TR/webdriver2/#dfn-element-click">Element Click</see> command could not be completed because the element receiving the events is <see href="https://www.w3.org/TR/webdriver2/#dfn-obscuring">obscuring</see> the element that was requested clicked.
         /// </summary>
         ElementClickIntercepted = 64,
 
@@ -234,9 +242,14 @@ public enum WebDriverResult
         /// </summary>
         DetachedShadowRoot = 66,
 
+        /// <summary>
+        /// The requested command matched a known URL but did not match any method for that URL.
+        /// </summary>
+        UnknownMethod = 67,
+
         /// <summary>
         /// Indicates that a command that should have executed properly cannot be supported for some reason.
         /// </summary>
-        UnsupportedOperation = 67,
+        UnsupportedOperation = 68,
     }
 }