Configuration¶

In this section, you will learn how to configure the Web Automation framework.

Supported Browsers¶

This framework leverages the WebDriver API in order to communicate with browsers for Automation.

In doing so, it requires that the WebDriver for the chosen browser to be installed and available preferably in your PATH. If you can't add the necessary WebDriver to your PATH you will be able to inform the driver path via code in your bot.

Here is a list of supported browsers along with links for you to download the proper WebDriver:

Please follow the instructions on the WebDriver website for installation and setup.

Once the desired WebDriver for the Web Browser to be used is installed we can proceed to the next steps.

Customizing the Browser¶

To provide flexibility we have properties to allow you to configure which browser to use, the WebDriver location as well as the options used when launching the browser.

The following sections will cover the possible customizations in detail.

Selecting the Browser¶

BotCity's project template by default comes configured to run with Google Chrome. You can select any other available browser by setting the browser property to one of the Browser enum available values.

Here is an example on how to change the default browser to be used:

# Import the Browser enum
from botcity.web import WebBot, Browser

def main():
    # Instantiate the WebBot.
    bot = WebBot()

    # Configure whether or not to run on headless mode.
    bot.headless = False

    # Changes the Browser to Firefox.
    bot.browser = Browser.FIREFOX

    # For Chrome.
    # bot.browser = Browser.CHROME

    ...

import dev.botcity.framework.bot.WebBot;
// Import the Browser enum
import dev.botcity.framework.web.browsers.Browser;

...

public void action(BotExecution botExecution) {
    try {
        // Configure whether or not to run on headless mode
        setHeadless(false);

        //Changes the Browser to Firefox
        setBrowser(Browser.FIREFOX);

        // For Chrome
        // setBrowser(Browser.CHROME);

        ...

From the snippet above the key takeaway is the browser piece in which we set it to one of the values from the Browser enum as mentioned before.

Defining the WebDriver Path¶

If your WebDriver for the selected browser is not available on the system PATH you can inform the location via the driver path property.

Here is how that can be done:

# Import the Browser enum
from botcity.web import WebBot, Browser

def main():
    # Instantiate the WebBot.
    bot = WebBot()

    # Configure whether or not to run on headless mode.
    bot.headless = False

    # Inform the WebDriver path for Google Chrome's chromedriver.
    bot.driver_path = "/home/username/drivers/chromedriver"

    ...

import dev.botcity.framework.bot.WebBot;
import dev.botcity.framework.web.browsers.Browser;

...

public void action(BotExecution botExecution) {
    try {
        // Configure whether or not to run on headless mode
        setHeadless(false);

        // Inform the WebDriver path for Google Chrome's chromedriver
        setDriverPath("/home/username/drivers/chromedriver");

        ...

Customizing Browser Options¶

By default the browsers are launched with a set of curated options which we picked as essential.

Before getting into how to customize those details let's walk through some of the assumptions and details which are covered by the default options.

• Headless Execution: Depending on the headless property set on your Bot class we pick the proper configuration to launch the browser in the desired mode.

• Downloads Folder Path: By default we save all downloaded files on the Desktop folder.

• User Profile: By default we generate a temporary directory (which is later erased) to be used as the profile directory. This procedure ensure that every execution starts with a clean browser session and things such as cookies and stored passwords or certificates from one execution won't interfere with the others.

• Page Load Strategy: By default we use the NORMAL strategy which waits for the page to load completely.

A handful of other options are also set and they can be inspected on the source code for each browser on the proper framework module.

If you really need to customize the options you can do so via the options property. You can fetch the default options curated by BotCity and make your changes or start your options from scratch.

In the following snippet we will cover how to build on top of the existing options.

from botcity.web import WebBot, Browser, PageLoadStrategy

# For Chrome
from botcity.web.browsers.chrome import default_options
# For Firefox
#from botcity.web.browsers.firefox import default_options

def main():
    # Instantiate the WebBot.
    bot = WebBot()

    # Configure whether or not to run on headless mode.
    bot.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=bot.headless,
        download_folder_path=bot.download_folder_path,
        user_data_dir=None,  # Informing None here will generate a temporary directory
        page_load_strategy=PageLoadStrategy.NORMAL
    )

    # Add your customized argument
    def_options.add_argument("<My Special Argument>")

    # Update the options to use the customized Options.
    bot.options = def_options

    ...

import dev.botcity.framework.bot.WebBot;
import dev.botcity.framework.web.browsers.Browser;
import dev.botcity.framework.web.browsers.PageLoadStrategy;

// For Chrome
import dev.botcity.framework.web.browsers.ChromeConfig;
// For Firefox
// import dev.botcity.framework.web.browsers.FirefoxConfig;

...

public void action(BotExecution botExecution) {
    try {
        // Configure whether or not to run on headless mode
        setHeadless(false);

        // Fetch the default options for my preferred browser
        ChromeConfig chromeConfig = new ChromeConfig();
        ChromeOptions defOptions = (ChromeOptions) chromeConfig.defaultOptions(
                isHeadless(), // Setting headless mode (using default)
                getDownloadPath(), // Setting the download folder path (using default)
                null, // Informing null here will generate a temporary directory
                PageLoadStrategy.NORMAL // Setting the page load strategy
        );

        // Add your customized argument
        defOptions.addArguments("<My Special Argument>");

        // Update the options to use the customized Options.
        setOptions(defOptions);

        ...

Every supported browser will have an exclusive module with curated default options accessible via the module's default options function.

This function takes in arguments to define the mode of execution (headless or not), default download folder path, user data/profile directory and page load strategy as described above.

Using other browsers¶

You can use other browsers based on Firefox or Chromium or even fixed versions of Chrome, Firefox, or Edge.

Chromium-based browsers:

• Vivaldi
• Opera
• Brave

Firefox-based browsers:

• Tor
• LibreWolf

It's straightforward to use these browsers in your code; the only dependency is the path to the browser binary/executable. With that in hand, you can use it as follows.

from botcity.web import WebBot, Browser

def main():
    # Instantiate the WebBot.
    bot = WebBot()

    # Configure whether or not to run on headless mode.
    bot.headless = False

    # Inform the WebDriver path for chromedriver
    bot.driver_path = "/home/username/drivers/chromedriver"

    # Inform the Browser path for Brave.
    bot.binary_path = "/usr/bin/brave-browser"