ENH: Expose capabilities and define default capabilities for all browsers supported.

DOC: Add documentation for all browser modules.

Author: hhslepicka

botcity/web/bot.py

@@ -54,6 +54,7 @@ def __init__(self, headless=False):
 
         self._browser = Browser.CHROME
         self._options = None
+        self._capabilities = None
         self._driver_path = None
 
         self._driver = None
@@ -141,6 +142,26 @@ def options(self, options):
         """
         self._options = options
 
+    @property
+    def capabilities(self):
+        """
+        The capabilities to be passed down to the WebDriver when starting the browser.
+
+        Returns:
+            capabilities (Dict): The browser specific capabilities to be used.
+        """
+        return self._capabilities
+
+    @capabilities.setter
+    def capabilities(self, capabilities):
+        """
+        The capabilities to be passed down to the WebDriver when starting the browser.
+
+        Args:
+            capabilities (Dict): The browser specific capabilities to be used.
+        """
+        self._capabilities = capabilities
+
     @property
     def download_folder_path(self):
         return self._download_folder_path
@@ -196,13 +217,17 @@ def check_driver():
         driver_class = BROWSER_CONFIGS.get(self.browser).get("class")
         # Specific default options method for a given browser
         func_def_options = BROWSER_CONFIGS.get(self.browser).get("options")
+        # Specific capabilities method for a given browser
+        func_def_capabilities = BROWSER_CONFIGS.get(self.browser).get("capabilities")
 
         opt = self.options or func_def_options(self.headless, self._download_folder_path, None)
+        cap = self.capabilities or func_def_capabilities()
         self.options = opt
+        self.capabilities = cap
         driver_path = self.driver_path or check_driver()
         self.driver_path = driver_path
 
-        self._driver = driver_class(options=opt, executable_path=driver_path)
+        self._driver = driver_class(options=opt, desired_capabilities=cap, executable_path=driver_path)
         self.set_screen_resolution()
 
     def stop_browser(self):

botcity/web/browsers/__init__.py

@@ -24,18 +24,21 @@ class Browser(str, enum.Enum):
         "driver": "chromedriver",
         "class": chrome.Chrome,
         "options": chrome.default_options,
+        "capabilities": chrome.default_capabilities,
         "wait_for_downloads": chrome.wait_for_downloads
     },
     Browser.FIREFOX: {
         "driver": "geckodriver",
         "class": firefox.Firefox,
         "options": firefox.default_options,
+        "capabilities": firefox.default_capabilities,
         "wait_for_downloads": firefox.wait_for_downloads
     },
     Browser.EDGE: {
         "driver": "msedgedriver",
         "class": edge.Edge,
         "options": edge.default_options,
+        "capabilities": edge.default_capabilities,
         "wait_for_downloads": edge.wait_for_downloads
     },
 }

botcity/web/browsers/chrome.py

@@ -1,15 +1,29 @@
-import json
 import atexit
+import json
 import os
 import tempfile
+from typing import Dict
 
 from selenium.webdriver import Chrome  # noqa: F401, F403
 from selenium.webdriver.chrome.options import Options as ChromeOptions
+from selenium.webdriver.common.desired_capabilities import DesiredCapabilities
 
 from ..util import cleanup_temp_dir
 
 
-def default_options(headless=False, download_folder_path=None, user_data_dir=None):
+def default_options(headless=False, download_folder_path=None, user_data_dir=None) -> ChromeOptions:
+    """Retrieve the default options for this browser curated by BotCity.
+
+    Args:
+        headless (bool, optional): Whether or not to use the headless mode. Defaults to False.
+        download_folder_path (str, optional): The default path in which to save files.
+            If None, the current directory is used. Defaults to None.
+        user_data_dir ([type], optional): The directory to use as user profile.
+            If None, a new temporary directory is used. Defaults to None.
+
+    Returns:
+        ChromeOptions: The Chrome options.
+    """
     chrome_options = ChromeOptions()
     chrome_options.add_argument("--remote-debugging-port=0")
     chrome_options.add_argument("--no-first-run")
@@ -83,7 +97,19 @@ def default_options(headless=False, download_folder_path=None, user_data_dir=Non
     return chrome_options
 
 
+def default_capabilities() -> Dict:
+    """Fetch the default capabilities for this browser.
+
+    Returns:
+        Dict: Dictionary with the default capabilities defined.
+    """
+    return DesiredCapabilities.CHROME.copy()
+
+
 def wait_for_downloads(driver):
+    """Wait for all downloads to finish.
+    *Important*: This method overwrites the current page with the downloads page.
+    """
     if not driver.current_url.startswith("chrome://downloads"):
         driver.get("chrome://downloads/")
     return driver.execute_script("""

botcity/web/browsers/edge.py

@@ -2,13 +2,27 @@
 import json
 import os
 import tempfile
+from typing import Dict
 
 from msedge.selenium_tools import Edge, EdgeOptions  # noqa: F401, F403
+from selenium.webdriver.common.desired_capabilities import DesiredCapabilities
 
 from ..util import cleanup_temp_dir
 
 
-def default_options(headless=False, download_folder_path=None, user_data_dir=None):
+def default_options(headless=False, download_folder_path=None, user_data_dir=None) -> EdgeOptions:
+    """Retrieve the default options for this browser curated by BotCity.
+
+    Args:
+        headless (bool, optional): Whether or not to use the headless mode. Defaults to False.
+        download_folder_path (str, optional): The default path in which to save files.
+            If None, the current directory is used. Defaults to None.
+        user_data_dir ([type], optional): The directory to use as user profile.
+            If None, a new temporary directory is used. Defaults to None.
+
+    Returns:
+        EdgeOptions: The Edge options.
+    """
     edge_options = EdgeOptions()
     edge_options.use_chromium = True
     edge_options.add_argument("--remote-debugging-port=0")
