spydr package

Submodules

spydr.utils module

spydr.utils.HOWS = {'class': 'class name', 'css': 'css selector', 'id': 'id', 'link_text': 'link text', 'name': 'name', 'partial_link_text': 'partial link text', 'tag_name': 'tag name', 'text': 'xpath', 'xpath': 'xpath', 'yml': 'yml'}

Set of HOW strategies to identify elements.

class spydr.utils.INI(file, default_section='Spydr', encoding='utf-8', interpolation=None)

Bases: object

Access INI key=value using JSON serialization.

Parameters

• file (str) – Ini file

• default_section (str) – Default section name. Defaults to ‘Spydr’.

Keyword Arguments

• encoding (str) – File Encoding. Defaults to ‘utf-8’.

• interpolation – Value interpolation. Can be BasicInterpolation or ExtendedInterpolation. Defaults to None.

property default_section

Default section to get/set key/value.

Returns

str – Default section name

get_key(key, section=None)

Get value from the given key.

Parameters

• key (str) – Key

• section – INI section. Defaults to the default section.

Returns

Value (any data type JSON supports)

save()

Save INI file.

set_key(key, value, section=None)

Set key/value for INI

Parameters

• key (str) – Key

• value – Value (any data type JSON supports)

• section – INI section. Defaults to the default section.

class spydr.utils.Utils

Bases: object

Utilities for Spydr WebDriver

Raises

WebDriverException – Raise an error when how=what can not be parsed

static compact(iterable, function=None, sorting=False, unique=False)

Filter items, by function, in list/set.

Parameters

• iterable (list/set) – Iterable

• function – Function to filter. Defaults to None.

Keyword Arguments

• sorting (bool) – Whether to sort the returned list.

• unique (bool) – Whether to remove duplicates in the returned list

Returns

list – Filtered list

Examples

compact([‘’, ‘a’, ‘’, ‘b’, 0, None, 1]) => [a’, b’, 1]

static date_sorted(dates, reverse=False, format='%m/%d/%Y')

Sort list of date strings.

Parameters

dates (list) – List of date strings

Keyword Arguments

• reverse (bool) – Reverse the sorting. Defaults to False.

• format (str) – Date format. Defaults to ‘%m/%d/%Y’.

Returns

list – Sorted list of date strings

static is_file(file_path)

Wether the file exists.

Parameters

file_path (str) – File Path

Returns

bool – Wether the file exists

static parse_locator(locator)

Parse locator with supported how=what strategies

Parameters

locator (str) – The locator using supported how=what strategies

Raises

WebDriverException – Raise an error when how=what is not supported

Returns

(str, str) – (how, what) strategy

static path_exists(path)

Check if path exists.

Parameters

path (str) – Path

Returns

bool – Whether path exists.

static random_choice(sequence)

Choose a random element from a non-empty sequence.

Parameters

sequence (Sequence[_T]) – Sequence

Returns

_T – A random element in the sequence

static random_sample(population, k)

Return a k length list of unique elements chosen from the population sequence.

Parameters

• population (Sequence[_T]) – Sequence

• k (int) – Length of the returned list

Returns

List[_T] – Returns a new list containing elements from the population

static remove_dir(dir)

Remove the directory.

Parameters

dir (str) – Directory path

static remove_file(file)

Remove the file.

Parameters

file (str) – File path

static same_set(string_1, string_2, sep=',?\\s+')

Check if string_1 and string_2 are the same set after being split by sep.

Parameters

• string_1 (str) – String 1

• string_2 (str) – String 2

• sep (regexp, optional) – Regex separator. Defaults to r’,?s+’.

Returns

bool – Whether string_1 and string_2 are the same

Examples

same_set(‘Bruce Lee’, ‘Lee, Bruce’) => True

same_set(‘Bruce Lee’, ‘Lee Bruce’) => True

static sanitize(text)

Sanitize text to be safe for file names.

Parameters

text (str) – text to sanitize

Returns

str – sanitized text

static strip_multi_spaces(words)

Strip multiple spaces between words to be single-spaced.

Parameters

words (srt) – Words

Returns

str – Single-spaced words

static strptime(date, format='%m/%d/%Y')

Parse date string to datetime.datetime object

Parameters

• date (str) – Date string

• format (str, optional) – Date format. Defaults to r’%m/%d/%Y’.

Returns

datetime.datetime/None – Return datetime.datetime or None if failed to parse date string.

static to_abspath(path, suffix='.png', root=os.getcwd(), mkdir=True, isdir=False)

Resolve file to absolute path and create all directories if missing.

Parameters

path (str) – Path

Keyword Arguments

• suffix (str) – File suffix. Defaults to None.

• root (str) – Root directory. Defaults to os.getcwd().

• mkdir (bool) – Create directores in the path. Defaults to True.

• isdir (bool) – Whether path is a directory. Defaults to False.

Returns

str – Absolute path

static true(obj)

Evaluate object(int/float/str) to Boolean

Parameters

obj (int/float/str) – Object to evaluate

Returns

bool – Whether Object is evaluated to True

class spydr.utils.YML(file)

Bases: object

Access YAML configuration file using dot notation.

Parameters

file (str/bytes/os.PathLike) – YAML file

property dict

YAML dict.

Returns

dict – YAML dict

t(key, **kwargs)

Get value from YAML file by using “dot notation” key.

Examples

# YAML

today:

dashboard:

search: ‘#search’

name: ‘Name is {name}’

t(‘today.dashboard.search’) => ‘#search’

t(‘today.dashboard.name’, name=’Spydr’) => ‘Name is Spydr’

Parameters

key (str) – Dot notation key

Keyword Arguments

**kwargs – Format key value (str) with str.format(**kwargs).

Returns

value of dot notation key

spydr.webdriver module

class spydr.webdriver.Spydr(auth_username=None, auth_password=None, browser='chrome', drivers_root=os.getcwd(), headless=False, ini=None, locale='en', log_indent=2, log_level=None, screen_root='./screens', timeout=30, whitelist=None, window_size='1280,720', yml=None)

Bases: object

Spydr WebDriver

Keyword Arguments

• auth_username (str) – Username for HTTP Basic/Digest Auth. Defaults to None.

• auth_password (str) – Password for HTTP Basic/Digest Auth. Defaults to None.

• browser (str) – Browser to drive. Defaults to ‘chrome’. Supported browsers: ‘chrome’, ‘edge’, ‘firefox’, ‘ie’, ‘safari’.

• drivers_root (str) – Where to download webdrivers. Defaults to os.getcwd().

• headless (bool) – Headless mode. Defaults to False.

• ini (str/INI) – INI File. Defaults to None.

• locale (str) – Browser locale. Defaults to ‘en’.

• log_indent (int) – Indentation for logging messages. Defaults to 2.

• log_level (str) – Logging level: ‘INFO’ or ‘DEBUG’. Defaults to None. When set to ‘INFO’, info() messages will be shown. When set to ‘DEBUG’, debug(), info() and called methods will be shown.

• screen_root (str) – The directory of saved screenshots. Defaults to ‘./screens’.

• timeout (int) – Timeout for implicitly_wait, page_load_timeout, and script_timeout. Defaults to 30.

• whitelist (str) – URLs to whitelist (only Chrome/Firefox). An example of whitelist is ‘google.com, apple.com’. Defaults to None.

• window_size (str) – The size of the window when headless. Defaults to ‘1280,720’.

• yml (str/bytes/os.PathLike/YML) – YAML File. Defaults to None.

Raises

• InvalidSelectorException – Raise an error when locator is invalid

• NoSuchElementException – Raise an error when no element is found

• WebDriverException – Raise an error when Spydr encounters an error

Returns

Spydr – An instance of Spydr Webdriver

abspath(path, suffix='.png', root=os.getcwd(), mkdir=True, isdir=False)

