Skip to content

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:

from botcity.web import WebBot, Browser

# Page Load Strategy
from botcity.web import PageLoadStrategy

# 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
# For IE
#from botcity.web.browsers.ie 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

        self.page_load_strategy = PageLoadStrategy.NORMAL

        # 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
            page_load_strategy=self.page_load_strategy
        )

        # 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

        ...

Page Load Strategy

Page Load Strategy is a browser option that determines how the browser will load the page.

botcity.web.browsers.PageLoadStrategy (str, Enum)

Page Load Strategy.

Attributes:

Name Type Description
NORMAL str

Wait for the entire page is loaded. When set to normal, waits until the load event fire is returned.

EAGER str

Wait until the initial HTML document has been completely loaded and parsed, and discards loading of stylesheets, images and subframes.

NONE str

Only waits until the initial page is downloaded

Source code in web/browsers/__init__.py
class PageLoadStrategy(str, enum.Enum):
    """
    Page Load Strategy.

    Attributes:
        NORMAL (str): Wait for the entire page is loaded. When set to normal,
            waits until the load event fire is returned.
        EAGER (str): Wait until the initial HTML document has been completely
            loaded and parsed, and discards loading of stylesheets, images and subframes.
        NONE (str): Only waits until the initial page is downloaded
    """
    NORMAL = "normal"
    EAGER = "eager"
    NONE = "none"

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(headless=False, download_folder_path=None, user_data_dir=None, page_load_strategy='normal')

Retrieve the default options for this browser curated by BotCity.

Parameters:

Name Type Description Default
headless bool

Whether or not to use the headless mode. Defaults to False.

False
download_folder_path str

The default path in which to save files. If None, the current directory is used. Defaults to None.

None
user_data_dir [type]

The directory to use as user profile. If None, a new temporary directory is used. Defaults to None.

None
page_load_strategy str

The page load strategy. Defaults to "normal".

'normal'

Returns:

Type Description
ChromeOptions

The Chrome options.