@@ -87,7 +101,19 @@ def default_options(headless=False, download_folder_path=None, user_data_dir=Non
     return edge_options
 
 
+def default_capabilities() -> Dict:
+    """Fetch the default capabilities for this browser.
+
+    Returns:
+        Dict: Dictionary with the default capabilities defined.
+    """
+    return DesiredCapabilities.EDGE.copy()
+
+
 def wait_for_downloads(driver):
+    """Wait for all downloads to finish.
+    *Important*: This method overwrites the current page with the downloads page.
+    """
     if not driver.current_url.startswith("chrome://downloads"):
         driver.get("chrome://downloads/")
     return driver.execute_script("""

botcity/web/browsers/firefox.py

@@ -1,9 +1,11 @@
 import atexit
 import os
 import tempfile
+from typing import Dict
 
 from selenium import webdriver
 from selenium.webdriver import Firefox  # noqa: F401, F403
+from selenium.webdriver.common.desired_capabilities import DesiredCapabilities
 from selenium.webdriver.firefox.options import Options as FirefoxOptions
 
 from ..util import cleanup_temp_dir
@@ -334,7 +336,19 @@
                                  'application/vnd.zzazz.deck+xml']
 
 
-def default_options(headless=False, download_folder_path=None, user_data_dir=None):
+def default_options(headless=False, download_folder_path=None, user_data_dir=None) -> FirefoxOptions:
+    """Retrieve the default options for this browser curated by BotCity.
+
+    Args:
+        headless (bool, optional): Whether or not to use the headless mode. Defaults to False.
+        download_folder_path (str, optional): The default path in which to save files.
+            If None, the current directory is used. Defaults to None.
+        user_data_dir ([type], optional): The directory to use as user profile.
+            If None, a new temporary directory is used. Defaults to None.
+
+    Returns:
+        FirefoxOptions: The Firefox options.
+    """
     firefox_options = FirefoxOptions()
     firefox_options.headless = headless
     if not user_data_dir:
@@ -361,7 +375,19 @@ def default_options(headless=False, download_folder_path=None, user_data_dir=Non
     return firefox_options
 
 
+def default_capabilities() -> Dict:
+    """Fetch the default capabilities for this browser.
+
+    Returns:
+        Dict: Dictionary with the default capabilities defined.
+    """
+    return DesiredCapabilities.FIREFOX.copy()
+
+
 def wait_for_downloads(driver):
+    """Wait for all downloads to finish.
+    *Important*: This method overwrites the current page with the downloads page.
+    """
     if not driver.current_url.startswith("about:downloads"):
         driver.get("about:downloads")
 

docs/browsers.md

@@ -0,0 +1,79 @@
+# Browsers
+
+Every supported browser has a default set of options and capabilities curated for you that are used by default.
+
+In case you need to customize the options or capabilities you can do so via the `default_options` and `default_capabilities` methods available within each browser module.
+
+Here is an example on how to do that:
+
+```python
+from botcity.web import WebBot, Browser
+
+# For Chrome
+from botcity.web.browsers.chrome import default_options, default_capabilities
+# For Firefox
+#from botcity.web.browsers.firefox import default_options, default_capabilities
+# For Edge
+#from botcity.web.browsers.edge import default_options, default_capabilities
+
+
+class Bot(WebBot):
+    def action(self, execution=None):
+        # Configure whether or not to run on headless mode
+        self.headless = False
+
+        # Fetch the default options for my preferred browser
+        # Pass in the headless, download_folder_path and user_data_dir
+        # to be used when building the default_options
+        def_options = default_options(
+            headless=self.headless,
+            download_folder_path=self.download_folder_path,
+            user_data_dir=None  # Informing None here will generate a temporary directory
+        )
+
+        # Add your customized argument
+        def_options.add_argument("<My Special Argument>")
+
+        # Update the options to use the customized Options.
+        self.options = def_options
+
+        # Fetch the default options for my preferred browser
+        def_capabilities = default_capabilities()
+
+        # Set of modify the key and value for my desired capability
+        def_capabilities["<My Special Parameter>"] = "special value"
+
+        # Update the capabilities to use the customized configurations.
+        self.capabilities = def_capabilities
+
+        ...
+```
+
+## Specific Browser Modules
+
+Here are the documentation for the methods mentioned above for each of the supported browsers.
+
+### Chrome
+::: botcity.web.browsers.chrome.default_options
+    rendering:
+      heading_level: 4
+
+::: botcity.web.browsers.chrome.default_capabilities
+    rendering:
+      heading_level: 4
+
+### Firefox
+::: botcity.web.browsers.firefox.default_options
+    rendering:
+      heading_level: 4
+::: botcity.web.browsers.firefox.default_capabilities
+    rendering:
+      heading_level: 4
+
+### Edge
+::: botcity.web.browsers.edge.default_options
+    rendering:
+      heading_level: 4
+::: botcity.web.browsers.edge.default_capabilities
+    rendering:
+      heading_level: 4

mkdocs.yml

@@ -7,6 +7,7 @@ nav:
     - Home: index.md
     - Getting Started: intro.md
     - Framework: bot.md
+    - Browsers: browsers.md
 
 theme:
   icon: