[py] add links to documentation for errors (#12156)

titusfortner · web-flow · commit 722376a9734d · 2023-06-06T06:41:54.000+02:00
* [py] include links to documentation for error messages

* [py] make custom exception for driver location
diff --git a/py/selenium/common/__init__.py b/py/selenium/common/__init__.py
@@ -34,12 +34,12 @@
 from .exceptions import NoAlertPresentException
 from .exceptions import NoSuchAttributeException
 from .exceptions import NoSuchCookieException
+from .exceptions import NoSuchDriverException
 from .exceptions import NoSuchElementException
 from .exceptions import NoSuchFrameException
 from .exceptions import NoSuchShadowRootException
 from .exceptions import NoSuchWindowException
 from .exceptions import ScreenshotException
-from .exceptions import SeleniumManagerException
 from .exceptions import SessionNotCreatedException
 from .exceptions import StaleElementReferenceException
 from .exceptions import TimeoutException
@@ -56,6 +56,7 @@
     "NoSuchWindowException",
     "NoSuchElementException",
     "NoSuchAttributeException",
+    "NoSuchDriverException",
     "NoSuchShadowRootException",
     "StaleElementReferenceException",
     "InvalidElementStateException",
@@ -82,5 +83,4 @@
     "InvalidSessionIdException",
     "SessionNotCreatedException",
     "UnknownMethodException",
-    "SeleniumManagerException",
 ]
diff --git a/py/selenium/common/exceptions.py b/py/selenium/common/exceptions.py
@@ -20,6 +20,9 @@
 from typing import Optional
 from typing import Sequence
 
+SUPPORT_MSG = "For documentation on this error, please visit:"
+ERROR_URL = "https://www.selenium.dev/documentation/webdriver/troubleshooting/errors"
+
 
 class WebDriverException(Exception):
     """Base webdriver exception."""
@@ -70,6 +73,13 @@ class NoSuchElementException(WebDriverException):
           for how to write a wait wrapper to wait for an element to appear.
     """
 
+    def __init__(
+        self, msg: Optional[str] = None, screen: Optional[str] = None, stacktrace: Optional[Sequence[str]] = None
+    ) -> None:
+        with_support = f"{msg}; {SUPPORT_MSG} {ERROR_URL}#no-such-element-exception"
+
+        super().__init__(with_support, screen, stacktrace)
+
 
 class NoSuchAttributeException(WebDriverException):
     """Thrown when the attribute of element could not be found.
@@ -102,6 +112,13 @@ class StaleElementReferenceException(WebDriverException):
         * Element may have been inside an iframe or another context which was refreshed.
     """
 
+    def __init__(
+        self, msg: Optional[str] = None, screen: Optional[str] = None, stacktrace: Optional[Sequence[str]] = None
+    ) -> None:
+        with_support = f"{msg}; {SUPPORT_MSG} {ERROR_URL}#stale-element-reference-exception"
+
+        super().__init__(with_support, screen, stacktrace)
+
 
 class InvalidElementStateException(WebDriverException):
     """Thrown when a command could not be completed because the element is in
@@ -194,6 +211,13 @@ class InvalidSelectorException(WebDriverException):
     "count(//input)").
     """
 
+    def __init__(
+        self, msg: Optional[str] = None, screen: Optional[str] = None, stacktrace: Optional[Sequence[str]] = None
+    ) -> None:
+        with_support = f"{msg}; {SUPPORT_MSG} {ERROR_URL}#invalid-selector-exception"
+
+        super().__init__(with_support, screen, stacktrace)
+
 
 class ImeNotAvailableException(WebDriverException):
     """Thrown when IME support is not available.