Source code in web/browsers/chrome.py
def default_options(headless=False, download_folder_path=None, user_data_dir=None,
                    page_load_strategy="normal") -> 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.
        page_load_strategy (str, optional): The page load strategy. Defaults to "normal".

    Returns:
        ChromeOptions: The Chrome options.
    """
    chrome_options = ChromeOptions()
    try:
        page_load_strategy = page_load_strategy.value
    except AttributeError:
        page_load_strategy = page_load_strategy
    chrome_options.page_load_strategy = page_load_strategy
    chrome_options.add_argument("--remote-debugging-port=0")
    chrome_options.add_argument("--no-first-run")
    chrome_options.add_argument("--no-default-browser-check")
    chrome_options.add_argument("--disable-background-networking")
    chrome_options.add_argument("--disable-background-timer-throttling")
    chrome_options.add_argument("--disable-client-side-phishing-detection")
    chrome_options.add_argument("--disable-default-apps")
    chrome_options.add_argument("--disable-hang-monitor")
    chrome_options.add_argument("--disable-popup-blocking")
    chrome_options.add_argument("--disable-prompt-on-repost")
    chrome_options.add_argument("--disable-syncdisable-translate")
    chrome_options.add_argument("--metrics-recording-only")
    chrome_options.add_argument("--safebrowsing-disable-auto-update")

    # Disable What's New banner for new chrome installs
    chrome_options.add_argument("--disable-features=ChromeWhatsNewUI")

    chrome_options.add_argument("--disable-blink-features=AutomationControlled")

    # Disable banner for Browser being remote-controlled
    chrome_options.add_experimental_option("excludeSwitches", ["enable-automation"])
    chrome_options.add_experimental_option('useAutomationExtension', False)

    if headless:
        chrome_options.add_argument("--headless")
        chrome_options.add_argument("--disable-gpu")
        chrome_options.add_argument("--hide-scrollbars")
        chrome_options.add_argument("--mute-audio")

    # Check if user is root
    try:
        # This is only valid with Unix
        if os.geteuid() == 0:
            chrome_options.add_argument("--no-sandbox")
    except AttributeError:
        pass

    if not user_data_dir:
        temp_dir = tempfile.TemporaryDirectory(prefix="botcity_")
        user_data_dir = temp_dir.name
        atexit.register(cleanup_temp_dir, temp_dir)

    chrome_options.add_argument(f"--user-data-dir={user_data_dir}")

    if not download_folder_path:
        download_folder_path = os.getcwd()

    app_state = {
        'recentDestinations': [{
            'id': 'Save as PDF',
            'origin': 'local',
            'account': ''
        }],
        'selectedDestinationId': 'Save as PDF',
        'version': 2
    }

    # Set the Downloads default folder
    prefs = {
        "printing.print_preview_sticky_settings.appState": json.dumps(app_state),
        "download.default_directory": download_folder_path,
        "savefile.default_directory": download_folder_path,
        "printing.default_destination_selection_rules": {
            "kind": "local",
            "namePattern": "Save as PDF",
        },
        "safebrowsing.enabled": True,
        "credentials_enable_service": False,
        "profile.password_manager_enabled": False,
        "plugins.always_open_pdf_externally": True
    }

    chrome_options.add_experimental_option("prefs", prefs)
    chrome_options.add_argument(
        "user-agent=Mozilla/5.0 (Windows NT 10.0; Win64; x64) "
        "AppleWebKit/537.36 (KHTML, like Gecko) Chrome/87.0.4280.88 Safari/537.36"
    )

    chrome_options.add_argument("--kiosk-printing")

    return chrome_options

botcity.web.browsers.chrome.default_capabilities()

Fetch the default capabilities for this browser.

Returns:

Type Description
Dict

Dictionary with the default capabilities defined.

Source code in web/browsers/chrome.py
def default_capabilities() -> Dict:
    """Fetch the default capabilities for this browser.

    Returns:
        Dict: Dictionary with the default capabilities defined.
    """
    return DesiredCapabilities.CHROME.copy()

Firefox

botcity.web.browsers.firefox.default_options(headless=False, download_folder_path=None, user_data_dir=None, page_load_strategy='normal')

Retrieve the default options for this browser curated by BotCity.

Parameters:

Name Type Description Default
headless bool

Whether or not to use the headless mode. Defaults to False.

False
download_folder_path str

The default path in which to save files. If None, the current directory is used. Defaults to None.

None
user_data_dir [type]

The directory to use as user profile. If None, a new temporary directory is used. Defaults to None.

None
page_load_strategy str

The page load strategy to use.

'normal'

Returns:

Type Description
FirefoxOptions

The Firefox options.

Source code in web/browsers/firefox.py
def default_options(headless=False, download_folder_path=None, user_data_dir=None,
                    page_load_strategy="normal") -> 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.
        page_load_strategy (str, optional): The page load strategy to use.

    Returns:
        FirefoxOptions: The Firefox options.
    """
    firefox_options = FirefoxOptions()
    try:
        page_load_strategy = page_load_strategy.value
    except AttributeError:
        page_load_strategy = page_load_strategy
    firefox_options.page_load_strategy = page_load_strategy
    firefox_options.headless = headless
    if not user_data_dir:
        temp_dir = tempfile.TemporaryDirectory(prefix="botcity_")
        user_data_dir = temp_dir.name
        atexit.register(cleanup_temp_dir, temp_dir)
    firefox_profile = webdriver.FirefoxProfile(user_data_dir)
    firefox_profile.set_preference("security.default_personal_cert", "Select Automatically")
    firefox_profile.set_preference('browser.download.folderList', 2)
    firefox_profile.set_preference('browser.download.manager.showWhenStarting', False)
    if not download_folder_path:
        download_folder_path = os.getcwd()
    firefox_profile.set_preference('browser.download.dir', download_folder_path)
    firefox_profile.set_preference('general.warnOnAboutConfig', False)

    mimetypes_to_download = ",".join(FIREFOX_MIMETYPES_TO_DOWNLOAD)
    firefox_profile.set_preference("pdfjs.disabled", True)
    firefox_profile.set_preference("plugin.disable_full_page_plugin_for_types", mimetypes_to_download)
    firefox_profile.set_preference('browser.helperApps.neverAsk.saveToDisk', mimetypes_to_download)

    firefox_profile.update_preferences()
    firefox_options.profile = firefox_profile

    return firefox_options

botcity.web.browsers.firefox.default_capabilities()

Fetch the default capabilities for this browser.

Returns:

Type Description
Dict

Dictionary with the default capabilities defined.

Source code in web/browsers/firefox.py
def default_capabilities() -> Dict:
    """Fetch the default capabilities for this browser.

    Returns:
        Dict: Dictionary with the default capabilities defined.
    """
    return DesiredCapabilities.FIREFOX.copy()

Edge

botcity.web.browsers.edge.default_options(headless=False, download_folder_path=None, user_data_dir=None, page_load_strategy='normal')

Retrieve the default options for this browser curated by BotCity.

Parameters:

Name Type Description Default
headless bool

Whether or not to use the headless mode. Defaults to False.

False
download_folder_path str

The default path in which to save files. If None, the current directory is used. Defaults to None.

None
user_data_dir [type]

The directory to use as user profile. If None, a new temporary directory is used. Defaults to None.

None
page_load_strategy str

The page load strategy. Defaults to "normal".

'normal'

Returns:

Type Description
EdgeOptions

The Edge options.

