Python

O módulo botcity.web contém implementações especializadas destinadas à automação web, como o WebBot que é descrito abaixo.

Ao instanciar um WebBot, você terá acesso aos métodos responsáveis por automatizar aplicações e processos no navegador.

Aqui está um exemplo muito breve de um bot que abre o site da Botcity usando o Google Chrome e o WebDriver do chromedriver para controlar remotamente o navegador.

from botcity.web import WebBot


def main():
    # Instancia o WebBot
    bot = WebBot()

    # Configure se deseja ou não executar no modo headless.
    bot.headless = False

    # Defina o caminho do WebDriver
    bot.driver_path = "<path to your WebDriver binary>"

    # Abre o site do BotCity.
    bot.browse("https://www.botcity.dev")

    # Aguarde 3 segundos antes de fechar.
    bot.wait(3000)

    # Concluir e limpar o navegador da Web.
    bot.stop_browser()


if __name__ == '__main__':
    main()

botcity.web.bot.WebBot (BaseBot)

binary_path property writable

The binary path to be used.

Returns:

Type	Description
binary_path (pathlib.Path)	The binary path to be used.

browser property writable

The web browser to be used.

Returns:

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:

Type	Description
capabilities (Dict)	The browser specific capabilities to be used.

driver property readonly

The WebDriver driver instance.

Returns:

Type	Description
driver (WebDriver)	The WebDriver driver instance.

headless property writable

Controls whether or not the bot will run headless.

Returns:

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:

Type	Description
options (Options)	The browser specific options to be used.

page_load_strategy: PageLoadStrategy property writable

The page load strategy to be used.

Returns:

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

activate_tab(self, handle)

Activate a tab given by the handle.

Parameters:

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

