Chrome Actions

Chrome Actions are actions to interact with Chrome Web Browser.

All Chrome actions should use browser instance, created by the chrome.open action.

Identifying an element

Chrome actions that interact with an element, will always give you to option to identifiy the element selector or element. When to use each of them?

element: use when you already have the element object returned from any other action.

selector: use when you don't have the desired element object.

All actions will allow to pass only selector or element, but when of them should always be given.

Using the Selector

Marvin uses the same selector patter as JavaScript, with the following notation:

CSS Class: to select an element by css class, should use . followed by the class name. Example: .menu_class.

Element ID: to select an element by ID, should use # followed by element ID. Example: #login.

Tag Name: to select an element by the tag name, just insert the tag name. Example: tbody

Tag with parameter: to select an element by tag and parameter, use the sintax tag[param=value]. If you want to use multiple parameters, use the sintax: tag[param1=value1][param2=value2]

Parameter wildcard: it is possible to use wildcard in parameters, using:

id^=someId: will match all ids starting with someId as someId1, someId-other

id$=someId: will match all ids ending with someId as 1someId, other-someId

id*=someId: will match all ids containing someId as someId1, someId-other, 1someId, other-someId

Actions

chrome.change_select

Change the <select> value, to the given value.

Do not use selector and element at the same time.

If this action is called using selector the onChange event will be automatically triggered.

If this action is called using an element object, the onChange event will not be fired. You can fire onChange event manually using the chrome.execute_js action.

Parameters:

browser - browser instance given from chrome.open.

value - Value that should be setted to <select> element.

selector (optional) - identifier of the element in selector mode (default=None).

element (optional) - element object to change (default=None).

inside (optional) - this value define the element object where the selector should be found in (default=all document).

iframe_search (optional) - define if selector should be found in the base document or any documents, even inside iframes. If setted True will search inside all iframes, and if setted False will search only inside the main document (default=True).

Return:

This action gives no return

Exceptions:

ElementNotFound: if the given selector don't match to any element in page.

chrome.click_element

Click with mouse in the middle of the given element.

Parameters:

browser - browser instance given from chrome.open.

selector (optional) - identifier of the element in selector mode (default=None).

element (optional) - element object to change (default=None).

inside (optional) - this value define the element object where the selector should be found in (default=all document).

iframe_search (optional) - define if selector should be found in the base document or any documents, even inside iframes. If setted True will search inside all iframes, and if setted False will search only inside the main document (default=True).

clicks (optional) - number of clicks to be performed at position (default=1)

button (optional) - defines witch mouse button should de used for multiple clicks 'left', 'middle' or 'right' (default='left').

interval (optional) - interval between each click, for slower computers, consider set a higher value than default (default=0 - instantaneous).

timeout (optional) - timeout to wait for element appear (default=5 seconds).

Return:

x - X position of the middle of the component

y - Y position of the middle of the component

Exceptions:

ElementNotFound: if the given selector don't match to any element in page.

chrome.close

Closes the given Chrome Web Browser instance

Parameters:

browser - browser instance given from chrome.open.

Return:

This action gives no return

chrome.get_tabs

Return all opened tabs on the given instance

Parameters:

browser - browser instance given from chrome.open.

Return:

tabs - list with all opened tab names

chrome.execute_js

Execute a Javascript expression on the current tab. Javascript must be possible to execute on higher page scope.

Parameters:

browser - browser instance given from chrome.open.

expression - Javascript expression to be executed.

await_promise (optional) - defines if expression will await for any promise, in case of async expression (default=True).

Return:

js_result - object with all informations about Javascript execution. Morei nformation about this object could be found here.

chrome.focus

Set the focus over the given element.

Parameters:

browser - browser instance given from chrome.open.

selector (optional) - identifier of the element in selector mode (default=None).

element (optional) - element object to change (default=None).

inside (optional) - this value define the element object where the selector should be found in (default=all document).

iframe_search (optional) - define if selector should be found in the base document or any documents, even inside iframes. If setted True will search inside all iframes, and if setted False will search only inside the main document (default=True).

Return:

This action gives no return

Exceptions:

ElementNotFound: if the given selector don't match to any element in page.

chrome.get_element

Return the first element found for the given selector name.

Parameters:

browser - browser instance given from chrome.open.

selector (optional) - identifier of the element in selector mode (default=None).

inside (optional) - this value define the element object where the selector should be found in (default=all document).

depth (optional) - define the depth (levels) of children elements to return (default=1).

iframe_search (optional) - define if selector should be found in the base document or any documents, even inside iframes. If setted True will search inside all iframes, and if setted False will search only inside the main document (default=True).

Return:

element - element object for the given selector or None if no element were found.

chrome.get_element_center

Return the X and Y position of the center of the given element. If the selector was given will return the first element found for the given selector.

Parameters:

browser - browser instance given from chrome.open.

selector (optional) - identifier of the element in selector mode (default=None).

element (optional) - element object to change (default=None).

