Python

The botcity.web module contains specialized implementations aimed at Web automation such as WebBot which is described below.

When instantiating a WebBot, you will have access to the methods responsible for automating applications and processes in the browser.

Here is a very brief example of a bot that opens the BotCity website using Google Chrome and the ChromeDriver WebDriver to remote control the browser.

from botcity.web import WebBot


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

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

    # Set the WebDriver path
    bot.driver_path = "<path to your WebDriver binary>"

    # Opens the BotCity website.
    bot.browse("https://www.botcity.dev")

    # Wait 3 seconds before closing
    bot.wait(3000)

    # Finish and clean up the Web Browser
    bot.stop_browser()


if __name__ == '__main__':
    main()

botcity.web.WebBot

Bases: BaseBot

binary_path property writable

The binary path to be used.

Returns:

Name	Type	Description
binary_path	Path	The binary path to be used.

browser property writable

The web browser to be used.

Returns:

Name	Type	Description
browser	Browser	The web browser to be used.

capabilities property writable

The capabilities to be passed down to the WebDriver when starting the browser.

Returns:

Name	Type	Description
capabilities	Dict	The browser specific capabilities to be used.

driver property

The WebDriver driver instance.

Returns:

Name	Type	Description
driver	WebDriver	The WebDriver driver instance.

headless property writable

Controls whether or not the bot will run headless.

Returns:

Name	Type	Description
headless	bool	Whether or not to run the browser on headless mode.

options property writable

The options to be passed down to the WebDriver when starting the browser.

Returns:

Name	Type	Description
options	Options	The browser specific options to be used.

page_load_strategy property writable

The page load strategy to be used.

Returns:

Name	Type	Description
page_load_strategy	PageLoadStrategy	The page load strategy to be used.

activate_tab(handle)

Activate a tab given by the handle.

Parameters:

Name	Type	Description	Default
handle	str	The tab or window handle.	required

add_image(label, path)

Add an image into the state image map.

Parameters:

Name	Type	Description	Default
label	str	The image identifier	required
path	str	The path for the image on disk	required

back()

Goes one step backward in the browser history.

backspace(wait=0)

Press Backspace key

Parameters:

Name	Type	Description	Default
wait	int	Wait interval (ms) after task	0

browse(url)

Opens the browser on the given URL.

Parameters:

Name	Type	Description	Default
url	str	The URL to be visited.	required

click(wait_after=config.DEFAULT_SLEEP_AFTER_ACTION, *, clicks=1, interval_between_clicks=0, button='left')

Click on the last found element.

Parameters:

Name	Type	Description	Default
wait_after	int	Interval to wait after clicking on the element.	DEFAULT_SLEEP_AFTER_ACTION
clicks	int	Number of times to click. Defaults to 1.	1
interval_between_clicks	int	The interval between clicks in ms. Defaults to 0.	0
button	str	One of 'left', 'right'. Defaults to 'left'	'left'

click_at(x, y, *, clicks=1, interval_between_clicks=0, button='left')

Click at the coordinate defined by x and y

Parameters:

Name	Type	Description	Default
x	int	The X coordinate	required
y	int	The Y coordinate	required
clicks	int	Number of times to click. Defaults to 1.	1
interval_between_clicks	int	The interval between clicks in ms. Defaults to 0.	0
button	str	One of 'left', 'right'. Defaults to 'left'	'left'

click_on(label)

Click on the element.

Parameters:

Name	Type	Description	Default
label	str	The image identifier	required

click_relative(x, y, wait_after=config.DEFAULT_SLEEP_AFTER_ACTION, *, clicks=1, interval_between_clicks=0, button='left')

Click Relative on the last found element.

Parameters:

Name	Type	Description	Default
x	int	Horizontal offset	required
y	int	Vertical offset	required
wait_after	int	Interval to wait after clicking on the element.	DEFAULT_SLEEP_AFTER_ACTION
clicks	int	Number of times to click. Defaults to 1.	1
interval_between_clicks	int	The interval between clicks in ms. Defaults to 0.	0
button	str	One of 'left', 'right'. Defaults to 'left'	'left'

