Tools for unit testing¶
Run fixtures¶
CleanDatabase¶
- class reahl.dev.fixtures.CleanDatabase(fixture, scenario=<reahl.tofu.fixture.DefaultScenario object at 0x5000b90>)¶
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 at 0x5000b90>)¶
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_js()¶
Returns the JavaScript that would be rendered for the Widget in the page header.
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.
- xpath(xpath)¶
Returns the lmxl Element found by the given xpath.
- 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.
- 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.
- 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.
- 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.
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.
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 an ErrorLabel containing the text 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_seperate_thread=True, connect=False)¶
Starts the webserver and web application.
Parameters: - in_seperate_thread – If False, the server handles requests in the same thread as your tests.
- connect – If True, also connects to the database.
- stop()¶
Stops the webserver and web application from running.
- shutdown_socket(socket_to_shutdown)¶
On windows, the shutdown of a socket does not work as we expect. http://stackoverflow.com/questions/409783/socket-shutdown-vs-socket-close This method tries the shutdown, and if it cannot, tries to close it.
- 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(*args, **kwds)¶
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=u'localhost', port=8000, scheme=u'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.
- 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, first waits for the element to become interactible (visible and enabled).
- 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, first waits for the element to become interactible (visible and enabled).
- 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.
- 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.
- 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.
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=u'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(*args, **kwds)¶
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.