Navigation

Tools for unit testing

Run fixtures

CleanDatabase

class reahl.dev.fixtures.CleanDatabase(fixture, scenario=<reahl.tofu.fixture.DefaultScenario object>)

A Fixture to be used as run fixture. Upon set up, it creates a new empty database with the correct database schema for the project and sets up any persistent classes for use with that schema. It also connects to the database. Upon tear down, the Fixture disconnects from the database.

BrowserSetup

class reahl.webdev.fixtures.BrowserSetup(fixture, scenario=<reahl.tofu.fixture.DefaultScenario object>)

A Fixture to be used as run fixture. It inherits from reahl.dev.fixtures.CleanDatabase and hence includes all its functionality, but adds a running, configured web server and more than one flavour of a Selenium 2.x WebDriver. BrowserSetup also stops all the necessary servers upon tear down.

The web server started runs in the same thread as your tests, making debugging easier.

reahl_server

The reahl.webdev.webserver.ReahlWebServer for this test process.

firefox_driver

A WebDriver instance set up to work with the running reahl_server, via Firefox.

chrome_driver

A WebDriver instance set up to work with the running reahl_server, via Chrome. Note that this expects a Chrome binary to be present at /usr/lib/chromium-browser/chromium-browser

web_driver

The default WebDriver instance (Chrome, by default).

config

A reahl.component.config.Configuration class used for the test process and web server.

Testing tools

WidgetTester

class reahl.webdev.tools.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.
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.

Browser

class reahl.webdev.tools.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 hebaves like a browser would, by opening redirect responses.
  • relative – Set to True to indicate that url_string contains a path relative to the current location.

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.

raw_html

Returns the HTML for the current location unchanged.

status

Returns the HTTP status code for the last response.

title

Returns the title of the current location.

last_request

Returns the last request.

location_path

Returns the current location url path.

location_scheme

Returns the the last request scheme(HTTP/HTTPS).

location_query_string

Returns the current query string.

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.
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.

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.

XPath

class reahl.webdev.tools.XPath(xpath)

An object representing 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.

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

classmethod label_with_text(text)

Returns an XPath to find an HTML <label> containing the text in text.

classmethod heading_with_text(level, text)

Returns an XPath to find an HTML <h> of level level containing the text in text.

classmethod caption_with_text(text)

Returns an XPath to find an HTML <caption> matching the text in text.

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_cell_with_text(text)

Returns an XPath to find an HTML <tr> that contains a <td> / cell with text matching the text in text

classmethod checkbox_in_table_row(nth)

Returns an XPath to find an HTML <tr> that contains a <td> / cell with text matching the text in text

classmethod link_with_text(text, nth=1)

Returns an XPath to find an HTML <a> containing the text in text.

classmethod link_starting_with_text(text)

Returns an XPath to find an HTML <a> containing text that starts with the contents of text.

classmethod paragraph_containing(text)

Returns an XPath to find an HTML <p> that contains the text in text.

classmethod input_labelled(label)

Returns an XPath to find an HTML <input> referred to by a <label> that contains the text in label.

classmethod select_labelled(label)

Returns an XPath to find an HTML <select> referred to by a <label> that contains the text in label.

classmethod input_of_type(input_type)

Returns an XPath to find an HTML <input> with type attribute input_type.

classmethod inputgroup_labelled(label)

Returns an XPath to find an InputGroup with label text label.

classmethod fieldset_with_legend(legend_text)

Returns an XPath to find a FieldSet with the given legend_text.

New in version 3.2.

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 error_label_containing(text)

Returns an XPath to find a Label containing the error message in text.

classmethod span_containing(text)

Returns an XPath to find a Span containing the message in text.

classmethod div_containing(text)

Returns an XPath to find a Div containing the message in text.

ReahlWebServer

class reahl.webdev.webserver.ReahlWebServer(config, port)

A web server for testing purposes. This web server runs both an HTTP and HTTPS server. It can be configured to handle requests in the same thread as the test itself, but it can also be run in a separate thread. The ReahlWebServer requires a certificate for use with HTTPS upon startup. A self signed certificate has been provided as part of the distribution for convenience.

Parameters:
  • config – The reahl.component.config.Configuration instance to use as config for this process.
  • port – The HTTP port on which the server should be started. The HTTPS port is computed as this number + 363.
classmethod fromConfigDirectory(directory, port)

Creates a new ReahlWebServer given a port and standard configuration directory for an application.

Parameters:
  • directory – The directory from which configuration will be read.
  • port – The HTTP port on which the server will be started.
set_app(new_wsgi_app)

Changes the currently served application to new_wsgi_app.

start(in_separate_thread=True, connect=False, in_seperate_thread=None)

Starts the webserver and web application.

Parameters:
  • in_separate_thread – If False, the server handles requests in the same thread as your tests.
  • in_seperate_thread – Deprecated: rather use in_separate_thread keyword argument
  • connect – If True, also connects to the database.
stop()

Stops the webserver and web application from running.

serve(timeout=0.01)

Call this method once to have the server handle all waiting requests in the calling thread.

install_handler(web_driver)

Installs this server’s request handler into the given web_driver. This enables the server to serve requests from the web_driver in the current thread.

in_background(wait_till_done_serving=True)

Returns a context manager. Within the context of this context manager, the webserver is temporarily run in a separate thread. After the context managed by this context manager is exited, the server reverts to handling requests in the current (test) thread.

Parameters:wait_till_done_serving – If True, wait for the server to finish its background job before exiting the context block.

DriverBrowser

class reahl.webdev.tools.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.
raw_html

Returns the HTML for the current location unchanged.

find_element(locator)

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.
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)

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 typed into the input.
type(locator, text, wait=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.
  • wait – If False, don’t wait_for_page_to_load after having typed into the input.
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.
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

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_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)

Executes JavaScript in the browser.

Parameters:script – A string containing the JavaScript to be executed.
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_checked(locator)

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

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

Ensures the CheckBoxInput element found by locator is currently checked.

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

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

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

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, background='White')

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.
  • background – The color to use as background color when cropping.
press_tab(locator)

Simulates the user pressing the tab key while the element at locator has focus.

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

Simulates the user pressing the backspace key while the element at locator has focus.

Parameters:locator – An instance of XPath or a string containing an XPath expression.
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.

xpath(xpath)

Returns the lmxl Element found by the given xpath.

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.

Table Of Contents

Previous topic

Tofu – Test Fixtures and other handy testing utilities (reahl.tofu)

Navigation

Created using Sphinx 1.4.3.