close_page()

Close the current active page (tab or window).

control_a(wait=0)

Press keys CTRL+A

Parameters:

Name	Type	Description	Default
wait	int	Wait interval (ms) after task	0

control_c(wait=0)

Press keys CTRL+C

Parameters:

Name	Type	Description	Default
wait	int	Wait interval (ms) after task	0

control_v(wait=0)

Press keys CTRL+V

Parameters:

Name	Type	Description	Default
wait	int	Wait interval (ms) after task	0

copy_to_clipboard(text, wait=0)

Copy content to the clipboard.

Parameters:

Name	Type	Description	Default
text	str	The text to be copied.	required
wait	int	Wait interval (ms) after task	0

create_tab(url)

Create a new tab and navigate to the given URL.

Parameters:

Name	Type	Description	Default
url	str	The desired URL.	required

create_window(url)

Creates a new window with the given URL.

Parameters:

Name	Type	Description	Default
url	str	The desired URL.	required

delete(wait=0)

Press Delete key

Parameters:

Name	Type	Description	Default
wait	int	Wait interval (ms) after task	0

display_size()

Returns the display size in pixels.

Returns:

Name	Type	Description
size	Tuple	The screen dimension (width and height) in pixels.

double_click(wait_after=config.DEFAULT_SLEEP_AFTER_ACTION)

Double Click on the last found element.

Parameters:

Name	Type	Description	Default
wait_after	int	Interval to wait after clicking on the element.	DEFAULT_SLEEP_AFTER_ACTION

double_click_relative(x, y, interval_between_clicks=0, wait_after=config.DEFAULT_SLEEP_AFTER_ACTION)

Double Click Relative on the last found element.

Parameters:

Name	Type	Description	Default
x	int	Horizontal offset	required
y	int	Vertical offset	required
interval_between_clicks	int	The interval between clicks in ms. Defaults to 0.	0
wait_after	int	Interval to wait after clicking on the element.	DEFAULT_SLEEP_AFTER_ACTION

enter(wait=0)

Press key Enter

Parameters:

Name	Type	Description	Default
wait	int	Wait interval (ms) after task	0

enter_iframe(iframe)

Switch the WebBot driver to the specified iframe.

Parameters:

Name	Type	Description	Default
iframe	WebElement	The desired iFrame.	required

execute_javascript(code)

Execute the given javascript code.

Parameters:

Name	Type	Description	Default
code	str	The code to be executed.	required

Returns:

Name	Type	Description
value	object	Returns the code output or None if not available or if an error happens.

find(label, x=None, y=None, width=None, height=None, *, threshold=None, matching=0.9, waiting_time=10000, best=True, grayscale=False)

Find an element defined by label on screen until a timeout happens.

Parameters:

Name	Type	Description	Default
label	str	The image identifier	required
x	int	Search region start position x. Defaults to 0.	None
y	int	Search region start position y. Defaults to 0.	None
width	int	Search region width. Defaults to screen width.	None
height	int	Search region height. Defaults to screen height.	None
threshold	int	The threshold to be applied when doing grayscale search. Defaults to None.	None
matching	float	The matching index ranging from 0 to 1. Defaults to 0.9.	0.9
waiting_time	int	Maximum wait time (ms) to search for a hit. Defaults to 10000ms (10s).	10000
best	bool	Whether or not to keep looking until the best matching is found. Defaults to True.	True
grayscale	bool	Whether or not to convert to grayscale before searching. Defaults to False.	False

Returns:

Name	Type	Description
element	NamedTuple	The element coordinates. None if not found.

find_all(label, x=None, y=None, width=None, height=None, *, threshold=None, matching=0.9, waiting_time=10000, grayscale=False, as_list=False)

Find all elements defined by label on screen until a timeout happens.

Parameters:

Name	Type	Description	Default
label	str	The image identifier	required
x	int	Search region start position x. Defaults to 0.	None
y	int	Search region start position y. Defaults to 0.	None
width	int	Search region width. Defaults to screen width.	None
height	int	Search region height. Defaults to screen height.	None
threshold	int	The threshold to be applied when doing grayscale search. Defaults to None.	None
matching	float	The matching index ranging from 0 to 1. Defaults to 0.9.	0.9
waiting_time	int	Maximum wait time (ms) to search for a hit. Defaults to 10000ms (10s).	10000
grayscale	bool	Whether or not to convert to grayscale before searching. Defaults to False.	False
as_list	(bool, Optional)	If True, returns a list of element coordinates instead of a generator. Use set_active_element() to be able to interact with the found elements. This parameter must be True if you intend to run multiple find_all() concurrently. Defaults to False.	False

Returns:

Name	Type	Description
elements	Iterable[NamedTuple]	A generator with all element coordinates found. None if not found.

find_element(selector, by=By.CSS_SELECTOR, waiting_time=10000, ensure_visible=False, ensure_clickable=False)

Find an element using the specified selector with selector type specified by by. If more than one element is found, the first instance is returned.

Parameters:

Name	Type	Description	Default
selector	str	The selector string to be used.	required
by	str	Selector type. Defaults to By.CSS_SELECTOR. See more	CSS_SELECTOR
waiting_time	int	Maximum wait time (ms) to search for a hit. Defaults to 10000ms (10s).	10000
ensure_visible	bool	Whether to wait for the element to be visible. Defaults to False.	False
ensure_clickable	bool	Whether to wait for the element to be clickable. Defaults to False. If True, ensure_clickable takes precedence over ensure_visible.	False

Returns:

Name	Type	Description
WebElement	WebElement	The element found.

Example:

from botcity.web import By
...
# Find element by ID
elem = self.find_element("my_elem", By.ID)
# Find element by XPath
elem = self.find_element("//input[@type='submit']", By.XPATH)
...

find_elements(selector, by=By.CSS_SELECTOR, waiting_time=10000, ensure_visible=True)

Find elements using the specified selector with selector type specified by by.

Parameters:

Name	Type	Description	Default
selector	str	The selector string to be used.	required
by	str	Selector type. Defaults to By.CSS_SELECTOR. See more	CSS_SELECTOR
waiting_time	int	Maximum wait time (ms) to search for a hit. Defaults to 10000ms (10s).	10000
ensure_visible	bool	Whether to wait for the element to be visible. Defaults to True.	True

Returns:

Type	Description
List[WebElement]	List[WebElement]: List of elements found.

Example:

from botcity.web import By
...
# Find element by ID
all_cells = self.find_elements("//td", By.XPATH)
...

find_multiple(labels, x=None, y=None, width=None, height=None, *, threshold=None, matching=0.9, waiting_time=10000, best=True, grayscale=False)

Find multiple elements defined by label on screen until a timeout happens.

Parameters:

Name	Type	Description	Default
labels	list	A list of image identifiers	required
x	int	Search region start position x. Defaults to 0.	None
y	int	Search region start position y. Defaults to 0.	None
width	int	Search region width. Defaults to screen width.	None
height	int	Search region height. Defaults to screen height.	None
threshold	int	The threshold to be applied when doing grayscale search. Defaults to None.	None
matching	float	The matching index ranging from 0 to 1. Defaults to 0.9.	0.9
waiting_time	int	Maximum wait time (ms) to search for a hit. Defaults to 10000ms (10s).	10000
best	bool	Whether or not to keep looking until the best matching is found. Defaults to True.	True
grayscale	bool	Whether or not to convert to grayscale before searching. Defaults to False.	False

Returns:

Name	Type	Description
results	dict	A dictionary in which the key is the label and value are the element coordinates in a NamedTuple.

find_text(label, x=None, y=None, width=None, height=None, *, threshold=None, matching=0.9, waiting_time=10000, best=True)

Find an element defined by label on screen until a timeout happens.

Parameters:

Name	Type	Description	Default
label	str	The image identifier	required
x	int	Search region start position x. Defaults to 0.	None
y	int	Search region start position y. Defaults to 0.	None
width	int	Search region width. Defaults to screen width.	None
height	int	Search region height. Defaults to screen height.	None
threshold	int	The threshold to be applied when doing grayscale search. Defaults to None.	None
matching	float	The matching index ranging from 0 to 1. Defaults to 0.9.	0.9
waiting_time	int	Maximum wait time (ms) to search for a hit. Defaults to 10000ms (10s).	10000
best	bool	Whether or not to keep looking until the best matching is found. Defaults to True.	True

