Browser

Browser module for autopylot. This module is used to interact with browsers. It can launch browsers, create new windows and tabs, and navigate to URLs. It can also take screenshots and save them to files. Interact with web pages using the tab object returned by the launch function.

Examples:

>>> from autopylot import browser
>>> chrome_browser, window_object, tab_object, _ = browser.launch(browser='chromium', headless=False)
>>> browser.navigate(tab_object, url='https://www.pybots.ai')
>>> browser.get_screenshot(tab_object, file_path='screenshot.png')
>>> browser.close_tab(tab_object)
>>> browser.close_window(window_object)
>>> browser.close(chrome_browser)

It contains the following functions:

launch(browser, headless): Quick launch a browser and returns a single tab object.
launch_advanced(browser, headless, timeout, arg_list): Launch a browser and returns multiple objects to support much more advanced automation.
launch_persistent_chrome(profile, headless, msedge, user_data_dir, timeout, arg_list): Launch a persistent Chrome browser.
close(browser): Close the given browser.
create_new_window(browser): Create a new window in the given browser.
get_window(browser, index): Get the window at the given index. If index is not given, windows list is returned.
close_window(window): Close the given window.
create_new_tab(window): Create a new tab in the given window.
get_tab(window, index): Get the tab at the given index. If index is not given, tabs list is returned.
navigate(tab, url): Navigate to the given URL in the given tab.
reload(tab): Reload the current page in the given tab.
close_tab(tab): Close the given tab.
locate_by_role(tab, role, name): Locate an element by role and name.
locate_by_text(tab, text): Locate an element by text.
locate_by_label(tab, label): Locate an element by label.
locate_by_placeholder(tab, placeholder): Locate an element by placeholder.
locate_by_alt_text(tab, alt_text): Locate an element by alt text.
locate_by_title(tab, title): Locate an element by title.
locate_by_id(tab, id): Locate an element by id.
locate_by_test_id(tab, test_id): Locate an element by test id.
locate_by_selector(tab, selector): Locate an element by selector.
set_download_path(tab, path): Set the download path for the given tab.
perform_check(locator, timeout): Perform a check on the given locator.
perform_uncheck(locator, timeout): Perform an uncheck on the given locator.
perform_clear(locator, timeout): Perform a clear on the given locator.
perform_click(locator, button, click_count, timeout): Perform a click on the given locator.
perform_dbl_click(locator, button, timeout): Perform a double click on the given locator.
perform_wheel(tab, deltaX, deltaY): Perform a wheel on the given tab.
perform_fill(locator, value, timeout): Perform a fill on the given locator.
perform_type(locator, text, delay, timeout): Perform a type on the given locator.
perform_hover(locator, timeout): Perform a hover on the given locator.
perform_press(locator, key, timeout): Perform a press on the given locator.
perform_wait(locator, state, timeout): Perform a wait on the given locator.
select_option(locator, value, label, index, timeout): Perform a select option on the given locator.
select_text(locator, timeout): Perform a select text on the given locator.
set_input_files(locator, files, timeout): Perform a set input files on the given locator.
get_all(locator): Get all the elements matching the given locator.
get_inner_text(locator, timeout): Get the inner text of the given locator.
get_inner_html(locator, timeout): Get the inner html of the given locator.
get_input_value(locator, timeout): Get the input value of the given locator.
get_screenshot(tab, file_path, timeout): Take a screenshot of the given tab and save it to the given file path.
get_text_content(locator, timeout): Get the text content of the given locator.

`close(browser, kwargs)`

Close the browser. This will also close all windows and tabs in the browser.

Parameters:

Name	Type	Description	Default
`browser`	`object`	The browser to close.	required

Returns:

Type	Description
`None`	None

Examples:

>>> close(browser=chrome_browser)
>>> close(browser=firefox_browser)

`close_tab(tab, kwargs)`

Close the tab. This will also close the window if it is the last tab in the window.

Parameters:

Name	Type	Description	Default
`tab`	`object`	The tab to close.	required

Returns:

Type	Description
`None`	None

Examples:

>>> close_tab(tab=tab_1)

`close_window(window, kwargs)`

Close the window.

Parameters:

Name	Type	Description	Default
`window`	`object`	The window to close.	required

Returns:

Type	Description
`None`	None

Examples:

>>> close_window(window=window_1)

`create_new_tab(window, kwargs)`

Launch a new tab in the window.

Parameters:

Name	Type	Description	Default
`window`	`object`	The window to launch the tab in.	required

Returns:

Name	Type	Description
`tab`	`object`	A tab object. This object can be used to navigate to a URL and interact with the webpage in the tab.

Examples:

>>> tab_1 = create_new_tab(window=window_1)

`create_new_window(browser, kwargs)`

Launch a new window in the browser. You can't see the window until you launch a tab in it.

Parameters:

Name	Type	Description	Default
`browser`	`object`	The browser to launch the window in.	required

Returns:

Name	Type	Description
`window`	`object`	A window object. This object can be used to launch tabs.

Examples:

>>> chrome_browser = launch(browser='chromium', headless=False)
>>> window_1 = create_new_window(chrome_browser)

`get_all(locator, kwargs)`

Get all elements that match the locator.

Parameters:

Name	Type	Description	Default
`locator`	`object`	The locator object.	required

Returns:

Name	Type	Description
`elements`	`list`	A list of elements.

Examples:

>>> elements = get_all(locator=locator)

`get_inner_html(locator, timeout=10000, kwargs)`

Get the inner html of the element.

Parameters:

Name	Type	Description	Default
`locator`	`object`	The locator object.	required
`timeout`	`int`	The timeout in milliseconds.	`10000`

Returns:

Name	Type	Description
`html`	`str`	The inner html of the element.

Examples:

>>> html = get_inner_html(locator=locator)

`get_inner_text(locator, timeout=10000, kwargs)`

Get the inner text of the element.

Parameters:

Name	Type	Description	Default
`locator`	`object`	The locator object.	required
`timeout`	`int`	The timeout in milliseconds.	`10000`

Returns:

Name	Type	Description
`text`	`str`	The inner text of the element.

Examples:

>>> text = get_inner_text(locator=locator)

`get_input_value(locator, timeout=10000, kwargs)`

Get the value of the element.

Parameters:

Name	Type	Description	Default
`locator`	`object`	The locator object.	required
`timeout`	`int`	The timeout in milliseconds.	`10000`

Returns:

Name	Type	Description
`value`	`str`	The value of the element.

Examples:

>>> value = get_input_value(locator=locator)

`get_screenshot(element, path, timeout=10000, kwargs)`

Get the screenshot of the Page or element.

Parameters:

Name	Type	Description	Default
`element`	`object`	The element object.	required
`path`	`str \|\| WindowsPath`	The path to save the screenshot.	required
`timeout`	`int`	The timeout in milliseconds.	`10000`

Returns:

Name	Type	Description
`Image`	`bytes`	The screenshot of the element.

Examples:

>>> get_screenshot(locator=locator, path='screenshot.png')

`get_tab(window, index=None)`

Get the tab at the specified index, starting at 0. If no index is specified, tabs list is returned.

Parameters:

Name	Type	Description	Default
`window`	`object`	The window to get the tab from.	required
`index`	`int`	The index of the tab to get.	`None`

Returns:

Name	Type	Description
`tab`	`object`	A tab object. This object can be used to navigate to a URL and interact with the webpage in the tab.

Examples:

>>> chrome_browser = launch_advanced()
>>> window_1 = get_window(chrome_browser, index=0)
>>> tab_1 = get_tab(window=window_1, index=0)
>>> tab_2 = get_tab(window=window_1, index=1)
>>> tabs = get_tab(window=window_1)

`get_text_content(locator, timeout=10000, kwargs)`

Get the text content of the element.

Parameters:

Name	Type	Description	Default
`locator`	`object`	The locator object.	required
`timeout`	`int`	The timeout in milliseconds.	`10000`

Returns:

Name	Type	Description
`text`	`str`	The text content of the element.

Examples:

>>> text = get_text_content(locator=locator)

`get_window(browser, index=None)`

Get the window at the specified index, starting at 0. If no index is specified, windows list is returned.

Parameters:

Name	Type	Description	Default
`browser`	`object`	The browser to get the window from.	required
`index`	`int`	The index of the window to get.	`None`

Returns:

Name	Type	Description
`window`	`object \|\| list`	A window object or list of window objects. This object can be used to launch tabs.

Examples:

>>> chrome_browser = launch(browser='chromium', headless=False)
>>> window_1 = get_window(chrome_browser, index=0)
>>> window_2 = get_window(chrome_browser, index=1)
>>> windows = get_window(chrome_browser)

`launch(browser='chromium', headless=False, kwargs)`