Resolve file to absolute path and create all directories if missing.

Parameters

path (str) – Path

Keyword Arguments

• suffix (str) – File suffix. Defaults to None.

• root (str) – Root directory. Defaults to os.getcwd().

• mkdir (bool) – Create directores in the path. Defaults to True.

• isdir (bool) – Whether path is a directory. Defaults to False.

Returns

str – Absolute path

actions()

Initialize an ActionChains.

Returns

ActionChains – An instance of ActionChains

add_class(locator, class_name)

Add the given CSS class to the element.

Parameters

• locator (str/WebElement) – The locator to identify the element or WebElement

• class_name (str) – CSS class name

add_cookie(cookie)

Add a cookie to your current session.

Parameters

cookie (dict) – A dictionary object. Required keys are “name” and “value”, and “value” must be string. Optional keys are “path”, “domain”, “secure”, and “expiry”.

Usage:

spydr.add_cookie({‘name’: ‘foo’, ‘value’: ‘bar’})

alert_accept(alert=None)

Accept the alert available.

Keyword Arguments

alert (Alert) – Alert instance. Defaults to None.

alert_dismiss(alert=None)

Dismiss the alert available.

Keyword Arguments

alert (Alert) – Alert instance. Defaults to None.

alert_sendkeys(keys_to_send, alert=None, accept=True)

Send keys to the alert available and accept it.

Parameters

keys_to_send (str) – Text to send

Keyword Arguments

• alert (Alert) – Alert instance. Defaults to None.

• accept (bool) – Whether to accept the alert after sending keys.

alert_text(alert=None, dismiss=True)

Get the text of the alert available and dismiss it.

Keyword Arguments

• alert (Alert) – Alert Instance. Defaults to None.

• dismiss (bool) – Whether to dismiss the alert.

back()

Goes one step backward in the browser history

blank()

Open a blank page.

blur(locator)

Trigger blur event on the element.

Parameters

locator (str/WebElement) – The locator to identify the element or WebElement

checkbox_to_be(locator, is_checked)

Set the checkbox, identified by the locator, to the given state (is_checked).

Parameters

• locator (str/WebElement) – The locator to identify the checkbox or WebElement

• is_checked (bool) – whether the checkbox is to be checked

Raises

• InvalidSelectorException – Raise an error when the element is not a checkbox

• WebDriverException – Raise an error when failing to set the given state

checkboxes_to_be(locator, is_checked, on_values=None)

Set all checkboxes, identified by the locator, to the given state (is_checked).

Parameters

• locator (str) – The locator to identify all the checkboxes

• is_checked (bool) – whether the checkboxes are to be checked

Keyword Arguments

on_values (list/tuple) – When given, only checkboxes with values in the list are set to is_checked while others are set to not is_checked. Defaults to None.

children(locator)

Get the children elements of the given element.

Parameters

locator (str/WebElement) – The locator to identify the element or WebElement

Returns

list[WebElement] – The children elements of the given element.

clear(locator)

Clear the text of a text input element.

Parameters

locator (str/WebElement) – The locator to identify the element or WebElement

clear_and_send_keys(locator, *keys, blur=False, wait_until_enabled=False)

Clear the element first and then send the given keys.

Parameters

• locator (str/WebElement) – The locator to identify the element or WebElement

• *keys – Any combinations of strings

Keyword Arguments

• blur (bool) – Lose focus after sending keys. Defaults to False.

• wait_until_enabled (bool) – Whether to wait until the element is_enabled() before clearing and sending keys. Defaults to False.

clear_drawings()

Clear all drawings made by Spydr.

clear_local_storage()

Clear localStorage.

clear_session_storage()

Clear sessionStorage.

click(locator, switch_to_new_target=False, scroll_into_view=False, behavior='auto')

Click the element.

Parameters

locator (str/WebElement) – The locator to identify the element or WebElement

Keyword Arguments

• switch_to_new_target (bool) – Whether to switch to a newly-opened window after clicking. Defaults to False.

• scroll_into_view (bool) – Whether to scroll the element into view before clicking. Defaults to False.

• behavior (str) – Defines the transition animation for scroll_into_view. One of auto or smooth. Defaults to ‘auto’.

Returns

tuple, optional – If switch_to_new_target, it returns a tuple of (window_handle_before_clicking, window_handle_after_clicking)

click_with_offset(locator, x_offset=1, y_offset=1)

Click the element from x and y offsets.

Parameters

locator (str/WebElement) – The locator to identify the element or WebElement

Keyword Arguments

• x_offset (int) – X offset from the left of the element. Defaults to 1.

• y_offset (int) – Y offset from the top of the element. Defaults to 1.

close()

Close the window.

close_all_others()

Close all other windows.

closest(locator, parent_locator)

Traverse the element, by locator, and its parents until it finds an element, by parent locator, that matches. Will return itself or the matching ancestor. (IE not supported)

Parameters

• locator (str/WebElement) – The locator to identify the element or WebElement

• parent_locator (str) – Parent locator

Returns

WebElement – WebElement

copy_and_paste(locator, text)

Copy text to clipboard and paste it (send_keys) to the element. (Chrome only)

Parameters

• locator (str/WebElement) – The locator to identify the element or WebElement

• text (str) – Text to paste

copy_to_clipboard(text)

Copy text to clipboard. (Chrome only)

Parameters

text (str) – Text to paste

css_property(locator, name)

The value of CSS property.

Parameters

• locator (str/WebElement) – The locator to identify the element or WebElement

• name (str) – CSS property name

Returns

str – CSS property value

ctrl_click(locator)

Ctrl-click the element.

Parameters

locator (str/WebElement) – The locator to identify the element or WebElement

property current_url

Get the URL of the current page.

Returns

str – URL of the page

date_sorted(dates, reverse=False, format='%m/%d/%Y')

Sort list of date strings.

Parameters

dates (list) – List of date strings

Keyword Arguments

• reverse (bool) – Reverse the sorting. Defaults to False.

• format (str) – Date format. Defaults to ‘%m/%d/%Y’.

Returns

list – Sorted list of date strings

debug(message)

Log DEBUG messages.

Parameters

message (str) – DEBUG message

delete_all_cookies()

Delete all cookies in the scope of the session.

delete_cookie(name)

Delete a cookie with the given name.

Parameters

name (str) – Name of the cookie

property desired_capabilities

Get driver’s current desired capabilities.

Returns

dict – A dictionary object of the current capabilities

double_click(locator)

Double-click the element.

Parameters

locator (str/WebElement) – The locator to identify the element or WebElement

double_click_with_offset(locator, x_offset=1, y_offset=1)

Double-click the element from x and y offsets.

Parameters

locator (str/WebElement) – The locator to identify the element or WebElement

Keyword Arguments

• x_offset (int) – X offset from the left of the element. Defaults to 1.

• y_offset (int) – Y offset from the top of the element. Defaults to 1.

drag_and_drop(source_locator, target_locator)

Hold down the left mouse button on the source element, then move to the target element and releases the mouse button.

Parameters

• source_locator (str/WebElement) – The element to mouse down

• target_locator (str/WebElement) – The element to mouse up

drag_and_drop_by_offset(source_locator, x_offset, y_offset)

Hold down the left mouse button on the source element, then move to the target offset and releases the mouse button.

Parameters

source_locator (str/WebElement) – The element to mouse down

Keyword Arguments

• x_offset (int) – X offset to move to

• y_offset (int) – Y offset to move to

draw_rectangle(locator, color='#f33', top=4, right=8, bottom=4, left=8)

Draw(Append) a bordered DIV around the given element.

Parameters

locator (str/WebElement) – The locator to identify the element or WebElement

Keyword Arguments

• color (str) – The color of the bordered DIV. Defaults to ‘#f33’.

• top (int) – padding-top of the bordered DIV. Defaults to 4.