Source code in web/browsers/edge.py
def default_options(headless=False, download_folder_path=None, user_data_dir=None,
                    page_load_strategy="normal") -> 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.
        page_load_strategy (str, optional): The page load strategy. Defaults to "normal".

    Returns:
        EdgeOptions: The Edge options.
    """
    edge_options = EdgeOptions()
    try:
        page_load_strategy = page_load_strategy.value
    except AttributeError:
        page_load_strategy = page_load_strategy
    edge_options.page_load_strategy = page_load_strategy
    edge_options.use_chromium = True
    edge_options.add_argument("--remote-debugging-port=0")
    edge_options.add_argument("--no-first-run")
    edge_options.add_argument("--no-default-browser-check")
    edge_options.add_argument("--disable-background-networking")
    edge_options.add_argument("--disable-background-timer-throttling")
    edge_options.add_argument("--disable-client-side-phishing-detection")
    edge_options.add_argument("--disable-default-apps")
    edge_options.add_argument("--disable-hang-monitor")
    edge_options.add_argument("--disable-popup-blocking")
    edge_options.add_argument("--disable-prompt-on-repost")
    edge_options.add_argument("--disable-syncdisable-translate")
    edge_options.add_argument("--metrics-recording-only")
    edge_options.add_argument("--safebrowsing-disable-auto-update")

    edge_options.add_argument("--disable-blink-features=AutomationControlled")

    # Disable banner for Browser being remote-controlled
    edge_options.add_experimental_option("excludeSwitches", ["enable-automation"])
    edge_options.add_experimental_option('useAutomationExtension', False)

    if headless:
        edge_options.add_argument("--headless")
        edge_options.add_argument("--disable-gpu")
        edge_options.add_argument("--hide-scrollbars")
        edge_options.add_argument("--mute-audio")

    # Check if user is root
    try:
        # This is only valid with Unix
        if os.geteuid() == 0:
            edge_options.add_argument("--no-sandbox")
    except AttributeError:
        pass

    if not user_data_dir:
        temp_dir = tempfile.TemporaryDirectory(prefix="botcity_")
        user_data_dir = temp_dir.name
        atexit.register(cleanup_temp_dir, temp_dir)

    edge_options.add_argument(f"--user-data-dir={user_data_dir}")

    if not download_folder_path:
        download_folder_path = os.getcwd()

    app_state = {
        "recentDestinations": [{
            "id": "Save as PDF",
            "origin": "local",
            "account": ""
        }],
        "selectedDestinationId": "Save as PDF",
        "version": 2,
        "isHeaderFooterEnabled": False,
        "marginsType": 2,
        "isCssBackgroundEnabled": True
    }

    # Set the Downloads default folder
    prefs = {
        "printing.print_preview_sticky_settings.appState": json.dumps(app_state),
        "download.default_directory": download_folder_path,
        "savefile.default_directory": download_folder_path,
        "printing.default_destination_selection_rules": {
            "kind": "local",
            "namePattern": "Save as PDF",
        },
        "safebrowsing.enabled": True,
        "credentials_enable_service": False,
        "profile.password_manager_enabled": False,
        "plugins.always_open_pdf_externally": True
    }

    edge_options.add_experimental_option("prefs", prefs)

    edge_options.add_argument(
        "user-agent=Mozilla/5.0 (Windows NT 10.0; Win64; x64) "
        "AppleWebKit/537.36 (KHTML, like Gecko) Chrome/87.0.4280.88 Safari/537.36"
    )

    edge_options.add_argument("--kiosk-printing")

    return edge_options

botcity.web.browsers.edge.default_capabilities()

Fetch the default capabilities for this browser.

Returns:

Type Description
Dict

Dictionary with the default capabilities defined.

Source code in web/browsers/edge.py
def default_capabilities() -> Dict:
    """Fetch the default capabilities for this browser.

    Returns:
        Dict: Dictionary with the default capabilities defined.
    """
    return DesiredCapabilities.EDGE.copy()

IE

botcity.web.browsers.ie.default_options(headless=False, download_folder_path=None, user_data_dir=None, page_load_strategy='normal')

Retrieve the default options for this browser curated by BotCity.

Returns:

Type Description
Options

The Internet Explorer options.

Source code in web/browsers/ie.py
def default_options(headless=False, download_folder_path=None, user_data_dir=None,
                    page_load_strategy="normal") -> Options:
    """Retrieve the default options for this browser curated by BotCity.

    Returns:
        Options: The Internet Explorer options.
    """
    ie_options = Options()
    ie_options.add_argument("-embedding")
    ie_options.add_argument("-extoff")
    ie_options.add_argument("-k")
    return ie_options

botcity.web.browsers.ie.default_capabilities()

Fetch the default capabilities for this browser.

Returns:

Type Description
Dict

Dictionary with the default capabilities defined.

Source code in web/browsers/ie.py
def default_capabilities() -> Dict:
    """Fetch the default capabilities for this browser.

    Returns:
        Dict: Dictionary with the default capabilities defined.
    """
    return DesiredCapabilities.INTERNETEXPLORER.copy()

Important

If you have any questions about the driver see IE Driver Server Documentation.

See the list of supported arguments in IE.

During execution some errors may occur, see the list of common errors.