Returns:

Name	Type	Description
element	NamedTuple	The element coordinates. None if not found.

find_until(label, x=None, y=None, width=None, height=None, *, threshold=None, matching=0.9, waiting_time=10000, best=True, grayscale=False)

Find an element defined by label on screen until a timeout happens.

Parameters:

Name	Type	Description	Default
label	str	The image identifier	required
x	int	Search region start position x. Defaults to 0.	None
y	int	Search region start position y. Defaults to 0.	None
width	int	Search region width. Defaults to screen width.	None
height	int	Search region height. Defaults to screen height.	None
threshold	int	The threshold to be applied when doing grayscale search. Defaults to None.	None
matching	float	The matching index ranging from 0 to 1. Defaults to 0.9.	0.9
waiting_time	int	Maximum wait time (ms) to search for a hit. Defaults to 10000ms (10s).	10000
best	bool	Whether or not to keep looking until the best matching is found. Defaults to True.	True
grayscale	bool	Whether or not to convert to grayscale before searching. Defaults to False.	False

Returns:

Name	Type	Description
element	NamedTuple	The element coordinates. None if not found.

forward()

Goes one step forward in the browser history.

get_clipboard()

Get the current content in the clipboard.

Returns:

Name	Type	Description
text	str	Current clipboard content

get_element_coords(label, x=None, y=None, width=None, height=None, matching=0.9, best=True)

Find an element defined by label on screen and returns its coordinates.

Parameters:

Name	Type	Description	Default
label	str	The image identifier	required
x	int	X (Left) coordinate of the search area.	None
y	int	Y (Top) coordinate of the search area.	None
width	int	Width of the search area.	None
height	int	Height of the search area.	None
matching	float	Minimum score to consider a match in the element image recognition process. Defaults to 0.9.	0.9
best	bool	Whether or not to search for the best value. If False the method returns on the first find. Defaults to True.	True

Returns:

Name	Type	Description
coords	Tuple	A tuple containing the x and y coordinates for the element.

get_element_coords_centered(label, x=None, y=None, width=None, height=None, matching=0.9, best=True)

Find an element defined by label on screen and returns its centered coordinates.

Parameters:

Name	Type	Description	Default
label	str	The image identifier	required
x	int	X (Left) coordinate of the search area.	None
y	int	Y (Top) coordinate of the search area.	None
width	int	Width of the search area.	None
height	int	Height of the search area.	None
matching	float	Minimum score to consider a match in the element image recognition process. Defaults to 0.9.	0.9
best	bool	Whether or not to search for the best value. If False the method returns on the first find. Defaults to True.	True

Returns:

Name	Type	Description
coords	Tuple	A tuple containing the x and y coordinates for the center of the element.

get_file_count(path=None, file_extension='')

Get the total number of files of the same type.

Parameters:

Name	Type	Description	Default
path	str	The path of the folder where the files are saved.	None
file_extension	str	The extension of the files to be searched for (e.g., .pdf, .txt).	''

Returns:

Name	Type	Description
int		the number of files of the given type

get_image_from_map(label)

Return an image from teh state image map.

Parameters:

Name	Type	Description	Default
label	str	The image identifier	required

Returns:

Name	Type	Description
Image		The Image object

get_js_dialog()

Return the last found dialog. Invoke first the find_js_dialog method to look up.

Returns:

Name	Type	Description
dialog	dict	The dialog information or None if not available. See https://chromedevtools.github.io/devtools-protocol/tot/Page/#event-javascriptDialogOpening

get_last_created_file(path=None, file_extension='')

Returns the last created file in a specific folder path.

Parameters:

Name	Type	Description	Default
path	str	The path of the folder where the file is expected. Defaults to None.	None
file_extension	str	The extension of the file to be searched for (e.g., .pdf, .txt).	''

Returns:

Name	Type	Description
str		the path of the last created file

get_last_element()

Return the last element found.

Returns:

Name	Type	Description
element	NamedTuple	The element coordinates (left, top, width, height)

get_last_x()

Get the last X position for the mouse.

Returns:

Name	Type	Description
x	int	The last x position for the mouse.

get_last_y()

Get the last Y position for the mouse.

Returns:

Name	Type	Description
y	int	The last y position for the mouse.

get_screen_image(region=None)

Capture and returns a screenshot from the browser.

Parameters:

Name	Type	Description	Default
region	tuple	A tuple containing the left, top, width and height to crop the screen image.	None

Returns:

Name	Type	Description
image	Image	The screenshot Image object.

get_screenshot(filepath=None, region=None)

Capture a screenshot.

Parameters:

Name	Type	Description	Default
filepath	str	The filepath in which to save the screenshot. Defaults to None.	None
region	tuple	Bounding box containing left, top, width and height to crop screenshot.	None

Returns:

Name	Type	Description
Image		The screenshot Image object

get_tabs()

Get a list of tab handlers

Returns:

Name	Type	Description
list		List of tab handlers

get_viewport_size()

Returns the browser current viewport size.

Returns:

Name	Type	Description
width	int	The current viewport width.
height	int	The current viewport height.

handle_js_dialog(accept=True, prompt_text=None)

Accepts or dismisses a JavaScript initiated dialog (alert, confirm, prompt, or onbeforeunload). This also cleans the dialog information in the local buffer.

Parameters:

Name	Type	Description	Default
accept	bool	Whether to accept or dismiss the dialog.	True
prompt_text	str	The text to enter into the dialog prompt before accepting. Used only if this is a prompt dialog.	None

hold_shift(wait=0)

Hold key Shift

Parameters:

Name	Type	Description	Default
wait	int	Wait interval (ms) after task	0

install_firefox_extension(extension)

Install an extension in the Firefox browser. This will start the browser if it was not started yet.

Parameters:

Name	Type	Description	Default
extension	str	The path of the .xpi extension to be loaded.	required

kb_type(text, interval=0)

Type a text char by char (individual key events).

Parameters:

Name	Type	Description	Default
text	str	text to be typed.	required
interval	int	interval (ms) between each key press. Defaults to 0	0

key_end(wait=0)

Press key End

Parameters:

Name	Type	Description	Default
wait	int	Wait interval (ms) after task	0

key_enter(wait=0)

Press key Enter

Parameters:

Name	Type	Description	Default
wait	int	Wait interval (ms) after task	0

key_esc(wait=0)

Press key Esc

Parameters:

Name	Type	Description	Default
wait	int	Wait interval (ms) after task	0

key_home(wait=0)

Press key Home

Parameters:

Name	Type	Description	Default
wait	int	Wait interval (ms) after task	0

key_right(wait=0)

Press key Right

Parameters:

Name	Type	Description	Default
wait	int	Wait interval (ms) after task	0

leave_iframe()

Leave the iframe and switch the WebBot driver to the default content.

maximize_window()

Shortcut to maximize window on Windows OS.

mouse_down(wait_after=config.DEFAULT_SLEEP_AFTER_ACTION, *, button='left')

Holds down the requested mouse button.

Parameters:

Name	Type	Description	Default
wait_after	int	Interval to wait after clicking on the element.	DEFAULT_SLEEP_AFTER_ACTION
button	str	One of 'left', 'right', 'middle'. Defaults to 'left'	'left'

mouse_move(x, y)

Mouse the move to the coordinate defined by x and y

Parameters:

Name	Type	Description	Default
x	int	The X coordinate	required
y	int	The Y coordinate	required

mouse_up(wait_after=config.DEFAULT_SLEEP_AFTER_ACTION, *, button='left')

Releases the requested mouse button.

Parameters:

Name	Type	Description	Default
wait_after	int	Interval to wait after clicking on the element.	DEFAULT_SLEEP_AFTER_ACTION
button	str	One of 'left', 'right', 'middle'. Defaults to 'left'	'left'

move()

Move to the center position of last found item.

