Browser tools¶

Composing XPath expressions¶

XPath¶

class reahl.browsertools.browsertools.XPath(*xpaths)¶

An object to build an XPath expression for locating a particular element on a web page. A programmer is not supposed to instantiate an XPath directly. Use one of the descriptive class methods to instantiate an XPath instance, then build more complex expressions using the instance methods.

An XPath expression in a string is returned when an XPath object is cast to str.

Examples:

>>> str(XPath.div().including_class('alert'))
'//div[contains(concat(" ", @class, " "), " alert ")]

>>> XPath.button_labelled('Save').inside_of(XPath.div().including_class('myclass'))
XPath('//div[contains(concat(" ", @class, " "), " myclass ")]/.//button[normalize-space()=normalize-space("Save")]|//div[contains(concat(" ", @class, " "), " myclass ")]/.//input[normalize-space(@value)=normalize-space("Save")]')

Changed in version 5.0: Removed .checkbox_in_table_row() method.

Changed in version 5.0: Made XPath instances composable (added .inside_of).

Changed in version 5.0: Added __getitem__ so that something like .table()[5] gives you the 5th table in its parent.

Changed in version 5.0: Removed .error_label_containing()

Changed in version 5.0: Removed .span_containing()

Changed in version 5.0: Removed .div_containing()

Changed in version 5.0: Removed .paragraph_containing()

Changed in version 5.0: Removed .legend_with_text()

Changed in version 5.0: Removed .link_starting_with_text()

Changed in version 5.0: Removed .link_with_text()

Changed in version 5.0: Removed .table_cell_with_text()

Changed in version 5.0: Removed .heading_with_text()

Changed in version 5.0: Removed .label_with_text()

Changed in version 5.0: Removed .caption_with_text()

Changed in version 5.0: Removed .option_with_text()

inside_of(another)¶: Returns an XPath that is positioned inside of another.

New in version 5.0.

including_class(css_class)¶: Returns an XPath that additionally has a given css_class.

New in version 5.0.

with_id(text)¶: Returns an XPath that additionally has the id.

New in version 5.0.

with_text(text)¶: Returns an XPath that additionally matches the given text exactly.

New in version 5.0.

including_text(text)¶: Returns an XPath that additionally includes text matching the given text.

New in version 5.0.

with_text_starting(text)¶: Returns an XPath that additionally has text that starts with the given text.

New in version 5.0.

containing(another)¶: Returns an XPath that additionally contains another XPath.

New in version 5.0.

classmethod any(tag_name)¶: Returns an XPath to find an HTML tag with name=tag_name.

New in version 5.0.

classmethod button_labelled(label, **arguments)¶

Returns an XPath to find an ButtonInput whose visible label is the text in label.

When extra keyword arguments are sent to this method, each one is interpreted as the name (kwarg name) and value (kwarg value) of an Event argument which this ButtonInput instance should match.

classmethod caption()¶

Returns an XPath to find an HTML <caption>.

..versionadded:: 5.0

classmethod checkbox()¶: Returns a XPath to a checkbox input.

New in version 5.0.

classmethod div()¶: Returns an XPath to find an HTML <div>.

New in version 5.0.

classmethod fieldset_with_legend(legend_text)¶: Returns an XPath to find a FieldSet with the given legend_text.

New in version 3.2.

classmethod heading(level)¶: Returns an XPath to find an HTML <h?> of level level.

New in version 5.0.

classmethod input_labelled(label_text)¶: Returns an XPath to find an HTML <input> referred to by a <label> that contains the text in label.

classmethod input_named(name)¶: Returns an XPath to find an HTML <input> with the given name.

classmethod input_of_type(input_type)¶: Returns an XPath to find an HTML <input> with type attribute input_type.

classmethod label()¶: Returns an XPath to find an HTML <label>.

New in version 5.0.

classmethod legend()¶: Returns an XPath to find an HTML <legend>.

New in version 5.0.

classmethod link()¶: Returns an XPath to find an HTML <a>.

New in version 5.0.

classmethod option()¶: Returns an XPath to find an HTML <option>.

New in version 5.0.

classmethod paragraph()¶: Returns an XPath to find an HTML <p>.

New in version 5.0.

classmethod select_labelled(label_text)¶: Returns an XPath to find an HTML <select> referred to by a <label> that contains the text in label.

classmethod span()¶: Returns an XPath to find a Span.

New in version 5.0.

classmethod table()¶: Returns a XPath to a table.

New in version 5.0.

classmethod table_with_summary(text)¶: Returns an XPath to find an HTML <table summary=’…’> matching the text in text in its summary attribute value.

classmethod table_header()¶: Returns a XPath to a table header.

New in version 5.0.

classmethod table_body()¶: Returns a XPath to a table body.

New in version 5.0.

classmethod table_row()¶: Returns a XPath to a table row.

New in version 5.0.

classmethod table_footer()¶: Returns a XPath to a table footer.

New in version 5.0.

classmethod table_cell()¶: Returns a XPath to a table cell.

New in version 5.0.

classmethod table_cell_aligned_to(column_heading_text, search_column_heading, search_cell_text)¶: Find a cell (td or th) in the column with column_heading_text which is in the same row as where a cell in search_column_heading matches search_cell_text.

..versionadded:: 5.0

classmethod ul()¶

Returns an XPath to find an unordered list.

..versionadded:: 5.0

classmethod li()¶

Returns an XPath to find a list item.

..versionadded:: 5.0

Browser interfaces¶

DriverBrowser¶

class reahl.browsertools.browsertools.DriverBrowser(web_driver, host='localhost', port=8000, scheme='http')¶

A Browser implemented by a supplied Selenium WebDriver instance, but with interface matching (or similar to) Browser.

Parameters

web_driver – The WebDriver instance to be wrapped by this DriverBrowser.
host – The hostname of the machine used by default for URLs.
port – The port used by default for URLs.
scheme – The URL scheme used by default for URLs.

class Keys¶: Set of special keys codes.

property raw_html¶: Returns the HTML for the current location unchanged.

find_element(locator, wait=True)¶

Returns the (WebDriver) element found by locator. If not found, the method will keep waiting until 2 seconds have passed before it will report not finding an element. This timeout mechanism makes it possible to call find_element for elements that will be created via JavaScript, and may need some time before they appear.

Parameters

locator – An instance of XPath or a string containing an XPath expression.
wait – If wait=False don’t wait for the element to appear (default is True).

is_element_enabled(locator)¶

Answers whether the element found by locator is responsive to user activity or not.

Parameters: locator – An instance of XPath or a string containing an XPath expression.

wait_for_element_enabled(locator)¶

Waits until the the element found by locator is present and becomes responsive to user activity.

Parameters: locator – An instance of XPath or a string containing an XPath expression.

is_interactable(locator)¶

Answers whether the element found by locator is actually being displayed by the browser as well as responsive to user activity.

Parameters: locator – An instance of XPath or a string containing an XPath expression.

wait_for_element_interactable(locator)¶

Waits until the element found by locator is being displayed by the browser as well as responsive to user activity.

Parameters: locator – An instance of XPath or a string containing an XPath expression.

is_visible(locator)¶

Answers whether the element found by locator is being displayed by the browser.

Parameters: locator – An instance of XPath or a string containing an XPath expression.

is_element_value(locator, value)¶

Answers whether the element found by locator has a value equal to the contents of value.

Parameters

locator – An instance of XPath or a string containing an XPath expression.
value – The (text) value to match.

does_element_have_attribute(locator, attribute, value=None)¶

Answers whether the element found by locator has the given attribute, with the given value

Parameters

locator – An instance of XPath or a string containing an XPath expression.
attribute – The name of the attribute to check for.
value – The value the attribute should have (if any)

New in version 3.2.

wait_for(condition, *args, **kwargs)¶

Waits until condition is satisfied. If condition is not satisfied after a timeout period of 2 seconds, an exception is raised.

Parameters: condition – A function, method or other callable which will be called periodically to check whether a certain condition holds. It should return True if the condition holds, False otherwise.

Extra positional and keyword arguments to this method are passed on as-is in the calls to condition.

wait_for_not(condition, *args, **kwargs)¶: Waits until the given condition is not satisfied. See DriverBrowser.wait_for().

wait_for_element_visible(locator)¶

Waits for the element found by locator to become visible.

Parameters: locator – An instance of XPath or a string containing an XPath expression.

wait_for_element_not_visible(locator)¶

Waits until the element found by locator is not visible.

Parameters: locator – An instance of XPath or a string containing an XPath expression.

is_page_loaded()¶: Answers whether the current page has finished loading.

wait_for_page_to_load()¶: Waits for the current page to load.

wait_for_element_present(locator)¶

Waits until the element found by locator is present on the page (whether visible or not).

Parameters: locator – An instance of XPath or a string containing an XPath expression.

wait_for_element_not_present(locator)¶

Waits until the element found by locator is not present on the page (whether visible or not).

Parameters: locator – An instance of XPath or a string containing an XPath expression.

open(url_string)¶

GETs the URL in url_string.

Parameters: url_string – A string containing the URL to be opened.

click(locator, wait=True, wait_for_ajax=True)¶

Clicks on the element found by locator.

Parameters

locator – An instance of XPath or a string containing an XPath expression.
wait – If False, don’t wait_for_page_to_load after having clicked the input.
wait_for_ajax – If False, don’t wait for ajax to finish before continuing (default is to wait).

Changed in version 5.0: Added keyword wait_for_ajax

type(locator, text, trigger_blur=True, wait_for_ajax=True)¶

Types the text in value into the input found by the locator.

Parameters

locator – An instance of XPath or a string containing an XPath expression.
text – The text to be typed.
trigger_blur – If False, don’t trigger the blur event on the input after typing (by default blur is triggered).
wait_for_ajax – If False, don’t wait for ajax to finish before continuing (default is to wait).

Changed in version 5.0: Removed wait kwarg, since we don’t ever need to wait_for_page_to_load after typing into an input

Changed in version 5.0: Added trigger_blur to trigger possible onchange events automatically after typing.

Changed in version 5.0: Added keyword wait_for_ajax

type_focussed(keys)¶

Type the keys wherever the focus is.

Parameters: keys – Keys to send

..versionadded:: 5.0

select(locator, label_to_choose, wait_for_ajax=True)¶

Finds the select element indicated by locator and selects one of its options.

Parameters

locator – An instance of XPath or a string containing an XPath expression.
label_to_choose – The label of the option that should be selected.
wait_for_ajax –
If False, don’t wait for ajax to finish before continuing (default is to wait).

Changed in version 5.0: Added keyword wait_for_ajax

select_many(locator, labels_to_choose, wait_for_ajax=True)¶

Finds the select element indicated by locator and selects some of its options.

Parameters

locator – An instance of XPath or a string containing an XPath expression.
labels_to_choose – A list of the labels of the options that should be selected.
wait_for_ajax – If False, don’t wait for ajax to finish before continuing (default is to wait).

Changed in version 5.0: Added keyword wait_for_ajax

select_none(locator, wait_for_ajax=True)¶

Finds the select element indicated by locator and deselects all options.

Parameters

locator – An instance of XPath or a string containing an XPath expression.
wait_for_ajax – If False, don’t wait for ajax to finish before continuing (default is to wait).

Changed in version 5.0: Added keyword wait_for_ajax

mouse_over(locator)¶

Moves the mouse pointer over the element found by the locator.

Parameters: locator – An instance of XPath or a string containing an XPath expression.

is_on_top(locator)¶

Answers whether the located element is topmost at its location in terms of z-index.

Parameters: locator – An instance of XPath or a string containing an XPath expression.

..versionadded:: 5.0

focus_on(locator)¶

Puts the tab-focus at the element found by the locator.

Parameters: locator – An instance of XPath or a string containing an XPath expression.

..versionadded:: 3.2

is_focus_on(locator)¶

Answers whether the tab-focus is on the element found by the locator.

Parameters: locator – An instance of XPath or a string containing an XPath expression.

..versionadded:: 5.0

property current_url¶: Returns the reahl.web.fw.Url of the current location.

go_back()¶: GETs the previous location (like the back button on a browser).

refresh()¶: GETs the current location again (like the refresh button on a browser).

get_fragment()¶: Returns the fragment part (the bit after the #) on the current URL.

New in version 5.0.

set_fragment(fragment)¶: Changes only the fragment part (the bit after the #) on the current URL.

New in version 5.0.

get_attribute(locator, attribute_name)¶

Returns the value of the HTML attribute of the element found by locator.

Parameters

locator – An instance of XPath or a string containing an XPath expression.
attribute_name – The name of the attribute to return.

get_value(locator)¶

Returns the value of the input indicated by locator.

Parameters: locator – An instance of XPath or a string containing an XPath expression.

execute_script(script, *arguments)¶

Executes JavaScript in the browser.

Parameters

script – A string containing the body of a JavaScript function to be executed.
arguments – Variable positional args passed into the function as an array named arguments.

switch_styling(javascript=True)¶: Switches styling for javascript enabled or javascript disabled.

New in version 3.2.

get_text(locator)¶

Returns the contents of the element found by locator, as plain text.

Parameters: locator – An instance of XPath or a string containing an XPath expression.

is_image_shown(locator)¶

Answers whether the located image is available from the server (ie, whether the src attribute of an img element is accessible).

Parameters: locator – An instance of XPath or a string containing an XPath expression.

is_editable(locator)¶

Answers whether the element found by locator can be edited by a user.

Parameters: locator – An instance of XPath or a string containing an XPath expression.

is_active(locator)¶

Answers whether the <a> element found by locator is currently clickable.

Parameters: locator – An instance of XPath or a string containing an XPath expression.

is_selected(locator)¶

Answers whether the CheckBoxInput or RadionButton element found by locator is currently checked.

Parameters: locator – An instance of XPath or a string containing an XPath expression.

Changed in version 5.0: Renamed from is_checked() to is_selected()

set_selected(locator, wait_for_ajax=True)¶

Ensures the CheckBoxInput or RadioButton element found by locator is currently checked.

Parameters

locator – An instance of XPath or a string containing an XPath expression.
wait_for_ajax – If False, don’t wait for ajax to finish before continuing (default is to wait).

Changed in version 5.0: Changed to break is locator is already checked.

Changed in version 5.0: Added keyword wait_for_ajax.

Changed in version 5.0: Renamed from check() to set_selected()

set_deselected(locator, wait_for_ajax=True)¶

Ensures the CheckBoxInput or RadioButton element found by locator is currently not checked.

Parameters

locator – An instance of XPath or a string containing an XPath expression.
wait_for_ajax – If False, don’t wait for ajax to finish before continuing (default is to wait).

Changed in version 5.0: Changed to break is locator is already unchecked.

Changed in version 5.0: Added keyword wait_for_ajax

Changed in version 5.0: Renamed from check() to set_deselected()

create_cookie(cookie_dict)¶

Creates a cookie from the given cookie_dict.

Parameters: cookie_dict – A dictionary with two required keys: ‘name’ and ‘value’. The values of these keys are the name of the cookie and its value, respectively. The keys ‘path’, ‘domain’, ‘secure’, ‘expiry’ can also be set to values. These have the respective meanings as defined in RFC6265.

delete_all_cookies()¶: Removes all cookies fomr the browser.

get_html_for(locator)¶

Returns the HTML of the element (including its own tags) targeted by the given locator

Parameters: locator – An instance of XPath or a string containing an XPath expression.

get_inner_html_for(locator)¶

Returns the HTML of the children of the element targeted by the given locator (excluding the element’s own tags).

Parameters: locator – An instance of XPath or a string containing an XPath expression.

get_xpath_count(locator)¶

Answers the number of elements matching locator.

Parameters: locator – An instance of XPath or a string containing an XPath expression.

capture_cropped_screenshot(output_file)¶

Takes a screenshot of the current page, and writes it to output_file. The image is cropped to contain only the parts containing something other than the background color.

Parameters: output_file – The name of the file to which to write the screenshot.

press_tab(shift=False)¶: Simulates the user pressing the tab key on element that is currently focussed.

Changed in version 4.0: Changed to operate on the currently focused element.

Changed in version 5.0: Added shift to be able to tab backwards

press_arrow(direction)¶

Simulates the user pressing arrow key on the element that has focus.

Parameters: direction – Either ‘up’, ‘down’, ‘left’, ‘right’

New in version 5.0.

property title¶: Returns the title of the current location.

no_page_load_expected()¶: Returns a context manager that would raise an exception should the current page be reloaded while code executes within the context managed by this context manager. Useful for testing JavaScript code that should change a page without refreshing it.

no_load_expected_for(jquery_selector)¶: Returns a context manager that would raise an exception should the element indicated by the given jquery selector be reloaded/replaced during execution of its context. Useful for testing JavaScript code that should change an element without replacing it.

load_expected_for(jquery_selector, refresh_expected)¶: Returns a context manager that would raise an exception should the element indicated by the given jquery selector be reloaded/replaced or not during execution of its context. Useful for testing JavaScript code that should change an element without replacing it. If refresh_expected is True, the exception is raised when the element is NOT refreshed.

refresh_expected_for(jquery_selector, refresh_expected)¶: Returns a context manager that would raise an exception should the element indicated by the given jquery selector be reloaded/replaced or not during execution of its context. Useful for testing JavaScript code that should change an element without replacing it. If refresh_expected is True, the exception is raised when the element is NOT refreshed.

new_tab_closed()¶: Returns a context manager that ensures, if a new tab is opened in its context, selenium ends up on the original tab while the newly created tab is closed on exit.

xpath(xpath)¶: Returns the lmxl Element found by the given xpath.

Browser¶

class reahl.browsertools.browsertools.Browser(wsgi_app)¶

A Browser that can be used to test a WSGI application in the current thread, without the need for a separate web server. This class implements methods matching the actions a user would perform using a browser.

Parameters: wsgi_app – The application instance under test.

open(url_string, follow_redirects=True, **kwargs)¶

GETs the URL in url_string.

Parameters

url_string – A string containing the URL to be opened.
follow_redirects – If False, this method acts as a simple GET request. If True (the default), the method behaves like a browser would, by opening redirect responses.

Other keyword arguments are passed directly on to WebTest.get.

go_back()¶: GETs the previous location (like the back button on a browser).

refresh()¶: GETs the current location again (like the refresh button on a browser).

follow_response()¶: Assuming the last response received was a redirect, follows that response (and other redirect responses that may be received in the process until a response is received which is not a redirect.

post(url_string, form_values, **kwargs)¶

POSTs the given form values to the url given.

Parameters

url_string – A string containing the URL to be posted to.
form_values – A dictionary containing form data in its key/value pairs.

Other keyword arguments are passed directly on to WebTest.post.

property raw_html¶: Returns the HTML for the current location unchanged.

property status¶: Returns the HTTP status code for the last response.

property title¶: Returns the title of the current location.

property last_request¶: Returns the last request.

property current_url¶: Returns the reahl.web.fw.Url of the current location.

New in version 5.0.

get_form_for(locator)¶

Return the form for the given locator.

Parameters: locator – An instance of XPath or a string containing an XPath expression.

type(locator, text)¶

Types the text in text into the input found by the locator.

Parameters

locator – An instance of XPath or a string containing an XPath expression.
text – The text to be typed.

click(locator, **kwargs)¶

Clicks on the element found by locator.

Parameters: locator – An instance of XPath or a string containing an XPath expression.

Other keyword arguments are passed directly on to Form.submit.

select(locator, label_to_choose)¶

Finds the select element indicated by locator and selects one of its options.

Parameters

locator – An instance of XPath or a string containing an XPath expression.
label_to_choose – The label of the option that should be selected.

select_many(locator, labels_to_choose)¶

Finds the select element indicated by locator and selects the options labelled as such.

Parameters

locator – An instance of XPath or a string containing an XPath expression.
labels_to_choose – The labels of the options that should be selected.

select_none(locator)¶

Finds the select element indicated by locator and ensure nothing is selected.

Parameters: locator – An instance of XPath or a string containing an XPath expression.

get_value(locator)¶

Returns the value of the input indicated by locator.

Parameters: locator – An instance of XPath or a string containing an XPath expression.

is_image_shown(locator)¶

Answers whether the located image is available from the server (ie, whether the src attribute of an img element is accessible).

Parameters: locator – An instance of XPath or a string containing an XPath expression.

create_cookie(cookie_dict)¶

Creates a cookie from the given cookie_dict.

Parameters: cookie_dict – A dictionary with two keys: ‘name’ and ‘value’. The values of these keys are the name of the cookie and its value, respectively. The keys ‘path’, ‘domain’, ‘secure’, ‘expiry’ can also be set to values. These have the respective meanings as defined in RFC6265 <http://tools.ietf.org/html/rfc6265#section-5.2>

is_element_enabled(locator)¶

Answers whether the located element is reactive to user commands or not. For <a> elements, this means that they have an href attribute, for inputs it means that they are not disabled.

Parameters: locator – An instance of XPath or a string containing an XPath expression.

get_html_for(locator)¶

Returns the HTML of the element (including its own tags) targeted by the given locator

Parameters: locator – An instance of XPath or a string containing an XPath expression.

get_inner_html_for(locator)¶

Returns the HTML of the children of the element targeted by the given locator (excluding the element’s own tags).

Parameters: locator – An instance of XPath or a string containing an XPath expression.

get_xpath_count(locator)¶

Answers the number of elements matching locator.

Parameters: locator – An instance of XPath or a string containing an XPath expression.

xpath(xpath)¶: Returns the lmxl Element found by the given xpath.

WidgetTester¶

class reahl.browsertools.browsertools.WidgetTester(widget)¶

A WidgetTester is used to render the contents of a reahl.web.fw.Widget instance.

Parameters: widget – The Widget instance to be tested.

property raw_html¶: The HTML rendered by the Widget.

render_html()¶: Returns the HTML rendered by the Widget.

render_html_tree()¶: Returns an lxml tree of HTML elements rendered by the Widget.

render_js()¶: Returns the JavaScript that would be rendered for the Widget in the page header.

get_html_for(locator)¶

Returns the HTML of the element (including its own tags) targeted by the given locator

Parameters: locator – An instance of XPath or a string containing an XPath expression.

get_inner_html_for(locator)¶

Returns the HTML of the children of the element targeted by the given locator (excluding the element’s own tags).

Parameters: locator – An instance of XPath or a string containing an XPath expression.

get_xpath_count(locator)¶

Answers the number of elements matching locator.

Parameters: locator – An instance of XPath or a string containing an XPath expression.

xpath(xpath)¶: Returns the lmxl Element found by the given xpath.

reahl

Browser tools¶

Composing XPath expressions¶

XPath¶

Browser interfaces¶

DriverBrowser¶

Browser¶

WidgetTester¶

Table of Contents

Previous topic

Next topic

Navigation

Browser tools¶

Composing XPath expressions¶

XPath¶

Browser interfaces¶

DriverBrowser¶

Browser¶

WidgetTester¶

Table of Contents

Previous topic

Next topic

Quick search

Navigation