@@ -253,5 +277,12 @@ class UnknownMethodException(WebDriverException):
     for that URL."""
 
 
-class SeleniumManagerException(WebDriverException):
-    """Raised when an issue interacting with selenium manager occurs."""
+class NoSuchDriverException(WebDriverException):
+    """Raised when driver is not specified and cannot be located."""
+
+    def __init__(
+        self, msg: Optional[str] = None, screen: Optional[str] = None, stacktrace: Optional[Sequence[str]] = None
+    ) -> None:
+        with_support = f"{msg}; {SUPPORT_MSG} {ERROR_URL}/driver_location"
+
+        super().__init__(with_support, screen, stacktrace)
diff --git a/py/selenium/webdriver/common/driver_finder.py b/py/selenium/webdriver/common/driver_finder.py
@@ -16,8 +16,9 @@
 # under the License.
 import logging
 import shutil
+from pathlib import Path
 
-from selenium.common.exceptions import WebDriverException
+from selenium.common.exceptions import NoSuchDriverException
 from selenium.webdriver.common.options import BaseOptions
 from selenium.webdriver.common.selenium_manager import SeleniumManager
 from selenium.webdriver.common.service import Service
@@ -36,10 +37,13 @@ def __init__(self) -> None:
 
     @staticmethod
     def get_path(service: Service, options: BaseOptions) -> str:
+        path = shutil.which(service.path)
         try:
-            path = shutil.which(service.path) or SeleniumManager().driver_location(options)
-        except WebDriverException as err:
-            logger.warning("Unable to obtain driver using Selenium Manager: " + err.msg)
-            raise err
+            path = SeleniumManager().driver_location(options) if path is None else path
+        except Exception as err:
+            raise NoSuchDriverException(f"Unable to obtain {service.path} using Selenium Manager; {err}")
+
+        if path is None or not Path(path).is_file():
+            raise NoSuchDriverException(f"Unable to locate or obtain {service.path}")
 
         return path
diff --git a/py/selenium/webdriver/common/selenium_manager.py b/py/selenium/webdriver/common/selenium_manager.py
@@ -21,7 +21,7 @@
 from pathlib import Path
 from typing import List
 
-from selenium.common.exceptions import SeleniumManagerException
+from selenium.common import WebDriverException
 from selenium.webdriver.common.options import BaseOptions
 
 logger = logging.getLogger(__name__)
@@ -57,8 +57,7 @@ def get_binary() -> Path:
         path = Path(__file__).parent.joinpath(directory, file)
 
         if not path.is_file():
-            tracker = "https://github.com/SeleniumHQ/selenium/issues"
-            raise SeleniumManagerException(f"{path} is missing.  Please open an issue on {tracker}")
+            raise WebDriverException(f"Unable to obtain working Selenium Manager binary; {path}")
 
         return path
 
@@ -109,15 +108,18 @@ def run(args: List[str]) -> str:
         """
         command = " ".join(args)
         logger.debug(f"Executing process: {command}")
-        completed_proc = subprocess.run(args, stdout=subprocess.PIPE, stderr=subprocess.PIPE)
-        stdout = completed_proc.stdout.decode("utf-8").rstrip("\n")
-        stderr = completed_proc.stderr.decode("utf-8").rstrip("\n")
-        output = json.loads(stdout)
-        result = output["result"]["message"]
+        try:
+            completed_proc = subprocess.run(args, stdout=subprocess.PIPE, stderr=subprocess.PIPE)
+            stdout = completed_proc.stdout.decode("utf-8").rstrip("\n")
+            stderr = completed_proc.stderr.decode("utf-8").rstrip("\n")
+            output = json.loads(stdout)
+            result = output["result"]["message"]
+        except Exception as err:
+            raise WebDriverException(f"Unsuccessful command executed: {command}; {err}")
+
         if completed_proc.returncode:
-            raise SeleniumManagerException(f"Selenium Manager failed for: {command}.\n{result}{stderr}")
+            raise WebDriverException(f"Unsuccessful command executed: {command}.\n{result}{stderr}")
         else:
-            # Selenium Manager exited successfully, return executable path and print warnings
             for item in output["logs"]:
                 if item["level"] == "WARN":
                     logger.warning(item["message"])
