behave-webdriver API Reference

This reference is meant for those who want to develop upon, extend, or alter the behavior of behave-webdriver. This will contain information regarding the implementation of various methods. Many aspects of the BehaveDriver class deal closely with selenium webdriver instances, but this document will refrain from duplicating information that should be contained in the selenium documentation.

behave-webdriver is designed with you in-mind. You are free to extend the behavior of our webdriver classes to suit your unique needs. You can subclass our webdriver classes, use a custom selenium webdriver, write your own mixin, or use a mixin somebody else provides for selenium.

Warning

While every effort is made to not make breaking changes, until a stable release, expect some things here to change, including breaking changes.

The webdriver classes

behave-webdriver provides each of the same webdriver classes provided in selenium.webdriver. Each class inherits from the BehaveDriverMixin mixin as well as the respective selenium counterpart class.

class behave_webdriver.Chrome(*args, **kwargs)

Chrome driver class. Alternate constructors and browser-specific logic is implemented here.

class behave_webdriver.Firefox(*args, **kwargs)

Firefox driver class. Alternate constructors and browser-specific logic is implemented here.

doubleclick_element(element)

Overrides the doubleclick method to first scroll to element, and adds JS shim for doubleclick

class behave_webdriver.Ie(*args, **kwargs)

Ie driver class. Alternate constructors and browser-specific logic is implemented here.

class behave_webdriver.Safari(*args, **kwargs)

Safari driver class. Alternate constructors and browser-specific logic is implemented here.

class behave_webdriver.PhantomJS(*args, **kwargs)

PhantomJS driver class. Alternate constructors and browser-specific logic is implemented here.

class behave_webdriver.Edge(*args, **kwargs)

Edge driver class. Alternate constructors and browser-specific logic is implemented here.

class behave_webdriver.Opera(*args, **kwargs)

Opera driver class. Alternate constructors and browser-specific logic is implemented here.

class behave_webdriver.BlackBerry(*args, **kwargs)

BlackBerry driver class. Alternate constructors and browser-specific logic is implemented here.

class behave_webdriver.Android(*args, **kwargs)

Android driver class. Alternate constructors and browser-specific logic is implemented here.

class behave_webdriver.Remote(*args, **kwargs)

Remote driver class. Alternate constructors and browser-specific logic is implemented here.

The BehaveDriverMixin

The mixin class implements all of the general logic. If you want to alter how behave-webdriver behaves, this is probably the place to do it.

class behave_webdriver.driver.BehaveDriverMixin(*args, **kwargs)

Implements most of the general (I.E. not browser-specific) logic for step implementations.

Intended to be used with subclasses of any selenium webdriver.

>>> from behave_webdriver.driver import BehaveDriverMixin
>>> from somewhere import SomeDriver
>>> class MyBehaveDriver(BehaveDriverMixin, SomeDriver):
...     pass
>>> behave_driver = MyBehaveDriver()
>>> behave_driver.get('https://github.com/spyoungtech/behave-webdriver')

Can also be used with other mixins designed for selenium, such as selenium-requests

>>> from behave_webdriver.driver import BehaveDriverMixin
>>> from seleniumrequests import RequestMixin
>>> from selenium import webdriver
>>> class BehavingRequestDriver(BehaveDriverMixin, RequestMixin, webdriver.Chrome):
...     pass
>>> behave_driver = BehavingRequestDriver()
>>> response = behave_driver.request('GET', 'https://github.com/spyoungtech/behave-webdriver')

alert

Property shortcut for an Alert object for the driver Note: this will return an Alert instance regardless of whether or not there is actually an alert present. Use has_alert to check whether or not there is an alert currently present.

Returns:an selenium.webdriver.common.alert.Alert instance

click_element(element)

Click on an element. Note: this will not trigger some doubleclick events, even when n=2 with any delay. Instead, if you want to doubleclick, use doubleclick_element

Parameters:element (str) – CSS Selector or XPATH used to locate the element

click_link_text(text, partial=False)

Click on a link, located by matching the text contained in the link. If partial is True, the link is located by partial text.

Parameters:

• text (str) – The text contained in the link, used to locate the element.
• partial (bool) – Whether or not to match link by partial text (as opposed to full match)

Returns:

cookies

Shortcut for driver.get_cookies()

doubleclick_element(element)

Double click an element

Parameters:element (str) – CSS Selector or XPATH used to locate the element Returns:

drag_element(element, to_element)

Drag an element to the location of another element.

Parameters:

• element (str) – CSS Selector or XPATH used to locate the element
• to_element (str) – the selector used to locate the destination element

Returns:

element_contains(element, value)

Checks if an element contains (in value/text) a given string/value

Parameters:

• element (str) – CSS Selector or XPATH used to locate the element
• value (str) – the text/value to check for

Returns:

True or False, whether or not the value was found in the element.

Return type:

bool

element_enabled(element)

Checks if an element is enabled or not.

Parameters:element (str) – CSS Selector or XPATH used to locate the element Returns:True if the element is enabled, else False Return type:bool

element_exists(element)

Whether or not an element exists. Attempts to locate the element using get_element returns True if the element was found, False if it couldn’t be located.

Parameters:element (str) – CSS Selector or XPATH used to locate the element Returns:True if the element could be found, False if it couldn’t be found Return type:bool

element_has_class(element, cls)

Checks whether or not an element has a particular css class.

Parameters:

• element (str) – CSS Selector or XPATH used to locate the element
• cls (str) – The css class to check for

Returns:

True if the element has the specified class, else False

Return type:

bool

element_in_viewport(element)

Determines the bounding box (rect) of the window and rect of the element. This information is used to determine whether or not the element is completely within the viewport.

Parameters:element – CSS Selector or XPATH used to locate the element Returns:

element_selected(element)

Checks if an element is selected or not.

Parameters:element (str) – CSS Selector or XPATH used to locate the element Returns:True if the element is selected, else False Return type:bool

element_visible(element)

Checks if an element is visible or not.

Parameters:element (str) – CSS Selector or XPATH used to locate the element Returns:True if the element is visible, else False Return type:bool

get_element(selector, by=None)

Takes a selector string and uses an appropriate method (XPATH or CSS selector by default) to find a WebElement The optional by argument can be supplied to specify any locating method explicitly. This is used to resolve selectors from step definition strings to actual element objects

Parameters:

• selector (str) – The selector to use, an XPATH or CSS selector
• by – alternate method used to locate element, e.g. (By.id) See selenium.webdriver.common.by.By attributes

Returns:

WebElement object

get_element_attribute(element, attr, css=False, expected_value=None)

Get the value of an attribute or css attribute from an element.

Parameters:

• element (str) – CSS Selector or XPATH used to locate the element
• attr (str) – The attribute to lookup
• css (bool) – Whether or not this is a CSS atrribute
• expected_value –

Returns:

The value of the attribute

get_element_location(element)

Gets the location of the element in the renderable canvas. This is a dict with two keys: ‘x’ and ‘y’

Parameters:element (str) – CSS Selector or XPATH used to locate the element Returns:the element’s location Return type:dict

get_element_size(element)

Returns a dictionary containing the size information of an element. The dictionary has two keys: ‘width’ and ‘height’ which represent the size of the element dimensions in px

Parameters:element (str) – CSS Selector or XPATH used to locate the element Returns:A dictionary with size information Return type:dict

get_element_text(element)

Takes in a selector, finds the element, and extracts the text. When present on the WebElement, the element’s ‘value’ property is returned. (For example, this is useful for getting the current text of Input elements) If the element has no ‘value’ property, the containing text is returned (elem.text)

Parameters:element (str) – CSS Selector or XPATH used to locate the element Returns:the text contained within the element. Return type:str

has_alert

Whether or not there is currently an alert present

Returns:True if there is an alert present, else False Return type:bool

static is_color(str_)

Whether or not the string represents a color.

Parameters:str – Returns:

move_to_element(element, offset=None)

Moves the mouse to the middle of an element

Parameters:

• element (str) – CSS Selector or XPATH used to locate the element
• offset (tuple) – optional tuple of x/y offsets to offset mouse from center

Returns:

open_url(url)

Navigate to an absolute URL Behaves same as driver.get but serves as a common entry-point for subclasses wanting to change this.

Parameters:url (str) – an absolute URL including the scheme Returns:

pause(milliseconds)

Pause for a number of miliseconds. time.sleep is used here due to issues with w3c browsers and ActionChain pause feature.

Parameters:milliseconds (int) – number of miliseconds to wait Returns:

press_button(button)

Send a keystroke simulating the press of a given button. You can use keys as strings (e.g. ‘a’, ‘z’) or any key names (e.g. the ‘escape’ key). When the length of the button argument is greater than one character, names are checked against selenium.webdriver.common.keys.Keys first.

Parameters:button (str) – A single character or key name Returns:

primary_handle

shortcut for window_handles[0]

Returns:the primary (first) window handle

screen_size

Property for the current driver window size. Can also be set by assigning an x/y tuple.

Returns:tuple of the screen dimensions (x, y)

scroll_to(x, y)

Scroll to a particular (x, y) coordinate.

Parameters:

• x (int) – the x coordinate to scroll to.
• y (int) – the y coordinate to scroll to.

Returns:

scroll_to_bottom()

Scrolls the current window to the bottom of the window (0, document.body.scrollHeight).

scroll_to_element(element)

Scroll to the location of an element.

Parameters:element – CSS Selector or XPATH used to locate the element Returns:

secondary_handles

shortcut for window_handles[1:]

Returns:list of window handles Return type:list

select_option(select_element, by, by_arg)

Implements features for selecting options in Select elements. Uses selenium’s Select support class.

Parameters:

• select_element – CSS Selector or XPATH used to locate the select element containing options
• by (str) – the method for selecting the option, valid options include any select_by_X supported by Select.

Returns:

send_keys(keys)

Send arbitrary keys. Note: this is different than sending keys directly to an element.

Parameters:keys – keys to send Returns:

submit(element)

Shortcut for submitting an element

Parameters:element (str) – CSS Selector or XPATH used to locate the element Returns:

wait_for_element_condition(element, ms, negative, condition)

Wait on an element until a certain condition is met, up to a maximum amount of time to wait.

Parameters:

• element – CSS Selector or XPATH used to locate the element
• ms – maximum time (in milliseconds) to wait for the condition to be true
• negative – whether or not the check for negation of condition. Will coarse boolean from value
• condition – the condition to check for. Defaults to checking for presence of element

Returns:

element