inside (optional) - this value define the element object where the selector should be found in (default=all document).

iframe_search (optional) - define if selector should be found in the base document or any documents, even inside iframes. If setted True will search inside all iframes, and if setted False will search only inside the main document (default=True).

Return:

x - X position of the middle of the component

y - Y position of the middle of the component

chrome.get_element_position

Return the X, Y, width and height of the given element on screen. If the selector was given will return the first element found for the given selector.

Parameters:

browser - browser instance given from chrome.open.

selector (optional) - identifier of the element in selector mode (default=None).

element (optional) - element object to change (default=None).

inside (optional) - this value define the element object where the selector should be found in (default=all document).

iframe_search (optional) - define if selector should be found in the base document or any documents, even inside iframes. If setted True will search inside all iframes, and if setted False will search only inside the main document (default=True).

Return:

x - Left position of the component

y - Top position of the component

width: Width of the component

height: Height of the component

Exceptions:

ElementNotFound: if the given selector don't match to any element in page.

InvalidPosition: if the given selector or element is not visible.

chrome.get_elements

Return the first element found for the given selector name.

Parameters:

browser - browser instance given from chrome.open.

selector (optional) - identifier of the element in selector mode (default=None).

inside (optional) - this value define the element object where the selector should be found in (default=all document).

depth (optional) - define the depth (levels) of children elements to return (default=1).

iframe_search (optional) - define if selector should be found in the base document or any documents, even inside iframes. If setted True will search inside all iframes, and if setted False will search only inside the main document (default=True).

Return:

elements - list of element objects for the given selector or empty list if no element were found. length - number of found elements

chrome.has_download_in_progress

Check if there is any download in progress on the browser instance, and returns True if there is at least one download in progress or False if there is no donwload in progress.

Parameters:

browser - browser instance given from chrome.open.

Return:

downloads_in_progress - True if there is at least one download in progress or False if there is no donwload in progress.

chrome.is_element_visible

Check if the given element is visible or hidden on the screen.

Elements that are visible but need to scroll the screen to be seen, are considered visible for this action.

Parameters:

browser - browser instance given from chrome.open.

selector (optional) - identifier of the element in selector mode (default=None).

element (optional) - element object to change (default=None).

inside (optional) - this value define the element object where the selector should be found in (default=all document).

iframe_search (optional) - define if selector should be found in the base document or any documents, even inside iframes. If setted True will search inside all iframes, and if setted False will search only inside the main document (default=True).

timeout (optional) - timeout to wait for element appear (default=5 seconds).

Return:

is_visible - True if the element is visible and False if element still hidden after timeout.

Exceptions:

ElementNotFound: if the given selector don't match to any element in page.

TimeoutException: if element is not visible until timeout is reached

chrome.navigate

Change the URL of the given browser, navigating to it.

Parameters:

browser - browser instance given from chrome.open.

url - new URL to set on browser.

Return:

This action gives no return

chrome.open

Creates a new Chrome Web Browser intance to interact with using Marvin.

Parameters:

url - URL that Chrome should open

chrome_path - Path to your chrome.exe file, if your installation is not in one of the default Chrome installation paths: C:\Program Files\Google\Chrome\Application\chrome.exe, C:\Program Files (x86)\Google\Chrome\Application\chrome.exe or C:\Users\<user name>\AppData\Local\Google\Chrome\Application\chrome.exe

Return:

browser - Chrome browser instance to be used for future interactions

chrome.query_selector

Return the first element found for the given selector name.

Parameters:

browser - browser instance given from chrome.open.

selector (optional) - identifier of the element in selector mode (default=None).

inside (optional) - this value define the element object where the selector should be found in (default=all document).

depth (optional) - define the depth (levels) of children elements to return (default=1).

iframe_search (optional) - define if selector should be found in the base document or any documents, even inside iframes. If setted True will search inside all iframes, and if setted False will search only inside the main document (default=True).

Return:

element - element object for the given selector or None if no element were found.

Exceptions:

ElementNotFound: if the given selector don't match to any element in page

chrome.query_selector_all

Return the first element found for the given selector name.

Parameters:

browser - browser instance given from chrome.open.

selector (optional) - identifier of the element in selector mode (default=None).

inside (optional) - this value define the element object where the selector should be found in (default=all document).

depth (optional) - define the depth (levels) of children elements to return (default=1).

iframe_search (optional) - define if selector should be found in the base document or any documents, even inside iframes. If setted True will search inside all iframes, and if setted False will search only inside the main document (default=True).

Return:

elements - list of element objects for the given selector or empty list if no element were found. length - number of found elements

Exceptions:

ElementNotFound: if the given selector don't match to any element in page

chrome.scroll_if_needed

Check for the given element, and scroll the screen if it is necessary to show element.

Parameters:

browser - browser instance given from chrome.open.

selector (optional) - identifier of the element in selector mode (default=None).

element (optional) - element object to change (default=None).

inside (optional) - this value define the element object where the selector should be found in (default=all document).