add_image(self, 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(self)

Goes one step backward in the browser history.

backspace(self, wait=0)

Press Backspace key

Parameters:

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

browse(self, url)

Opens the browser on the given URL.

Parameters:

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

click(self, wait_after=300, *, 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.	300
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(self, 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(self, label)

Click on the element.

Parameters:

Name	Type	Description	Default
label	str	The image identifier	required

click_relative(self, x, y, wait_after=300, *, 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.	300
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(self)

Close the current active page (tab or window).

control_a(self, wait=0)

Press keys CTRL+A

Parameters:

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

control_c(self, wait=0)

Press keys CTRL+C

Parameters:

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

control_v(self, wait=0)

Press keys CTRL+V

Parameters:

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

copy_to_clipboard(self, 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(self, url)

Create a new tab and navigate to the given URL.

Parameters:

Name	Type	Description	Default
url	str	The desired URL.	required

create_window(self, url)

Creates a new window with the given URL.

Parameters:

Name	Type	Description	Default
url	str	The desired URL.	required

delete(self, wait=0)

Press Delete key

Parameters:

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

display_size(self)

Returns the display size in pixels.

Returns:

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

double_click(self, wait_after=300)

Double Click on the last found element.

Parameters:

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

double_click_relative(self, x, y, interval_between_clicks=0, wait_after=300)

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.	300

enter(self, wait=0)

Press key Enter

Parameters:

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

enter_iframe(self, iframe)

Switch the WebBot driver to the specified iframe.

Parameters:

Name	Type	Description	Default
iframe	WebElement	The desired iFrame.	required

execute_javascript(self, code)

Execute the given javascript code.

Parameters:

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

Returns:

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

find(self, 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:

Type	Description
element (NamedTuple)	The element coordinates. None if not found.

find_all(self, 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:

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

find_element(self, selector, 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:

Type	Description
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(self, selector, 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 of elements found.

Example:

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

find_multiple(self, 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:

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

find_text(self, 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:

Type	Description
element (NamedTuple)	The element coordinates. None if not found.

find_until(self, 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:

Type	Description
element (NamedTuple)	The element coordinates. None if not found.

forward(self)

Goes one step forward in the browser history.

get_clipboard(self)

Get the current content in the clipboard.

Returns:

Type	Description
text (str)	Current clipboard content

get_element_coords(self, 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:

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

get_element_coords_centered(self, 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:

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

get_file_count(self, 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:

Type	Description
int	the number of files of the given type

get_image_from_map(self, label)

Return an image from teh state image map.

Parameters:

Name	Type	Description	Default
label	str	The image identifier	required

Returns:

Type	Description
Image	The Image object

get_js_dialog(self)

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

Returns:

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(self, 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:

Type	Description
str	the path of the last created file

get_last_element(self)

Return the last element found.

Returns:

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

get_last_x(self)

Get the last X position for the mouse.

Returns:

Type	Description
x (int)	The last x position for the mouse.

get_last_y(self)

Get the last Y position for the mouse.

Returns:

Type	Description
y (int)	The last y position for the mouse.

get_screen_image(self, 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:

Type	Description
image (Image)	The screenshot Image object.

get_screenshot(self, 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:

Type	Description
Image	The screenshot Image object

get_tabs(self)

Get a list of tab handlers

Returns:

Type	Description
list	List of tab handlers

get_viewport_size(self)

Returns the browser current viewport size.

Returns:

Type	Description
width (int)	The current viewport width. height (int): The current viewport height.

handle_js_dialog(self, 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(self, wait=0)

Hold key Shift

Parameters:

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

install_firefox_extension(self, 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(self, 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(self, wait=0)

Press key End

Parameters:

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

key_enter(self, wait=0)

Press key Enter

Parameters:

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

key_esc(self, wait=0)

Press key Esc

Parameters:

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

key_home(self, wait=0)

Press key Home

Parameters:

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

key_right(self, wait=0)

Press key Right

Parameters:

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

leave_iframe(self)

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

maximize_window(self)

Shortcut to maximize window on Windows OS.

mouse_down(self, wait_after=300, *, button='left')

Holds down the requested mouse button.

Parameters:

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

mouse_move(self, 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(self, wait_after=300, *, button='left')

Releases the requested mouse button.

Parameters:

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

move(self)

Move to the center position of last found item.

move_random(self, 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(self, 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(self, 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(self, 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(self, wait=0)

Press Page Down key

Parameters:

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

page_source(self)

Returns the active page source.

Returns:

Type	Description
soup (BeautifulSoup)	BeautifulSoup object for the page source.

page_title(self)

Returns the active page title.

Returns:

Type	Description
title (str)	The page title.

page_up(self, wait=0)

Press Page Up key

Parameters:

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

paste(self, 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(self, 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:

Type	Description
str	the saved file path

refresh(self)

Refreshes the current page.

release_shift(self)

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

right_click(self, wait_after=300, *, 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.	300
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(self, 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(self, x, y, interval_between_clicks=0, wait_after=300)

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.	300

save_screenshot(self, 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(self, 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:

Type	Description
Image	The screenshot Image object

screenshot(self, 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:

Type	Description
Image	The screenshot Image object

scroll_down(self, clicks)

Scroll Down n clicks

Parameters:

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

scroll_element(self, 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(self, clicks)

Scroll Up n clicks

Parameters:

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

set_current_element(self, 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(self, 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(self, 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(self, interval)

Wait / Sleep for a given interval.

Parameters:

Name	Type	Description	Default
interval	int	Interval in milliseconds	required

space(self, wait=0)

Press Space key

Parameters:

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

start_browser(self)

Starts the selected browser.

stop_browser(self)

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(self, wait=0)

Press key Tab

Parameters:

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

triple_click(self, wait_after=300)

Triple Click on the last found element.

Parameters:

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

triple_click_relative(self, x, y, interval_between_clicks=0, wait_after=300)

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.	300

type_down(self, wait=0)

Press Down key

Parameters:

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

type_keys(self, 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(self, 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(self, wait=0)

Press Left key

Parameters:

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

type_right(self, wait=0)

Press Right key

Parameters:

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

type_up(self, wait=0)

Press Up key

Parameters:

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

wait(self, interval)

Wait / Sleep for a given interval.

Parameters:

Name	Type	Description	Default
interval	int	Interval in milliseconds	required

wait_for_downloads(self, 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(self, 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(self, 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:

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

wait_for_new_file(self, 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:

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

wait_for_new_page(self, 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(self, 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

Módulos específicos do navegador

Aqui está a documentação para os métodos mencionados acima para cada um dos navegadores suportados.

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:

Type	Description
ChromeOptions	The 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.

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:

Type	Description
FirefoxOptions	The 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.

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.

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:

Type	Description
EdgeOptions	The 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.

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.

botcity.web.browsers.ie.default_capabilities()

Fetch the default capabilities for this browser.

Returns:

Type	Description
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:

Type	Description
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:

Type	Description
list	List with dict for each row.