diff --git a/py/test/selenium/webdriver/common/driver_element_finding_tests.py b/py/test/selenium/webdriver/common/driver_element_finding_tests.py
@@ -93,6 +93,13 @@ def test_finding_multiple_elements_by_id_with_space_should_return_empty_list(dri
     assert len(elements) == 0
 
 
+def test_no_such_element_error(driver, pages):
+    pages.load("formPage.html")
+    msg = r"\/errors#no-such-element-exception"
+    with pytest.raises(NoSuchElementException, match=msg):
+        driver.find_element(By.ID, "non_Existent_Button")
+
+
 # By.name positive
 
 
@@ -268,7 +275,8 @@ def test_should_not_find_element_by_class_when_the_name_queried_is_shorter_than_
 
 def test_finding_asingle_element_by_empty_class_name_should_throw(driver, pages):
     pages.load("xhtmlTest.html")
-    with pytest.raises(InvalidSelectorException):
+    msg = r"\/errors#invalid-selector-exception"
+    with pytest.raises(InvalidSelectorException, match=msg):
         driver.find_element(By.CLASS_NAME, "")
 
 
diff --git a/py/test/selenium/webdriver/common/selenium_manager_tests.py b/py/test/selenium/webdriver/common/selenium_manager_tests.py
@@ -19,8 +19,10 @@
 
 import pytest
 
-from selenium.common.exceptions import SeleniumManagerException
+from selenium.common.exceptions import WebDriverException
 from selenium.webdriver.chrome.options import Options
+from selenium.webdriver.chrome.service import Service
+from selenium.webdriver.common.driver_finder import DriverFinder
 from selenium.webdriver.common.proxy import Proxy
 from selenium.webdriver.common.selenium_manager import SeleniumManager
 
@@ -85,8 +87,18 @@ def test_proxy_is_used_for_sm(mocker):
 
 
 def test_stderr_is_propagated_to_exception_messages():
-    msg = r"Selenium Manager failed for:.* --browser foo --output json\.\nInvalid browser name: foo\n"
-    with pytest.raises(SeleniumManagerException, match=msg):
+    msg = r"Unsuccessful command executed:.* --browser foo --output json\.\nInvalid browser name: foo\n"
+    with pytest.raises(WebDriverException, match=msg):
         manager = SeleniumManager()
         binary = manager.get_binary()
         _ = manager.run([str(binary), "--browser", "foo", "--output", "json"])
+
+
+def test_driver_finder_error(mocker):
+    mocker.patch("selenium.webdriver.common.selenium_manager.SeleniumManager.driver_location", return_value=None)
+
+    service = Service()
+    options = Options()
+    msg = r"Unable to locate or obtain chromedriver.*errors\/driver_location"
+    with pytest.raises(WebDriverException, match=msg):
+        DriverFinder.get_path(service, options)
diff --git a/py/test/selenium/webdriver/common/stale_reference_tests.py b/py/test/selenium/webdriver/common/stale_reference_tests.py
@@ -25,7 +25,8 @@ def test_old_page(driver, pages):
     pages.load("simpleTest.html")
     elem = driver.find_element(by=By.ID, value="links")
     pages.load("xhtmlTest.html")
-    with pytest.raises(StaleElementReferenceException):
+    msg = r"\/errors#stale-element-reference-exception"
+    with pytest.raises(StaleElementReferenceException, match=msg):
         elem.click()
 
 
diff --git a/py/test/selenium/webdriver/support/relative_by_tests.py b/py/test/selenium/webdriver/support/relative_by_tests.py
@@ -86,7 +86,7 @@ def test_no_such_element_is_raised_rather_than_index_error(driver, pages):
     with pytest.raises(NoSuchElementException) as exc:
         anchor = driver.find_element(By.ID, "second")
         driver.find_element(locate_with(By.ID, "nonexistentid").above(anchor))
-    assert exc.value.msg == "Cannot locate relative element with: {'id': 'nonexistentid'}"
+    assert "Cannot locate relative element with: {'id': 'nonexistentid'}" in exc.value.msg
 
 
 def test_near_locator_should_find_near_elements(driver, pages):
@@ -105,4 +105,4 @@ def test_near_locator_should_not_find_far_elements(driver, pages):
     with pytest.raises(NoSuchElementException) as exc:
         driver.find_element(locate_with(By.ID, "rect4").near(rect3))
 
-    assert exc.value.msg == "Cannot locate relative element with: {'id': 'rect4'}"
+    assert "Cannot locate relative element with: {'id': 'rect4'}" in exc.value.msg