• right (int) – padding-right of the bordered DIV. Defaults to 8.

• bottom (int) – padding-bottom of the bordered DIV. Defaults to 4.

• left (int) – padding-left of the bordered DIV. Defaults to 8.

Returns

[type] – [description]

draw_text(locator, text, color='#f33', font_size=16, top=5, right=20)

Draw(Append) a text DIV element to the given element, by locator.

Parameters

• locator (str/WebElement) – The locator to identify the element or WebElement

• text (str) – Text

Keyword Arguments

• color (str) – The color of the text. Defaults to ‘#f33’.

• font_size (int) – The font size of the text. Defaults to 16.

• top (int) – CSS style of top. Defaults to 5.

• right (int) – CSS style of right. Defaults to 20.

Returns

WebElement – The text DIV element

property driver

Instance of Selenium WebDriver.

Returns

WebDriver – Instance of Selenium WebDriver

execute_async_script(script, *args)

Asynchronously execute JavaScript in the current window or frame.

Parameters

• script (str) – JavaScript to execute

• *args – Any applicable arguments for JavaScript

Returns

Any applicable return from JavaScript

execute_cdp_cmd(cmd, cmd_args={})

Execute Chrome Devtools Protocol command and get returned result.

cmd and cmd_args should follow Chrome DevTools Protocol. Refer to: https://chromedevtools.github.io/devtools-protocol/

Parameters

• cmd (str) – Command name

• cmd_args (dict) – Command arguments. Defaults to {}.

Returns

dict – A dict, empty dict {} if there is no result to return.

execute_script(script, *args)

Synchronously execute JavaScript in the current window or frame.

Parameters

• script (str) – JavaScript to execute

• *args – Any applicable arguments for JavaScript

Returns

Any applicable return from JavaScript

explicitly_run(seconds, method, *args, **kwargs)

Explicitly run the given method for the given seconds.

Parameters

• seconds (int) – Seconds to run before timing out

• method (callable) – Method to call

• *args – Any applicable arguments

• *kwargs – Any applicable keyword arguments

Returns

Return the result of the given method.

find_element(locator)

Find the element by the given locator.

Parameters

locator (str/WebElement) – The locator to identify the element or WebElement

Raises

NoSuchElementException – Raise an error when no element found

Returns

WebElement – The element found

find_elements(locator)

Find all elements by the given locator.

Parameters

locator (str) – The locator to identify the elements or list[WebElement]

Returns

list[WebElement] – All elements found

first_child(locator)

Get the first child element of the given element.

Parameters

locator (str/WebElement) – The locator to identify the element or WebElement

Returns

WebElement – The first child element of the given element.

focus(locator)

Trigger focus event on the element.

Parameters

locator (str/WebElement) – The locator to identify the element or WebElement

forward()

Goes one step forward in the browser history.

fullscreen_window()

Invokes the window manager-specific ‘full screen’ operation.

get_attribute(locator, name)

Get the given attribute or property of the element.

Parameters

• locator (str/WebElement) – The locator to identify the element or WebElement

• name (str) – Attribute name

Returns

bool/str/None – The attribute value

get_cookie(name)

Get the cookie by name.

Parameters

name (str) – The name of the cookie

Returns

dict/None – Return the cookie or None if not found.

get_cookies()

Get the cookies visible in the current session.

Returns

list[dict] – Return cookies in a set of dictionaries

get_ini_key(key, section=None)

Get value of the given key from INI.

Parameters

• key (str) – Key name

• section – INI section. Defaults to the default section.

Returns

Value (any data type JSON supports)

get_local_storage_item(name)

Get item’s value from localStorage.

Parameters

name (str) – Item name in localStorage

Returns

Item’s value from localStorage. (Deserialized with json.loads)

get_property(locator, name)

Get the given property of the element.

Parameters

• locator (str/WebElement) – The locator to identify the element or WebElement

• name (str) – Property name

Returns

bool/dict/int/list/str/None – The property value

get_screenshot_as_base64()

Get a screenshot of the current window as a base64 encoded string.

Returns

str – Base64 encoded string of the screenshot

get_screenshot_as_file(filename)

Save a screenshot of the current window to filename (PNG).

Default directory for saved screenshots is defined in: screen_root.

Parameters

filename (str) – Filename of the screenshot

Returns

bool – Whether the file is saved

get_screenshot_as_png()

Get a screenshot of the current window as a binary data.

Returns

bytes – Binary data of the screenshot

get_session_storage_item(name)

Get item’s value from sessionStorage.

Parameters

name (str) – Item name in sessionStorage

Returns

Item’s value from sessionStorage. (Deserialized with json.loads)

get_window_position(window_handle='current')

Get the x and y position of the given window.

Keyword Arguments

window_handle (str) – The handle of the window. Defaults to ‘current’.

Returns

dict – The position of the window as dict: {‘x’: 0, ‘y’: 0}

get_window_rect()

Get the x, y, height, and width of the current window.

Returns

dict – The position, height, and width as dict: {‘x’: 0, ‘y’: 0, ‘width’: 100, ‘height’: 100}

get_window_size(window_handle='current')

Get the width and height of the given window.

Keyword Arguments

window_handle (str) – The handle of the window. Defaults to ‘current’.

Returns

dict – The height and width of the window as dict: {‘width’: 100, ‘height’: 100}

has_attribute(locator, attribute)

Check if the element has the given attribute.

Parameters

• locator (str/WebElement) – The locator to identify the element or WebElement

• attribute (str) – Attribute name

Returns

bool – Whether the attribute exists

has_attribute_value(locator, attribute, value)

Check if the element’s attribute contains the given value.

Parameters

• locator (str/WebElement) – The locator to identify the element or WebElement

• attribute (str) – Attribute name

• value (bool/str) – value to check

Returns

bool – Whether value is found in the element’s attribute

has_class(locator, class_name)

Check if the element has the given CSS class.

Parameters

• locator (str/WebElement) – The locator to identify the element or WebElement

• class_name (str) – CSS class name

Returns

bool – Whether the CSS class exists

has_local_storage()

Check access to localStorage.

Returns

bool – Whether has access to localStorage or not

has_session_storage()

Check access to sessionStorage.

Returns

bool – Whether has access to sessionStorage or not

has_text(locator, text)

Check if the element contains the given text.

Parameters

• locator (str/WebElement) – The locator to identify the element or WebElement

• text (str) – Text to check

Returns

bool – Whether the element has the given text

hide(locator)

Hide the element.

highlight(locator, hex_color='#ff3')

Highlight the element with the given color.

Parameters

• locator (str/WebElement) – The locator to identify the element or WebElement

• hex_color (str, optional) – Hex color. Defaults to ‘#ff3’.

property implicitly_wait

Timeout for implicitly wait.

Returns

int – The timeout of implicitly wait

info(message)

Log INFO messages.

Parameters

message (str) – INFO Message

property ini

INI file as an INI instance.

Returns

INI – INI instance

is_displayed(locator, seconds=None)

Check if the element is displayed.

Parameters

locator (str/WebElement) – The locator to identify the element or WebElement

Keyword Arguments

seconds (int) – Seconds to wait until giving up. Defaults to self.implicitly_wait.

Returns

bool – Whether the element is displayed

is_enabled(locator)

Check if the element is enabled.

Parameters

locator (str/WebElement) – The locator to identify the element or WebElement

Returns

bool – Whether the element is enabled

is_file(file_path)

Whether the file exists.

Parameters

file_path (str) – File Path

Returns

bool – Whether the file exists

is_located(locator, seconds=None)

Check if the element is located in the given seconds.

Parameters

locator (str) – The locator to identify the element

Keyword Arguments

seconds (int) – Seconds to wait until giving up. Defaults to self.implicitly_wait.

Returns

False/WebElement – Return False if not located. Return WebElement if located.

is_page_loaded()

Check if document.readyState is complete.

Returns

bool – Whether the page is loaded

is_selected(locator)

Check if the element is selected.

Can be used to check if a checkbox or radio button is selected.

Parameters

locator (str/WebElement) – The locator to identify the element or WebElement

Returns

bool – Whether the element is selected

is_text_matched(locator, text)

Whether the given text matches the element’s text.

Parameters

• locator (str/WebElement) – The locator to identify the element or WebElement

• text (str) – Text to match

Returns

bool – Whether the given text matches the element’s text

js_click(locator)

Call HTMLElement.click() using JavaScript.

Parameters

locator (str/WebElement) – The locator to identify the element or WebElement

js_send_keys(locator, text)

Send text to the element using JavaScript.

Parameters

• locator (str/WebElement) – The locator to identify the element or WebElement

• text (str) – Text to send

keys

alias of selenium.webdriver.common.keys.Keys

last_child(locator)

Get the last child element of the given element.

Parameters

locator (str/WebElement) – The locator to identify the element or WebElement

Returns

WebElement – The last child element of the element element.

load_cookies(filename)

Load Cookies from a JSON file.

Parameters

filename (str) – File name

Examples

# cookies.json file

[

{ “name”: “name1”, “value”: “true” },

{ “name”: “name2”, “value”: “false” },

]

load_local_storage(filename)

Load JSON file to localStorage.

Parameters

filename (str) – File name

Examples

# local_storage.json file

{

“name1”: “true”,

“name2”: “false”

}

load_session_storage(filename)

Load JSON file to sessionStorage.

Parameters

filename (str) – File name

Examples

# session_storage.json file

{

“name1”: “true”,

“name2”: “false”

}

location(locator)

The location of the element in the renderable canvas.

Parameters

locator (str/WebElement) – The locator to identify the element or WebElement

Returns

dict – The location of the element as dict: {‘x’: 0, ‘y’: 0}

maximize_to_screen()

Maximize the current window to match the screen size.

maximize_window()

Maximize the current window.

minimize_window()

Minimize the current window.

move_by_offset(x_offset, y_offset)

Moving the mouse to an offset from current mouse position.

Keyword Arguments

• x_offset (int) – X offset

• y_offset (int) – Y offset

move_to_element(locator)

Moving the mouse to the middle of the element.

Parameters

locator (str/WebElement) – The locator to identify the element or WebElement

move_to_element_with_offset(locator, x_offset=1, y_offset=1)

Move the mouse by an offset of the specified element. Offsets are relative to the top-left corner of the element.

Parameters

locator (str/WebElement) – The locator to identify the element or WebElement

Keyword Arguments

• x_offset (int) – X offset. Defaults to 1.

• y_offset (int) – Y offset. Defaults to 1.

new_tab()

Open a new tab.

Returns

str – Window handle of the new tab

new_window(name)

Open a new window.

Parameters

name (str) – Name of the window

Returns

str – Window handle of the new window

next_element(locator)

Get the next element of the given element.

Parameters

locator (str/WebElement) – The locator to identify the element or WebElement

Returns

WebElement – The next element of the given element.

open(url, new_tab=False)

Load the web page by its given URL.

Parameters

url (str) – URL of the web page

Keyword Arguments

new_tab (bool) – Whether to open in a new tab. Defaults to False.

Returns

list[str] – List of [current_window_handle, new_tab_window_handle]

open_data_as_url(data, mediatype='text/html', encoding='utf-8')

Use Data URL to open data as inline document.

Parameters

data (str) – Data to be open as inline document

Keyword Arguments

• mediatype (str) – MIME type. Defaults to ‘text/html’.

• encoding (str) – Data encoding. Defaults to ‘utf-8’.

open_file(filename)

Open file with the browser.

Parameters

filename (str) – File name

Raises

WebDriverException – Raise an error when filename is not found

open_file_as_url(filename, mediatype='text/html', encoding='utf-8')

Use Data URL to open file content as inline document.

Parameters

filename (str) – File name

Keyword Arguments

• mediatype (str) – MIME type. Defaults to ‘text/html’.

• encoding (str) – File encoding. Defaults to ‘utf-8’.

Raises

WebDriverException – Raise an error when filename is not found

open_with_auth(url, username=None, password=None)

Load the web page by adding username and password to the URL

Parameters

url (str) – URL of the web page

Keyword Arguments

• username (str) – Username. Defaults to auth_username or None.

• password (str) – Password. Defaults to auth_password or None.

property page_load_timeout

Timeout for page load

Returns

int – Page load timeout

property page_source

Get the source of the current page.

Returns

str – The source of the current page

parent_element(locator)

Get the parent element of the given element.

Parameters

locator (str/WebElement) – The locator to identify the element or WebElement

Returns

WebElement – The parent element of the given element.

paste_from_clipboard(locator)

Paste clipboard (send_keys) to the given element. (Chrome only)

Parameters

locator (str/WebElement) – The locator to identify the element or WebElement

path_exists(path)

Check if path exists.

Parameters

path (str) – Path

Returns

bool – Whether path exists.

previous_element(locator)

Get the previous element of the given element.

Parameters

locator (str/WebElement) – The locator to identify the element or WebElement

Returns

WebElement – The previous element of the given element.

quit()

Quit the Spydr webdriver.

radio_to_be(locator, is_checked)

Set the radio button, identified by the locator, to the given state (is_checked).

Parameters

• locator (str/WebElement) – The locator to identify the radio button or WebElement

• is_checked (bool) – whether the radio button is to be checked

Raises

• InvalidSelectorException – Raise an error when the element is not a radio button

• WebDriverException – Raise an error when failing to set the given state

randomized_string(size=10, sequence='abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ', digits=True, punctuation=False, whitespace=False, is_upper=False)

Generate a randomized string in the given size using the given characters.

Parameters

size (int, optional) – Size of the string. Defaults to 10.

Keyword Arguments

• sequence (str) – Sequence. Defaults to string.ascii_letters.

• digits (bool) – Add string.digits to sequence.

• punctuation (bool) – Add string.punctuation to sequence.

• whitespace (bool) – Add whitespace to sequence.

• is_upper (bool) – Uppercase the randomized string. Defaults to False.

Returns

[type] – [description]

rect(locator)

Get the size and location of the element.

Parameters

locator (str/WebElement) – The locator to identify the element or WebElement

Returns

dict – The size and location of the element as dict: {‘x’: 0, ‘y’: 0, ‘width’: 100, ‘height’: 100}

refresh()

Refresh the current page.

refresh_until_page_changed(frequency=2, timeout=10, body_text_diff=True)

Refresh the page (every frequency) until the page changes or until timeout.

Keyword Arguments

• frequency (int) – Refresh frequency

• timeout (int) – Time allowed to refresh. Defaults to 10.

• body_text_diff (bool) – Compare body text when True. Compare page_source when False.

Returns

bool – Whether the page is changed

remove_attribute(locator, attribute)

Remove the given attribute from the element.

Parameters

• locator (str/WebElement) – The locator to identify the element or WebElement

• attribute (str) – Attribute name

remove_class(locator, class_name)

Remove the given CSS class to the element.

Parameters

• locator (str/WebElement) – The locator to identify the element or WebElement

• class_name (str) – CSS class name

remove_dir(dir)

Remove the directory.

Parameters

dir (str) – Directory path

remove_file(file)

Remove the file.

Parameters

file (str) – File path

right_click(locator)

Right-click on the element.

Parameters

locator (str/WebElement) – The locator to identify the element or WebElement

right_click_with_offset(locator, x_offset=1, y_offset=1)

Right-click on the element with x and y offsets.

Parameters

locator (str/WebElement) – The locator to identify the element or WebElement

Keyword Arguments

• x_offset (int) – X offset from the left of the element. Defaults to 1.

• y_offset (int) – Y offset from the top of the element. Defaults to 1.

save_cookies(filename)

Save cookies as a JSON file.

Parameters

filename (str) – File name

save_ini()

Save INI file.

save_screenshot(filename)

Save a screenshot of the current window to filename (PNG).

Default directory for saved screenshots is defined in: screen_root.

Parameters

filename (str) – Filename of the screenshot

Returns

bool – Whether the file is saved

screenshot(locator, filename)

Save a screenshot of the element to the filename (PNG).

Parameters

• locator (str/WebElement) – The locator to identify the element or WebElement

• filename ([type]) – Filename of the screenshot

Returns

bool – Whether the file is saved

screenshot_as_base64(locator)

Get the screenshot of the element as a Base64 encoded string

Parameters

locator (str/WebElement) – The locator to identify the element or WebElement

Returns

str – Base64 encoded string of the screenshot

screenshot_as_png(locator)

Get the screenshot of the element as a binary data.

Parameters

locator (str/WebElement) – The locator to identify the element or WebElement

Returns

bytes – Binary data of the screenshot

property script_timeout

Timeout for script.

Returns

int – Script timeout

scroll_into_view(locator, behavior='auto', block='start', inline='nearest')

Scroll the element’s parent to be displayed.

Parameters

locator (str/WebElement) – The locator to identify the element or WebElement

Keyword Arguments

• behavior (str) – Defines the transition animation. One of auto or smooth. Defaults to ‘auto’.

• block (str) – Defines vertical alignment. One of start, center, end, or nearest. Defaults to ‘start’.

• inline (str) – Defines horizontal alignment. One of start, center, end, or nearest. Defaults to ‘nearest’.

scroll_to(locator, x, y)

Scroll the element to the given x- and y-coordinates. (IE not supported)

Parameters

• locator (str/WebElement) – The locator to identify the element or WebElement

• x (int) – x-coordinate

• y (int) – y-coordinate

select_options(select_locator, filter_by='value', filter_value=None)

Get options of an select element. Filter the options by attribute if filter_value is given.

Parameters

select_locator (str/WebElement) – The locator to identify the element or WebElement

Keyword Arguments

• filter_by (str) – Filter options by attribute. Defaults to ‘value’.

• filter_value (str) – Filter option’s attribute by value. Defaults to None.

Returns

list[WebElement] – All filtered options

select_to_be(select_locator, option_value, selected=True, option_by='value')

Set selected state of the given option in the select drop-down menu.

Parameters

• select_locator (str/WebElement) – The locator to identify the element or WebElement

• option_value (int/str) – The value to identify the option by using option_by method.

Keyword Arguments

• selected (bool) – Option selected state to be

• option_by (str) – The method to identify the options. One of value, text, index, or ‘attribute_name’. Defaults to ‘value’.

Raises

InvalidSelectorException – Raise an error when the element is not a select

Examples

# Deselect option: <option value=”3”>Three</option>