iframe_search (optional) - define if selector should be found in the base document or any documents, even inside iframes. If setted True will search inside all iframes, and if setted False will search only inside the main document (default=True).

Return:

This action gives no return

Exceptions:

ElementNotFound: if the given selector don't match to any element in page.

chrome.select_tab

Select a specific tab of the browser instance

Parameters:

browser - browser instance given from chrome.open.

tab_name - name/Title of the tab to be selected. Don't need to be the complete tab name, as this action searchs a tab that contains the given name in any part of it's title in a case insensitive way.

timeout - how long (in seconds) this action will wait until the tab_name could be found. This is util when a new tab is created dinamically, which sometimes could have a litle delay (default=10 seconds).

Return:

This action gives no return

Exceptions:

ChromeTabNotFound: if the given tab_name don't match to any tab name/title on browser instance.

chrome.wait_downloads

Stop execution until all in progress downloads finishes.

Parameters:

browser - browser instance given from chrome.open.

timeout (optional) - defines the maximum wait time in seconds to wait until all downloads finishes.

Return:

This action gives no return

Exceptions:

TimeoutException: if element is not visible until timeout is reached

chrome.wait_element

Stop execution until the given element is present in page.

Parameters:

browser - browser instance given from chrome.open.

selector (optional) - identifier of the element in selector mode (default=None).

element (optional) - element object to change (default=None).

inside (optional) - this value define the element object where the selector should be found in (default=all document).

iframe_search (optional) - define if selector should be found in the base document or any documents, even inside iframes. If setted True will search inside all iframes, and if setted False will search only inside the main document (default=True).

timeout (optional) - defines the maximum wait time in seconds to wait until element is present in page (default=30 seconds).

Return:

element - element object for the given selector or None if no element were found.

Exceptions:

TimeoutException: if element is not visible until timeout is reached

chrome.wait_element_hide

Stop execution util the given element is hidden for the user.

Parameters:

browser - browser instance given from chrome.open.

selector (optional) - identifier of the element in selector mode (default=None).

element (optional) - element object to change (default=None).

inside (optional) - this value define the element object where the selector should be found in (default=all document).

iframe_search (optional) - define if selector should be found in the base document or any documents, even inside iframes. If setted True will search inside all iframes, and if setted False will search only inside the main document (default=True).

timeout (optional) - defines the maximum wait time in seconds to wait until element is present in page (default=30 seconds).

Return:

This action gives no return

Exceptions:

TimeoutException: if element is not visible until timeout is reached

ElementNotFound: if the given selector don't match to any element in page

chrome.wait_element_visible

Stop execution until the given element is visible for the user.

Parameters:

browser - browser instance given from chrome.open.

selector (optional) - identifier of the element in selector mode (default=None).

element (optional) - element object to change (default=None).

inside (optional) - this value define the element object where the selector should be found in (default=all document).

iframe_search (optional) - define if selector should be found in the base document or any documents, even inside iframes. If setted True will search inside all iframes, and if setted False will search only inside the main document (default=True).

timeout (optional) - defines the maximum wait time in seconds to wait until element is present in page (default=30 seconds).

Returns:

element - element object for the given selector or None if no element were found.

Exceptions:

TimeoutException: if element is not visible until timeout is reached

ElementNotFound: if the given selector don't match to any element in page

chrome.wait_load

Stop execution until the page is completelly loaded.

This action don't cover the JavaScript load executed in page. If the page you are automating use extensive JavaScript load functions, consider using chrome.wait_element or chrome.wait_element_visible

Parameters:

browser - browser instance given from chrome.open.

timeout (optional) - defines the maximum wait time in seconds to wait until page is loaded (default=60 seconds).

Return:

This action gives no return

Exceptions:

TimeoutException: if element is not visible until timeout is reached

Special Chrome Objects

Some actions on Chrome, uses or returns special objects like Element to hold a complex informations.

Here we gona explain all of them and how to use it.

Element

Returnet by chrome.query_selector holds further information about the selected element.

element.get_text()

Returns the text inside the element if the element has one. This method just return the text right inside the element, don't returning texts from chidren elements.

Returns:

Text inside the element if it has one, or None if there is no text on this element.

element.get_attribute(attribute_name)

Returns the text inside the element if the element has one. This method just return the text right inside the element, don't returning texts from chidren elements.

Parameters:

attribute_name - name/key of the attribute to be returned.

Returns:

The value of the given attribute.

exeucte_js result

After executing a Javascript expression on browser, it will return a object with these keys:

type - Type of the returned object (object, function, undefined, string, number, boolean, symbol, bigint, wasm)

subtype - Subtype of the returned object in case of type be object or wasm (array, null, node, regexp, date, map, set, weakmap, weakset, iterator, generator, error, proxy, promise, typedarray, arraybuffer, dataview, i32, i64, f32, f64, v128, externref)

className - Defined for object type, gives the name of class (constructor) of the object.

value - Value returned for informed type.