move_random(range_x, range_y)

Move randomly along the given x, y range.

Parameters:

Name	Type	Description	Default
range_x	int	Horizontal range	required
range_y	int	Vertical range	required

move_relative(x, y)

Move the mouse relative to its current position.

Parameters:

Name	Type	Description	Default
x	int	Horizontal offset	required
y	int	Vertical offset	required

move_to(x, y)

Move the mouse relative to its current position.

Parameters:

Name	Type	Description	Default
x	int	The X coordinate	required
y	int	The Y coordinate	required

navigate_to(url, is_retry=False)

Opens the browser on the given URL.

Parameters:

Name	Type	Description	Default
url	str	The URL to be visited.	required
is_retry	bool	Whether or not this is a retry attempt.	False

page_down(wait=0)

Press Page Down key

Parameters:

Name	Type	Description	Default
wait	int	Wait interval (ms) after task	0

page_source()

Returns the active page source.

Returns:

Name	Type	Description
soup	BeautifulSoup	BeautifulSoup object for the page source.

page_title()

Returns the active page title.

Returns:

Name	Type	Description
title	str	The page title.

page_up(wait=0)

Press Page Up key

Parameters:

Name	Type	Description	Default
wait	int	Wait interval (ms) after task	0

paste(text=None, wait=0)

Paste content from the clipboard.

Parameters:

Name	Type	Description	Default
text	str	The text to be pasted. Defaults to None	None
wait	int	Wait interval (ms) after task	0

print_pdf(path=None, print_options=None)

Print the current page as a PDF file.

Parameters:

Name	Type	Description	Default
path	str	The path for the file to be saved. Defaults to None.	None
print_options	dict	Print options as defined at. Defaults to None.	None

Returns:

Name	Type	Description
str		the saved file path

refresh()

Refreshes the current page.

release_shift()

Release key Shift. This method needs to be invoked after holding Shift or similar.

right_click(wait_after=config.DEFAULT_SLEEP_AFTER_ACTION, *, clicks=1, interval_between_clicks=0)

Right click on the last found element.

Parameters:

Name	Type	Description	Default
wait_after	int	Interval to wait after clicking on the element.	DEFAULT_SLEEP_AFTER_ACTION
clicks	int	Number of times to click. Defaults to 1.	1
interval_between_clicks	int	The interval between clicks in ms. Defaults to 0.	0

right_click_at(x, y)

Right click at the coordinate defined by x and y

Parameters:

Name	Type	Description	Default
x	int	The X coordinate	required
y	int	The Y coordinate	required

right_click_relative(x, y, interval_between_clicks=0, wait_after=config.DEFAULT_SLEEP_AFTER_ACTION)

Right Click Relative on the last found element.

Parameters:

Name	Type	Description	Default
x	int	Horizontal offset	required
y	int	Vertical offset	required
interval_between_clicks	int	The interval between clicks in ms. Defaults to 0.	0
wait_after	int	Interval to wait after clicking on the element.	DEFAULT_SLEEP_AFTER_ACTION

save_screenshot(path)

Saves a screenshot in a given path.

Parameters:

Name	Type	Description	Default
path	str	The filepath in which to save the screenshot	required

screen_cut(x, y, width=None, height=None)

Capture a screenshot from a region of the screen.

Parameters:

Name	Type	Description	Default
x	int	region start position x	required
y	int	region start position y	required
width	int	region width	None
height	int	region height	None

Returns:

Name	Type	Description
Image		The screenshot Image object

screenshot(filepath=None, region=None)

Capture a screenshot.

Parameters:

Name	Type	Description	Default
filepath	str	The filepath in which to save the screenshot. Defaults to None.	None
region	tuple	Bounding box containing left, top, width and height to crop screenshot.	None

Returns:

Name	Type	Description
Image		The screenshot Image object

scroll_down(clicks)

Scroll Down n clicks

Parameters:

Name	Type	Description	Default
clicks	int	Number of times to scroll down.	required

scroll_element(element, steps=100, interval=500, start=0, end=None)

Scrolls down an element by its scroll height or a given amount defined by start and end.