Quick launch a browser and returns a single tab object. Defaults to Chromium. Other options are Firefox and WebKit.

Parameters:

Name	Type	Description	Default
`browser`	`str`	The browser to launch. Valid options are: chromium, firefox, webkit.	`'chromium'`
`headless`	`bool`	Whether to launch the browser in headless mode.	`False`

Returns:

Name	Type	Description
`tab`	`Page`	A tab object. This object can be used to navigate to a URL and perform actions on the page.

Examples:

>>> tab_object = launch(browser='chromium', headless=False)
>>> window_object = launch(browser='firefox', headless=False)

`launch_advanced(browser='chromium', headless=False, timeout=10000, arg_list=None, kwargs)`

Launch a browser and returns multiple objects to support much more advanced automation. Defaults to Chromium. Other options are Firefox and WebKit.

Parameters:

Name	Type	Description	Default
`browser`	`str`	The browser to launch. Valid options are: chromium, firefox, webkit.	`'chromium'`
`headless`	`bool`	Whether to launch the browser in headless mode.	`False`
`timeout`	`int`	The timeout in seconds to wait for the browser to launch.	`10000`
`arg_list`	`list`	A list of arguments to pass to the browser.	`None`

Returns:

Name	Type	Description
`browser`	`object`	A browser object. This object can be used to create browser windows and windows can be used to create tabs.

Examples:

>>> chrome_browser = launch(browser='chromium', headless=False)
>>> firefox_browser = launch(browser='firefox', headless=False)

`launch_persistent_chrome(profile='Default', headless=False, msedge=True, user_data_dir=None, timeout=10000, arg_list=None, kwargs)`

Launch a persistent Chrome browser. This browser will save cookies and other data.

Parameters:

Name	Type	Description	Default
`profile`	`str`	The name of the profile to use.	`'Default'`
`headless`	`bool`	Whether to launch the browser in headless mode.	`False`
`msedge`	`bool`	Whether to use the MS Edge browser.	`True`
`user_data_dir`	`str \|\| WindowsPath`	The path to the user data directory.	`None`
`arg_list`	`list`	A list of arguments to pass to the browser.	`None`
`timeout`	`int`	The timeout in seconds to wait for the browser to launch.	`10000`

Returns:

Name	Type	Description
`window`	`object`	A window object. This object can be used to launch tabs.
`tab`	`object`	A tab object. This object can be used to navigate to a URL.

Examples:

>>> window_object, tab_object = launch_persistent_chrome()
>>> window_object, tab_object = launch_persistent_chrome(profile='Profile 1')
>>> window_object, tab_object = launch_persistent_chrome(msedge=False)

`locate_by_alt_text(tab, alt_text, kwargs)`

Locate an element by its alt text.

Parameters:

Name	Type	Description	Default
`tab`	`object`	The tab to locate the element in.	required
`alt_text`	`str`	The alt text of the element to locate.	required

Returns:

Name	Type	Description
`locator`	`object`	A locator object. This object can be used to click on the element.

Examples:

>>> locator = locate_by_alt_text(alt_text='Click Me')

`locate_by_id(tab, id, kwargs)`

Locate an element by its id.

Parameters:

Name	Type	Description	Default
`tab`	`object`	The tab to locate the element in.	required
`id`	`str`	The id of the element to locate.	required

Returns:

Name	Type	Description
`locator`	`object`	A locator object. This object can be used to click on the element.

Examples:

>>> locator = locate_by_id(id='Click Me')

`locate_by_label(tab, label)`

Locate an element by its label.

Parameters:

Name	Type	Description	Default
`tab`	`object`	The tab to locate the element in.	required
`label`	`str`	The label of the element to locate.	required

Returns:

Name	Type	Description
`locator`	`object`	A locator object. This object can be used to click on the element.

Examples:

>>> locator = locate_by_label(label='Password')

`locate_by_placeholder(tab, placeholder, kwargs)`

Locate an element by its placeholder.

Parameters:

Name	Type	Description	Default
`tab`	`object`	The tab to locate the element in.	required
`placeholder`	`str`	The placeholder of the element to locate.	required

Returns:

Name	Type	Description
`locator`	`object`	A locator object. This object can be used to click on the element.

Examples:

>>> locator = locate_by_placeholder(placeholder='name@example.com')

`locate_by_role(tab, role, name, kwargs)`

Locate an element by its role and name.

Parameters:

Name	Type	Description	Default
`tab`	`object`	The tab to locate the element in.	required
`role`	`str`	The role of the element to locate.	required
`name`	`str`	The name of the element to locate.	required

Returns:

Name	Type	Description
`locator`	`object`	A locator object. This object can be used to click on the element.

Examples:

>>> locator = locate_by_role(role='button', name='Click Me')

`locate_by_selector(tab, selector, kwargs)`

Locate an element by its CSS selector or XPath.

Parameters:

Name	Type	Description	Default
`tab`	`object`	The tab to locate the element in.	required
`selector`	`str`	The selector or Xpath of the element to locate.	required

Returns:

Name	Type	Description
`locator`	`object`	A locator object. This object can be used to click on the element.

Examples:

>>> locator = locate_by_selector(selector='Click Me')

`locate_by_test_id(tab, test_id, kwargs)`

Locate an element by its test id.

Parameters:

Name	Type	Description	Default
`tab`	`object`	The tab to locate the element in.	required
`test_id`	`str`	The test id of the element to locate.	required

Returns:

Name	Type	Description
`locator`	`object`	A locator object. This object can be used to click on the element.

Examples:

>>> locator = locate_by_test_id(test_id='Click Me')

`locate_by_text(tab, text, kwargs)`

Locate an element by its text.

Parameters:

Name	Type	Description	Default
`tab`	`object`	The tab to locate the element in.	required
`text`	`str`	The text of the element to locate.	required

Returns:

Name	Type	Description
`locator`	`object`	A locator object. This object can be used to click on the element.

Examples:

>>> locator = locate_by_text(text='Click Me')

`locate_by_title(tab, title, kwargs)`

Locate an element by its title.

Parameters:

Name	Type	Description	Default
`tab`	`object`	The tab to locate the element in.	required
`title`	`str`	The title of the element to locate.	required

Returns:

Name	Type	Description
`locator`	`object`	A locator object. This object can be used to click on the element.

Examples:

>>> locator = locate_by_title(title='Click Me')

`navigate(tab, url, kwargs)`

Navigate to a URL in the tab.

Parameters:

Name	Type	Description	Default
`tab`	`object`	The tab to navigate to the URL in.	required
`url`	`str`	The URL to navigate to.	required

Returns:

Type	Description
`None`	None

Examples:

>>> navigate(tab=tab_1, url="https://www.google.com")

`perform_check(locator, timeout=10000, kwargs)`

Check the checkbox.

Parameters:

Name	Type	Description	Default
`locator`	`object`	The locator object.	required
`timeout`	`int`	The timeout in milliseconds.	`10000`

Returns:

Type	Description
`None`	None

Examples:

>>> perform_check(locator=locator)

`perform_clear(locator, timeout=10000, kwargs)`

Clear the text field.

Parameters:

Name	Type	Description	Default
`locator`	`object`	The locator object.	required
`timeout`	`int`	The timeout in milliseconds.	`10000`

Returns:

Type	Description
`None`	None

Examples:

>>> perform_clear(locator=locator)

`perform_click(locator, button='left', click_count=1, timeout=10000, kwargs)`

Click on the element.

Parameters:

Name	Type	Description	Default
`locator`	`object`	The locator object.	required
`button`	`str`	The button to click. Options are 'left', 'right', 'middle'.	`'left'`
`click_count`	`int`	The number of times to click.	`1`
`timeout`	`int`	The timeout in milliseconds.	`10000`

Returns:

Type	Description
`None`	None

Examples:

>>> perform_click(locator=locator)

`perform_dbl_click(locator, button='left', timeout=10000, kwargs)`

Double click on the element.

Parameters:

Name	Type	Description	Default
`locator`	`object`	The locator object.	required
`button`	`str`	The button to click. Options are 'left', 'right', 'middle'.	`'left'`
`timeout`	`int`	The timeout in milliseconds.	`10000`

Returns:

Type	Description
`None`	None

Examples:

>>> perform_dbl_click(locator=locator)

`perform_fill(locator, text, timeout=10000, kwargs)`

Fill the text field.

Parameters:

Name	Type	Description	Default
`locator`	`object`	The locator object.	required
`text`	`str`	The text to fill.	required
`timeout`	`int`	The timeout in milliseconds.	`10000`

Returns:

Type	Description
`None`	None

Examples:

>>> perform_fill(locator=locator, text='Hello World')

`perform_hover(locator, timeout=10000, kwargs)`

Hover over the element.

Parameters:

Name	Type	Description	Default
`locator`	`object`	The locator object.	required
`timeout`	`int`	The timeout in milliseconds.	`10000`

Returns:

Type	Description
`None`	None

Examples:

>>> perform_hover(locator=locator)

`perform_press(locator, key, timeout=10000, kwargs)`

Press a key on the element.

Parameters:

Name	Type	Description	Default
`locator`	`object`	The locator object.	required
`key`	`str`	The key to press.	required
`timeout`	`int`	The timeout in milliseconds.	`10000`

Returns:

Type	Description
`None`	None

Examples:

>>> perform_press(locator=locator, key='Enter')

`perform_type(locator, text, delay=0, timeout=10000, kwargs)`

Type text into the element. Like a human. Use delay to slow down the typing.

Parameters:

Name	Type	Description	Default
`locator`	`object`	The locator object.	required
`text`	`str`	The text to type.	required
`delay`	`int`	The delay in milliseconds between each key press.	`0`
`timeout`	`int`	The timeout in milliseconds.	`10000`

Returns:

Type	Description
`None`	None

Examples:

>>> perform_type(locator=locator, text='Hello World', delay=0)

`perform_uncheck(locator, timeout=10000, kwargs)`

Uncheck the checkbox.

Parameters:

Name	Type	Description	Default
`locator`	`object`	The locator object.	required
`timeout`	`int`	The timeout in milliseconds.	`10000`

Returns:

Type	Description
`None`	None

Examples:

>>> perform_uncheck(locator=locator)

`perform_wait(locator, state='visible', timeout=10000, kwargs)`

Wait for the element to be in a certain state.

Parameters:

Name	Type	Description	Default
`locator`	`object`	The locator object.	required
`state`	`str`	The state to wait for. Options are 'attached', 'detached', 'hidden', 'visible'.	`'visible'`
`timeout`	`int`	The timeout in milliseconds.	`10000`

Returns:

Type	Description
`None`	None

Examples:

>>> perform_wait(locator=locator, state='visible')

`perform_wheel(tab, deltaX=10, deltaY=10, kwargs)`

Scroll the element.

Parameters:

Name	Type	Description	Default
`tab`	`object`	The tab object.	required
`deltaX`	`int`	The number of pixels to scroll horizontally.	`10`
`deltaY`	`int`	The number of pixels to scroll vertically.	`10`

Returns:

Type	Description
`None`	None

Examples:

>>> perform_wheel(tab=tab, deltaX=10, deltaY=10)

`reload(tab, kwargs)`

Reload the tab.

Parameters:

Name	Type	Description	Default
`tab`	`object`	The tab to reload.	required

Returns:

Type	Description
`None`	None

Examples:

>>> reload(tab=tab_1)

`select_option(locator, value=None, label=None, index=None, timeout=10000, kwargs)`

Select an option from the element.

Parameters:

Name	Type	Description	Default
`locator`	`object`	The locator object.	required
`value`	`str`	The value of the option to select.	`None`
`label`	`str`	The label of the option to select.	`None`
`index`	`int`	The index of the option to select.	`None`
`timeout`	`int`	The timeout in milliseconds.	`10000`

Returns:

Type	Description
`None`	None

Examples:

>>> select_option(locator=locator, value='1')

`select_text(locator, timeout=10000, kwargs)`

Select text in the element.

Parameters:

Name	Type	Description	Default
`locator`	`object`	The locator object.	required
`timeout`	`int`	The timeout in milliseconds.	`10000`

Returns:

Type	Description
`None`	None

Examples:

>>> select_text(locator=locator)

`set_download_path(tab, path)`

Set the download path for the element.

Parameters:

Name	Type	Description	Default
`tab`	`object`	The tab to set the download path in.	required
`path`	`str \|\| WindowsPath`	The path to download the file to.	required

Returns:

Type	Description
`None`	None

Examples:

>>> set_download_path(locator=locator, path='/path/to/download')

`set_input_files(locator, files, timeout=10000, kwargs)`

Set the files to upload for the element.

Parameters:

Name	Type	Description	Default
`locator`	`object`	The locator object.	required
`files`	`str \|\| list`	The files to upload.	required
`timeout`	`int`	The timeout in milliseconds.	`10000`

Returns:

Type	Description
`None`	None

Examples:

>>> set_input_files(locator=locator, files=['/path/to/file'])