select_to_be(‘#group’, 3, selected=False)

# Select option: <option value=”5”>Volvo</option>

select_to_be(‘#car’, ‘Volvo’, option_by=’text’)

# Select option: <option id=”18”>Peyton Manning</option>

select_to_be(‘#qb’, 18, option_by=’id’)

select_to_be_all(select_locator)

Select all option in a multiple select drop-down menu.

Parameters

select_locator (str/WebElement) – The locator to identify the element or WebElement

select_to_be_none(select_locator)

De-select all option in a multiple select drop-down menu.

Parameters

select_locator (str/WebElement) – The locator to identify the element or WebElement

select_to_be_random(select_locator, ignored_options=[None, '', '0'])

Randomly select an option in the select menu

Parameters

select_locator (str/WebElement) – The locator to identify the element or WebElement

Keyword Arguments

ignored_options (list) – Options to exclude from selection. Defaults to [None, “”, “0”].

Raises

WebDriverException – Raise an error if failing to randomly select an option

select_to_be_some(select_locator, option_values, selected=True, option_by='value')

Set selected state on the given options, by option_values, in a multiple select element.

Parameters

• select_locator (str/WebElement) – The locator to identify the element or WebElement

• option_values (list) – The list of values to identify the options by using option_by method.

Keyword Arguments

• selected (bool) – Option selected state to be

• option_by (str) – The method to identify the options. One of value, text, index, or ‘attribute_name’. Defaults to ‘value’.

Raises

• InvalidSelectorException – Raise an error when the element is not a select

• WebDriverException – Raise an error if select_locator is not multiple

• WebDriverException – Raise an error if option_values is not a list

selected_options(select_locator, by='value')

Get values of selected option in a select drop-down menu.

Parameters

select_locator (str/WebElement) – The locator to identify the element or WebElement

Keyword Arguments

by (str) – Get selected options by value, text, or index. Defaults to ‘value’.

Raises

• InvalidSelectorException – Raise an error when element is not a select element

• WebDriverException – Raise an error when the given by is unsupported

Returns

list[int/str] – list of values of all selected options

send_keys(locator, *keys, blur=False, wait_until_enabled=False)

Simulate typing into the element.

Parameters

• locator (str/WebElement) – The locator to identify the element or WebElement

• *keys – Any combinations of strings

Keyword Arguments

• blur (bool) – Lose focus after sending keys. Defaults to False.

• wait_until_enabled (bool) – Whether to wait until the element is_enabled() before sending keys. Defaults to False.

set_attribute(locator, attribute, value)

Set the given value to the attribute of the element.

Parameters

• locator (str/WebElement) – The locator to identify the element or WebElement

• attribute (str) – Attribute name

• value (str) – Attribute name

set_download_dir(download_dir)

Set Download directory (Chrome only)

Parameters

download_dir (str) – Download directory

set_ini_key(key, value, section=None)

Set the value of the given key in INI.

Parameters

• key (str) – Key name

• value – Value (any data type JSON supports)

• section – INI section. Defaults to the default section.

set_local_storage_item(name, value)

Set Item and its value to localStorage.

Parameters

• name (str) – Item name in localStorage

• value (str) – Item’s value. Non-string value is auto serialized with json.dumps.

set_session_storage_item(name, value)

Set Item and its value to sessionStorage.

Parameters

• name (str) – Item name in sessionStorage

• value (str) – Item’s value. Non-string value is auto-serialized with json.dumps.

set_window_position(x, y, window_handle='current')

Set the x and y position of the current window

Parameters

• x (int) – x-coordinate in pixels

• y (int) – y-coordinate in pixels

Keyword Arguments

window_handle (str) – Window handle. Defaults to ‘current’.

Returns

dict – Window rect as dict: {‘x’: 0, ‘y’: 0, ‘width’: 100, ‘height’: 100}

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

Set the x, y, width, and height of the current window.

Keyword Arguments

• x (int) – x-coordinate in pixels. Defaults to None.

• y (int) – y-coordinate in pixels. Defaults to None.

• width (int) – Window width in pixels. Defaults to None.

• height (int) – Window height in pixels. Defaults to None.

Returns

dict – Window rect as dict: {‘x’: 0, ‘y’: 0, ‘width’: 100, ‘height’: 100}

set_window_size(width, height, window_handle='current')

Set the width and height of the current window.

Parameters

• width (int, optional) – Window width in pixels. Defaults to None.

• height (int, optional) – Window height in pixels. Defaults to None.

Keyword Arguments

window_handle (str) – Window handle. Defaults to ‘current’.

Returns

dict – Window rect as dict: {‘x’: 0, ‘y’: 0, ‘width’: 100, ‘height’: 100}

shift_click_from_and_to(from_locator, to_locator)

Shift click from from_locator to to_locator.

Parameters

• from_locator (str/WebElement) – The locator to identify the element or WebElement

• to_locator (str/WebElement) – The locator to identify the element or WebElement

show(locator)

Show the element.

Parameters

locator (str/WebElement) – The locator to identify the element or WebElement

size(locator)

The size of the element.

Parameters

locator (str/WebElement) – The locator to identify the element or WebElement

Returns

dict – The size of the element as dict: {‘width’: 100, ‘height’: 100}

sleep(seconds)

Sleep the given seconds.

Parameters

seconds (int) – Seconds to sleep

strptime(date_string, format='%m/%d/%Y %H:%M:%S', timezone=None)

Parse date string to a datetime object.

Parameters

date_string (str) – Date string.

Keyword Arguments

• format (str, optional) – Date format. Defaults to r’%m/%d/%Y %H:%M:%S’.

• timezone (str) – Timezone name, such as ‘Asia/Taipei’. Name is handled by dateutil.tz.gettz(). Defaults to None.

Returns

datetime – datetime

submit(locator)

Submit a form.

Parameters

locator (str/WebElement) – The locator to identify the element or WebElement

switch_to_active_element()

Switch to active element.

Returns

WebElement – Active Element

switch_to_alert()

Switch to alert.

Returns

Alert – Alert

switch_to_default_content()

Switch to default content.

switch_to_frame(frame_locator)

Switch to frame.

Parameters

frame_locator (str/WebElement) – The locator to identify the frame or WebElement

switch_to_frame_and_wait_until_element_located_in_frame(frame_locator, element_locator)

Switch to the given frame and wait until the element is located within the frame.

Parameters

• frame_locator (str/WebElement) – The locator to identify the frame or WebElement

• element_locator (str) – The locator to identify the element

Returns

False/WebElement – Return False if not located. Return WebElement if located.

switch_to_last_window_handle()

Switch to the last opened tab or window.

switch_to_parent_frame()

Switch to parent frame.

switch_to_window(window_name)

Switch to window.

Parameters

window_name (str) – Window name

t(key, **kwargs)

Get value from YML instance by using “dot notation” key.

Parameters

key (str) – Dot notation key

Keyword Arguments

**kwargs – Format key value (str) with str.format(**kwargs).

Returns

value of dot notation key

Examples

# YAML

today:

dashboard:

search: ‘#search’

name: ‘Name is {name}’

t(‘today.dashboard.search’) # ‘#search’

t(‘today.dashboard.name’, name=’Spydr’) # ‘Name is Spydr’

tag_name(locator)

Get the element’s tagName.

Parameters

locator (str/WebElement) – The locator to identify the element or WebElement

Returns

str – tagName

text(locator, typecast=<class 'str'>)

The the element’s text. (Only works when the element is in the viewport)

Parameters

locator (str/WebElement) – The locator to identify the element or WebElement

Keyword Arguments

typecast – Typecast the text. Defaults to str.

Returns

The text, by typecast, of the element

text_content(locator, strip=True)

Get the element’s text. (Works whether the element is in the viewport or not)

Parameters

locator (str/WebElement) – The locator to identify the element or WebElement

Keyword Arguments

strip (bool) – Whether to strip textContent. Defaults to True.

Returns

str – The text of the element

text_to_file(text, filename, suffix)

Write text to the given filename

Parameters

• text (str) – Text to write

• filename (str) – filename of the text file

• suffix (str) – suffix of the text file

Returns

str – Absolute path of the file

texts(locator, typecast=<class 'str'>)

Texts of all elements located by the locator.

Parameters

locator (str/list[WebElement]) – The locator to identify the elements or list[WebElement]

Keyword Arguments

typecast – Typecast the texts. Defaults to str.

Returns

list – list of texts, by typecast, of the given elements

timedelta(days, format='%m/%d/%Y', timezone=None)

Get the date by the given delta from today.

Parameters

• days (int) – Delta days from today

• format (str, optional) – Date format. Defaults to ‘%m/%d/%Y’.

Keyword Arguments

timezone (str) – Timezone name, such as ‘Asia/Taipei’. Name is handled by dateutil.tz.gettz(). Defaults to None.

Returns

str – Delta date from today

Examples

today() # 2020/12/10

timedelta(1) # 2020/12/11

timedelta(-1) # 2020/12/09

property timeout

Spydr webdriver timeout for implicitly_wait, page_load_timeout, and script_timeout

Returns

int – Spydr webdriver timeout

static timestamp(prefix='', suffix='')

Get current local timestamp with optional prefix and/or suffix.

Keyword Arguments

• prefix (str) – Prefix for timestamp. Defaults to ‘’.

• suffix (str) – Suffix for timestamp. Defaults to ‘’.

Returns

str – Timestamp with optional prefix and suffix

property title

Get the title of the current page.

Returns

str – Title of the current page

today(format='%m/%d/%Y', timezone=None)

Get Today’s date.

Parameters

format (str, optional) – Date format. Defaults to ‘%m/%d/%Y’.

Keyword Arguments

timezone (str) – Timezone name, such as ‘Asia/Taipei’. Name is handled by dateutil.tz.gettz(). Defaults to None.

Returns

str/datetime – Today’s date in the given format. When format is None, it returns as datetime.

toggle_attribute(locator, name)

Toggle a Boolean attribute of the given element. (IE not supported)

Parameters

• locator (str/WebElement) – The locator to identify the element or WebElement

• name ([type]) – Attribute name

toggle_class(locator, class_name)

Toggle the given CSS class of the element.

Parameters

• locator (str/WebElement) – The locator to identify the element or WebElement

• class_name (str) – CSS class name

trigger(locator, event)

Trigger the given event on the element.

Parameters

• locator (str/WebElement) – The locator to identify the element or WebElement

• event (str) – Event name

value(locator, typecast=<class 'str'>)

Get the value of the element using get_property.

Parameters

locator (str/WebElement) – The locator to identify the element or WebElement

Keyword Arguments

typecast – Typecast the value. Defaults to str.

Returns

The value, by typecast, of the element

value_now(locator, typecast=<class 'str'>)

Get the current value of the element using get_attribute.

Parameters

locator (str/WebElement) – The locator to identify the element or WebElement

Keyword Arguments

typecast – Typecast the value. Defaults to str.

Returns

The value, by typecast, of the element

values(locator, typecast=<class 'str'>)

Get the values of the elements.

Parameters

locator (str) – The locator to identify the elements or list[WebElement]

Keyword Arguments

typecast – Typecast the values. Defaults to str.

Returns

list – list of values, by typecast, of the given elements

wait

alias of selenium.webdriver.support.wait.WebDriverWait

wait_until(method, timeout=None, poll_frequency=0.5, ignored_exceptions=[<class 'selenium.common.exceptions.NoSuchElementException'>])

Create a WebDriverWait instance and wait until the given method is evaluated to not False.

Parameters

method (callable) – Method to call, and the method takes WebDriver instance as the parameter.

Keyword Arguments

• timeout (int) – Timeout. Defaults to self.timeout.

• poll_frequency (float) – Sleep interval between method calls. Defaults to 0.5.

• ignored_exceptions (list[Exception]) – Exception classes to ignore during calls. Defaults to (NoSuchElementException).

Returns

Any applicable return from the method call

Examples

wait_until(lambda wd: method(wd), timeout=5)

wait_until_alert_present()

Wait until alert is present.

Returns

False/Alert – Return False if not present. Return Alert if present.

wait_until_attribute_contains(locator, attribute, value)

Wait until the element’s attribute contains the given value.

Parameters

• locator (str/WebElement) – The locator to identify the element or WebElement

• attribute (str) – Attribute name

• value (str) – value to check

Returns

bool – Whether value is found in the element’s attribute

wait_until_class_contains(locator, class_name)

Wait until the element contains the given CSS class.

Parameters

• locator (str/WebElement) – The locator to identify the element or WebElement

• class_name (str) – CSS class name

Returns

bool – Whether the element contains the given CSS class

wait_until_class_excludes(locator, class_name)

Wait until the element excludes the given CSS class.

Parameters

• locator (str/WebElement) – The locator to identify the element or WebElement

• class_name (str) – CSS class name

Returns

bool – Whether the element excludes the given CSS class

wait_until_displayed(locator)

Wait until the element is displayed.

Parameters

locator (str/WebElement) – The locator to identify the element or WebElement

Returns

bool – Whether the element is displayed

wait_until_displayed_and_get_element(locator)

Wait until the element is displayed and return the element.

Parameters

locator (str/WebElement) – The locator to identify the element or WebElement

Returns

WebElement – WebElement

wait_until_enabled(locator)

Wait until the element is enabled.

Parameters

locator (str/WebElement) – The locator to identify the element or WebElement

Returns

bool – Whether the element is enabled

wait_until_frame_available_and_switch(frame_locator)

Wait until the given frame is available and switch to it.

Parameters

frame_locator (str/WebElement) – The locator to identify the frame or WebElement

wait_until_ignored_timeout(method, timeout=3)

Wait until the given method timed-out and ignore TimeoutException.

Parameters

method ([type]) – Method to call

Keyword Arguments

timeout (int) – [description]. Defaults to 3.

Returns

Any applicable return from the method call

wait_until_listdir_equal_to(directory, number, sleep=2)

Wait until the directory has the given number of files.

Parameters

• directory (str) – Directory

• number (int) – Number of files in the directory

Keyword Arguments

sleep (int) – Seconds to sleep after number of files matched. Defaults to 2.

Raises

WebDriverException – Raise an error when directory is not a directory or when number of files not matched.

Returns

bool – Whether the directory has the given number of files

wait_until_loading_finished(locator, seconds=2, loading_wait=None, sleep=None)

Wait the given seconds until loading/spinning element, by locator, shows up. If/when shown, wait until not displayed. If not, this is equivalent to sleep the given seconds.

Parameters

locator (str/WebElement) – The locator to identify the loading-like element

Keyword Arguments

• seconds (int) – Seconds to wait for loading-like element to show. Defaults to 2.

• loading_wait (int) – Seconds to wait for the loading-like element to disappear. When None, it is default to implicit_wait. Defaults to None.

• sleep (int) – Seconds to sleep after loading finished. Defaults to None.

Returns

bool – Whether the element is not displayed

wait_until_located(locator)

Wait until the element is located.

Parameters

locator (str/WebElement) – The locator to identify the element or WebElement

Returns

bool – Whether the element is located

wait_until_not(method)

Create a WebDriverWait instance and wait until the given method is evaluated to False.

Parameters

method (callable) – Method to call

Returns

Any applicable return from the method call

wait_until_not_displayed(locator, seconds=2)

Wait until the element is not displayed in the given seconds.

Parameters

locator (str) – The locator to identify the element

Keyword Arguments

seconds (int) – Seconds to give up waiting. Defaults to 2.

Returns

bool – Whether the element is not displayed

wait_until_number_of_windows_to_be(number)

Wait until number of windows matches the given number.

Parameters

number (int) – Number of windows

Returns

bool – Whether number of windows matching the given number

wait_until_page_loaded()

Wait until document.readyState is complete.

wait_until_page_not_changed(seconds=10, interval=2)

Wait until page_source not changed (page_source are compared at the interval)

Keyword Arguments

• seconds (int) – Seconds to give up waiting. Defaults to 10.

• interval (int) – Interval to compare page_source. Defaults to 2.

Returns

bool – Whether page_source not changed

wait_until_selected(locator)

Wait until the element is selected.

Parameters

locator (str/WebElement) – The locator to identify the element or WebElement

Returns

bool – Whether the element is selected

wait_until_selection_to_be(locator, is_selected)

Wait until the element’s selected state to match the given state.

Parameters

• locator (str/WebElement) – The locator to identify the element or WebElement

• is_selected (bool) – Element’s selected state

Returns

bool – Whether the element’s selected state matching the given state

wait_until_text_contains(locator, text)

Wait until the element’s text contains the given text.

Parameters

• locator (str/WebElement) – The locator to identify the element or WebElement

• text (str) – Text to match

Returns

bool – Whether the element’s text containing the given text

wait_until_text_equal_to(locator, text)

Wait until the element’s text equal to the given text.

Parameters

• locator (str/WebElement) – The locator to identify the element or WebElement

• text (str) – Text to not match

Returns

bool – Whether the element’s text equal to the given text

wait_until_text_excludes(locator, text)

Wait until the element’s text to exclude the given text.

Parameters

• locator (str/WebElement) – The locator to identify the element or WebElement

• text (str) – Text to not match

Returns

bool – Whether the element’s text excluding the given text

wait_until_text_not_equal_to(locator, text)

Wait until the element’s text not equal to the given text.

Parameters

• locator (str/WebElement) – The locator to identify the element or WebElement

• text (str) – Text to not match

Returns

bool – Whether the element’s text not equal to the given text

wait_until_title_contains(title)

Wait until the title of the current page contains the given title.

Parameters

title (str) – Title to match

Returns

bool – Whether the title containing the given title

wait_until_url_contains(url, timeout=None)

Wait until the URL of the current window contains the given URL.

Parameters

url (str) – URL to match

Keyword Arguments

timeout (int) – Timeout. Defaults to self.page_load_timeout.

Returns

bool – Whether the URL containing the given URL

property window_handle

Return the handle of the current window.

Returns

str – The current window handle

property window_handles

Return the handles of all windows within the current session.

Returns

list[str] – List of all window handles

property yml

YAML file as YML instance.

Returns

YML – YML instance

zoom(scale)

Set the zoom factor of a document defined by the viewport.

Parameters

scale (float/str) – Zoom factor: 0.8, 1.5, or ‘150%’

class spydr.webdriver.SpydrElement(spydr_or_element_self, element)

Bases: selenium.webdriver.remote.webelement.WebElement

Wrap WebElement with Spydr-specific implementations.

Goals:

• Add additional functionality to WebElement

• Add Spydr locator formats to WebElement

Parameters

• spydr_or_element_self (Spydr/SpydrElement) – Spydr or SpydrElement self

• element (WebElement) – WebElement instance

add_class(class_name)

Add the given CSS class to the element.

Parameters

class_name (str) – CSS class name

blur()

Trigger blur event on the element.

property children

Get the children elements.

Returns

list[WebElement] – The children elements of the current element.

clear()

Clears the text if it’s a text-entry element.

clear_and_send_keys(*keys, blur=False, wait_until_enabled=False)

Clear the element and then send the given keys.

Parameters

*keys – Any combinations of strings

Keyword Arguments

• blur (bool) – Lose focus after sending keys. Defaults to False.

• wait_until_enabled (bool) – Whether to wait until the element is_enabled() before clearing and sending keys. Defaults to False.

Returns

WebElement – WebElement

click(scroll_into_view=False)

Click the element.

Keyword Arguments

scroll_into_view (bool) – Whether to scroll the element into view before clicking. Defaults to False.

closest(locator)

Traverse the current element and its parents until it finds an element that matches the given locator. Will return itself or the matching ancestor. (IE not supported)

Parameters

locator (str) – The locator to identify the element

Returns

WebElement – WebElement

copy_and_paste(text)

Copy text to clipboard and paste it (send_keys) to the element. (Chrome only)

Parameters

text (str) – Text to paste

css_property(name)

The value of CSS property.

Parameters

name (str) – CSS property name

Returns

str – CSS property value

ctrl_click()

Ctrl-click the element.

property current_url

The element’s current URL.

Returns

str – URL

double_click()

Double-click the element.

double_click_with_offset(x_offset=1, y_offset=1)

Double-click the element from x and y offsets.

Keyword Arguments

• x_offset (int) – X offset from the left of the element. Defaults to 1.

• y_offset (int) – Y offset from the top of the element. Defaults to 1.

find_element(locator)

Find the element by the given locator.

Parameters

locator (str) – The locator to identify the element

Returns

WebElement – The element found

find_elements(locator)

Find all elements by the given locator.

Parameters

locator (str) – The locator to identify the elements

Returns

list[WebElement] – All elements found

property first_child

Get the first child element.

Returns

WebElement – The first child element of the current element.

focus()

Trigger focus event on the element.

get_attribute(name)

Get the given attribute or property of the element.

Parameters

name (str) – Attribute name

get_property(name)

Get the given property of the element.

Parameters

name (str) – Property name

has_attribute(attribute)

Check if the element has the given attribute.

Parameters

attribute (str) – Attribute name

Returns

bool – Whether the attribute exists

has_attribute_value(attribute, value)

Check if the element’s attribute contains the given value.

Parameters

• attribute (str) – Attribute name

• value (bool/str) – value to check

Returns

bool – Whether value is found in the element’s attribute

has_class(class_name)

Check if the element has the given CSS class.

Parameters

class_name (str) – CSS class name

Returns

bool – Whether the CSS class exists

has_text(text)

Check if the element contains the given text.

Parameters

text (str) – Text to check

Returns

bool – Whether the element has the given text

hide(locator)

Hide the element.

highlight(hex_color='#ff3')

Highlight the element with the given color.

Parameters

hex_color (str, optional) – Hex color. Defaults to ‘#ff3’.

property html

The element’s innerHTML.

Returns

str – innerHTML

property html_id

The ID of the element.

Returns

str – Element’s ID

property id

Internal ID used by selenium.

Returns

str – Internal WebElement ID

is_displayed()

Whether the element is visible to a user.

Returns

bool – Whether the element is visible

is_enabled()

whether the element is enabled.

Returns

bool – Whether the element is enabled

is_located(locator, seconds=None)

Check if the child element is located in the given seconds.

Parameters

locator (str) – The locator to identify the child element

Keyword Arguments

seconds (int) – Seconds to wait until giving up. Defaults to implicitly_wait.

Returns

False/WebElement – Return False if not located. Return WebElement if located.

is_selected()

Whether the element is selected.

Can be used to check if a checkbox or radio button is selected.

Returns

bool – Whether the element is selected

is_text_matched(text)

Whether the given text matches the element’s text.

Parameters

text (str) – Text to match

Returns

bool – Whether the given text matches

js_click()

Call HTMLElement.click() using JavaScript.

js_send_keys(text)

Send text to input using JavaScript.

Parameters

text (str) – Text to send

property last_child

Get the last child element.

Returns

WebElement – The last child element of the current element.

property location

The location of the element in the renderable canvas.

Returns

dict – The coordinate of the element as dict: {‘x’: 0, ‘y’: 0}

property next_element

Get the next element.

Returns

WebElement – The next element of the current element.

property parent_element

Get the parent element.

Returns

WebElement – The parent element of the current element.

paste_from_clipboard()

Paste clipboard (send_keys) to the element. (Chrome only)

property previous_element

Get the previous element.

Returns

WebElement – The previous element of the current element.

property rect

A dictionary with the size and location of the element.

Returns

dict – The size and location of the element as dict: {‘x’: 0, ‘y’: 0, ‘width’: 100, ‘height’: 100}

remove_attribute(attribute)

Remove the given attribute from the element.

Parameters

attribute (str) – Attribute name

remove_class(class_name)

Remove the given CSS class to the element.

Parameters

class_name (str) – CSS class name

right_click()

Right-click on the element.

right_click_with_offset(x_offset=1, y_offset=1)

Right-click on the element with x and y offsets.

Keyword Arguments

• x_offset (int) – X offset from the left of the element. Defaults to 1.

• y_offset (int) – Y offset from the top of the element. Defaults to 1.

save_screenshot(filename)

Save a screenshot of the element to filename (PNG).

Default directory for saved screenshots is defined in: screen_root.

Parameters

filename (str) – Filename of the screenshot

Returns

bool – Whether the file is saved

scroll_into_view(behavior='auto', block='start', inline='nearest')

Scroll the element’s parent to be displayed.

Keyword Arguments

• behavior (str) – Defines the transition animation. One of auto or smooth. Defaults to ‘auto’.

• block (str) – Defines vertical alignment. One of start, center, end, or nearest. Defaults to ‘start’.

• inline (str) – Defines horizontal alignment. One of start, center, end, or nearest. Defaults to ‘nearest’.

scroll_to(x, y)

Scroll the element to the given x- and y-coordinates. (IE not supported)

Parameters

• x (int) – x-coordinate

• y (int) – y-coordinate

select_options(filter_by='value', filter_value=None)

Get options of an select element. Filter the options by attribute if filter_value is given.

Keyword Arguments

• filter_by (str) – Filter options by attribute. Defaults to ‘value’.

• filter_value (str) – Filter option’s attribute by value. Defaults to None.

Raises

InvalidSelectorException – Raise an error when element is not a select element

Returns

list[WebElement] – All filtered options

selected_options()

Get select element’s selectedOptions.

Raises

WebDriverException – Raise an error if the element is not a select element.

Returns

list[WebElement] – All selected options

send_keys(*keys, blur=False, wait_until_enabled=False)

Simulate typing into the element.

Parameters

*keys – Any combinations of strings

Keyword Arguments

• blur (bool) – Lose focus after sending keys. Defaults to False.

• wait_until_enabled (bool) – Whether to wait until the element is_enabled() before sending keys. Defaults to False.

set_attribute(attribute, value)

Set the given value to the attribute of the element.

Parameters

• attribute (str) – Attribute name

• value (str) – Attribute name

show()

Show the element.

property size

The size of the element.

Returns

dict – The size of the element as dict: {‘width’: 100, ‘height’: 100}

submit()

Submit a form.

property tag_name

Get the element’s tagName.

Returns

str – tagName

property text

The the element’s text. (Only works when the element is in the viewport)

Returns

str – The text of the element

property text_content

Get the element’s text. (Works whether the element is in the viewport or not)

Returns

str – The text of the element

texts(child_locator, typecast=<class 'str'>)

Text of all children elements, located by child_locator.

Parameters

child_locator (str) – The locator to identify children elements.

Keyword Arguments

typecast – Typecast the texts. Defaults to str.

Returns

list – list of texts, by typecast, of the given elements

toggle_attribute(name)

Toggle a Boolean attribute. (IE not supported)

Parameters

name ([type]) – Attribute name

toggle_class(class_name)

Toggle the given CSS class of the element.

Parameters

class_name (str) – CSS class name

trigger(event)

Trigger the given event on the element.

Parameters

event (str) – Event name

property value

Get the value of the element using get_property.

Parameters

typecast – Typecast the value. Defaults to str.

Returns

The value, by typecast, of the element

property value_now

Get the current value of the element using get_attribute.

Parameters

typecast – Typecast the value. Defaults to str.

Returns

The value, by typecast, of the element

wait_until_displayed(timeout=None)

Wait until the element is displayed.

Keyword Arguments

timeout (int, optional) – Wait timeout. Defaults to Spydr driver timeout.

Returns

bool – Whether the element is displayed

wait_until_not_displayed(timeout=None)

Wait until the element is not displayed.

Keyword Arguments

timeout (int, optional) – Wait timeout. Defaults to Spydr driver timeout.

Returns

bool – Whether the element is not displayed

wait_until_not_enabled(timeout=None)

Wait until the element is not enabled.

Keyword Arguments

timeout (int, optional) – Wait timeout. Defaults to Spydr driver timeout.

Returns

bool – Whether the element is not enabled

Module contents