This is useful for scrolling down a page to load more content or to scroll down a dynamically loaded element.

Parameters:

Name	Type	Description	Default
element	WebElement	The element to scroll.	required
steps	int	Number of steps in which to conclude the scroll. Defaults to 100.	100
interval	float	Time interval between each step. Defaults to 500ms.	500
start	int	Start position. Defaults to 0.	0
end	int	End position. Defaults to None.	None

scroll_up(clicks)

Scroll Up n clicks

Parameters:

Name	Type	Description	Default
clicks	int	Number of times to scroll up.	required

set_current_element(element)

Changes the current screen element the bot will interact when using click(), move(), and similar methods.

This method is equivalent to self.state.element = element.

Parameters:

Name	Type	Description	Default
element	Box	A screen element from self.state.element or the find_all(as_list=True) method.	required

set_file_input_element(element, filepath)

Configure the filepath for upload in a file element. Note: This method does not submit the form.

Parameters:

Name	Type	Description	Default
element	WebElement	The file upload element.	required
filepath	str	The path to the file to be uploaded.	required

Example:

...
# Find element
elem = self.find_element("body > form > input[type=file]")
# Set the filepath
self.set_file_input_element(elem, "./test.txt")
...

set_screen_resolution(width=None, height=None)

Configures the browser dimensions.

Parameters:

Name	Type	Description	Default
width	int	The desired width.	None
height	int	The desired height.	None

sleep(interval)

Wait / Sleep for a given interval.

Parameters:

Name	Type	Description	Default
interval	int	Interval in milliseconds	required

space(wait=0)

Press Space key

Parameters:

Name	Type	Description	Default
wait	int	Wait interval (ms) after task	0

start_browser()

Starts the selected browser.

stop_browser()

Stops the Chrome browser and clean up the User Data Directory.

Warning

After invoking this method, you will need to reassign your custom options and capabilities.

tab(wait=0)

Press key Tab

Parameters:

Name	Type	Description	Default
wait	int	Wait interval (ms) after task	0

triple_click(wait_after=config.DEFAULT_SLEEP_AFTER_ACTION)

Triple Click on the last found element.

Parameters:

Name	Type	Description	Default
wait_after	int	Interval to wait after clicking on the element.	DEFAULT_SLEEP_AFTER_ACTION

triple_click_relative(x, y, interval_between_clicks=0, wait_after=config.DEFAULT_SLEEP_AFTER_ACTION)

Triple Click Relative on the last found element.

Parameters:

Name	Type	Description	Default
x	int	Horizontal offset	required
y	int	Vertical offset	required
interval_between_clicks	int	The interval between clicks in ms. Defaults to 0.	0
wait_after	int	Interval to wait after clicking on the element.	DEFAULT_SLEEP_AFTER_ACTION

type_down(wait=0)

Press Down key

Parameters:

Name	Type	Description	Default
wait	int	Wait interval (ms) after task	0

type_keys(keys)

Press a sequence of keys. Hold the keys in the specific order and releases them.

Parameters:

Name	Type	Description	Default
keys	list	List of keys to be pressed	required

type_keys_with_interval(interval, keys)

Press a sequence of keys. Hold the keys in the specific order and releases them.

Parameters:

Name	Type	Description	Default
interval	int	Interval (ms) in which to press and release keys	required
keys	list	List of Keys to be pressed	required

type_left(wait=0)

Press Left key

Parameters:

Name	Type	Description	Default
wait	int	Wait interval (ms) after task	0

type_right(wait=0)

Press Right key

Parameters:

Name	Type	Description	Default
wait	int	Wait interval (ms) after task	0

type_up(wait=0)

Press Up key

Parameters:

Name	Type	Description	Default
wait	int	Wait interval (ms) after task	0

wait(interval)

Wait / Sleep for a given interval.

Parameters:

Name	Type	Description	Default
interval	int	Interval in milliseconds	required

wait_for_downloads(timeout=120000)

Wait for all downloads to be finished. Beware that this method replaces the current page with the downloads window.

Parameters:

Name	Type	Description	Default
timeout	int	Timeout in millis. Defaults to 120000.	120000

wait_for_element_visibility(element, visible=True, waiting_time=10000)

Wait for the element to be visible or hidden.

Parameters:

Name	Type	Description	Default
element	WebElement	The element to wait for.	required
visible	bool	Whether to wait for the element to be visible. Defaults to True.	True
waiting_time	int	Maximum wait time (ms) to search for a hit. Defaults to 10000ms (10s).	10000

wait_for_file(path, timeout=60000)

Wait for a file to be available on disk.

Parameters:

Name	Type	Description	Default
path	str	The path for the file to be executed	required
timeout	int	Maximum wait time (ms) to search for a hit. Defaults to 60000ms (60s).	60000

Returns:

Name	Type	Description
status	bool	Whether or not the file was available before the timeout

wait_for_new_file(path=None, file_extension='', current_count=0, timeout=60000)

Wait for a new file to be available on disk without the file path.

Parameters:

Name	Type	Description	Default
path	str	The path of the folder where the file is expected. Defaults to None.	None
file_extension	str	The extension of the file to be searched for (e.g., .pdf, .txt).	''
current_count	int	The current number of files in the folder of the given type. Defaults to 0 files	0
timeout	int	Maximum wait time (ms) to search for a hit. Defaults to 60000ms (60s).	60000

Returns:

Name	Type	Description
str		the path of the last created file of the given type

wait_for_new_page(waiting_time=10000, activate=True)

Context manager to wait for a new page to load and activate it.

Parameters:

Name	Type	Description	Default
waiting_time	int	The maximum waiting time. Defaults to 10000.	10000
activate	bool	Whether or not to activate the new page. Defaults to True.	True

wait_for_stale_element(element, timeout=10000)

Wait until the WebElement element becomes stale (outdated).

Parameters:

Name	Type	Description	Default
element	WebElement	The element to monitor for staleness.	required
timeout	int	Timeout in millis. Defaults to 120000.	10000

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', binary_path=None)

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'
binary_path	str	The path to the browser binary.	None

Returns:

Name	Type	Description
ChromeOptions	Options	The Chrome options.

botcity.web.browsers.chrome.default_capabilities()

Fetch the default capabilities for this browser.

Returns:

Name	Type	Description
Dict	Dict	Dictionary with the default capabilities defined.

Firefox

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

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'
binary_path	str	The path to the browser binary.	None

Returns: FirefoxOptions: The Firefox options.

botcity.web.browsers.firefox.default_capabilities()

Fetch the default capabilities for this browser.

Returns:

Name	Type	Description
Dict	Dict	Dictionary with the default capabilities defined.

Edge

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

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". binary_path (str, optional): The path to the browser binary. Returns: EdgeOptions: The Edge options.

botcity.web.browsers.edge.default_capabilities()

Fetch the default capabilities for this browser. Returns: Dict: Dictionary with the default capabilities defined.

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:

Name	Type	Description
Options	Options	The Internet Explorer options.

botcity.web.browsers.ie.default_capabilities()

Fetch the default capabilities for this browser.

Returns:

Name	Type	Description
Dict	Dict	Dictionary with the default capabilities defined.

Form Utilities

botcity.web.util.element_as_select(element)

Wraps a WebElement in a Select object.

Parameters:

Name	Type	Description	Default
element	WebElement	The element to wrap.	required

Returns:

Name	Type	Description
Select	Select	The Select object.

Parsers

Tables

botcity.web.parsers.table_to_dict(table, has_header=True, skip_rows=0, header_tag='th', cell_xpath=None)

Convert a table WebElement to a dict of lists.

Parameters:

Name	Type	Description	Default
table	WebElement	The table element.	required
has_header	bool	Whether or not to parse a header. Defaults to True.	True
skip_rows	int	Number of rows to skip from the top. Defaults to 0.	0
header_tag	str	The HTML tag associated with the header cell. Defaults to "th".	'th'
cell_xpath	str	Optional cell XPath selector for complex row constructions. If cell_xpath is not informed, the row data will come from <td> elements.	None

Returns:

Name	Type	Description
list	List[Dict]	List with dict for each row.