Browser¶

Drivers

ftw.testbrowser.MECHANIZE_BROWSER_FIXTURE = <Layer 'ftw.testbrowser.drivers.layers.DefaultDriverFixture:mechanize library'>¶: A plone.testing layer which sets the default driver to Mechanize.

ftw.testbrowser.REQUESTS_BROWSER_FIXTURE = <Layer 'ftw.testbrowser.drivers.layers.DefaultDriverFixture:requests library'>¶: A plone.testing layer which sets the default driver to Requests.

ftw.testbrowser.TRAVERSAL_BROWSER_FIXTURE = <Layer 'ftw.testbrowser.drivers.layers.DefaultDriverFixture:traversal library'>¶: A plone.testing layer which sets the default driver to Traversal.

ftw.testbrowser.WEBTEST_BROWSER_FIXTURE = <Layer 'ftw.testbrowser.drivers.layers.DefaultDriverFixture:None'>¶: A plone.testing layer which sets the default driver to Webtest.

ftw.testbrowser.browser = <ftw.browser.core.Browser instance>¶: The singleton browser instance acting as default browser.

ftw.testbrowser.browsing(func)¶

The browsing decorator is used in tests for automatically setting up the browser and passing it into the test function as additional argument:

from ftw.testbrowser import browsing
from plone.app.testing import PLONE_FUNCTIONAL_TESTING
from unittest import TestCase

class TestSomething(TestCase):
    layer = PLONE_FUNCTIONAL_TESTING

    @browsing
    def test_login_form(self, browser):
        browser.open(view='login_form')
        self.assertEqual('http://nohost/plone/login_form',
                         browser.url)

class ftw.testbrowser.core.Browser¶

Bases: object

The Browser is the top level object of ftw.testbrowser. It represents the browser instance and is used for navigating and interacting with the browser.

The Browser is a context manager, requiring the Zope app to be set:

# "app" is the Zope app object

from ftw.testbrowser import Browser

browser = Browser()

with browser(app):
    browser.open()

When using the browser in tests there is a @browsing test-method decorator uses the global (singleton) browser and sets it up / tears it down using the context manager syntax. See the ftw.testbrowser.browsing documentation for more information.

Variables:	raise_http_errors – HTTPError exceptions are raised on 4xx and 5xx response codes when enabled (Default: `True`). exception_bubbling – When enabled, exceptions from within the Zope view are bubbled up into the test method if the driver supports it. (Default: `False`).

append_request_header(name, value)¶

Add a new permanent request header which is sent with every request until it is cleared.

HTTP allows multiple request headers with the same name. Therefore this method does not replace existing names. Use replace_request_header for replacing headers.

Be aware that the requests library does not support multiple headers with the same name, therefore it is always a replace for the requests module.

Parameters:	name (string) – Name of the request header value (string) – Value of the request header

See also

replace_request_header()

See also

clear_request_header()

base_url¶: The base URL of the current page. The base URL can be defined in HTML using a <base>-tag. If no <base>-tag is found, the page URL is used.

body¶: The binary response content

clear_request_header(name)¶

Removes a permanent header. If there are no such headers, the removal is silently skipped.

Parameters:	name (string) – Name of the request header as positional arguments

click_on(**kwargs)¶

Find a link by its text and click on it.

Parameters:	text (string) – The text to be looked for. within (`ftw.testbrowser.nodes.NodeWrapper`.) – A node object for limiting the scope of the search.
Returns:	The browser object.
Raises:	`ftw.testbrowser.exceptions.NoElementFound`

See also

find()

clone()¶

Creates a new browser instance with a cloned state of the current browser. Headers and cookies are copied but not shared. The new browser needs to be used as a context manager, eg.:

with browser.clone() as sub_browser:: sub_browser.open()

Returns:	A new browser instance.
Return type:	`ftw.testbrowser.core.Browser`

contents¶: The response body as native string.

contenttype¶: The contenttype of the response, e.g. text/html; charset=utf-8.

See also

mimetype(), encoding()

context¶

Returns the current context (Plone object) of the currently viewed page.

Returns:	The Plone context object

cookies¶: A read-only dict of current cookies.

css(**kwargs)¶

Select one or more HTML nodes by using a CSS selector.

Parameters:	css_selector (string) – The CSS selector.
Returns:	Object containg matches.
Return type:	`ftw.testbrowser.nodes.Nodes`

debug()¶

Open the current page in your real browser by writing the contents into a temporary file and opening it with os.system open [FILE].

This is meant to be used in pdb, not in actual code.

encoding¶: The encoding of the respone, e.g. utf-8.

See also

contenttype()

expect_http_error(**kwds)¶

Context manager for expecting certain HTTP errors. The code and reason arguments may be provided or omitted. The values are only asserted if the arguments are provided. An assertion error is raised when the HTTP error is not cathed in the code block. The code block may make a request or reload the browser.

Parameters:	code (`int`) – The status code to assert. reason (`string`) – The status reason to assert.
Raises:	`AssertionError`

expect_unauthorized(**kwds)¶: Context manager for expecting that next request, issued in the context manager block, will be unauthorized.

fill(values)¶

Fill multiple fields of a form on the current page. All fields must be in the same form.

Example:

browser.open(view='login_form')
browser.fill({'Login Name': 'hugo.boss', 'Password': 'secret'})

Since the form node (ftw.testbrowser.form.Form) is returned, it can easily be submitted:

browser.open(view='login_form')
browser.fill({'Login Name': 'hugo.boss',
              'Password': 'secret'}).submit()

Parameters:	values (dict) – The key is the label or input-name and the value is the value to set.
Returns:	The form node.
Return type:	`ftw.testbrowser.form.Form`

find(text, within=None)¶

Find an element by text. This will look for:

a link with this text (normalized, including subelements’ texts)
a field which has a label with this text
a button which has a label with this text

Parameters:	text (string) – The text to be looked for. within (`ftw.testbrowser.nodes.NodeWrapper`.) – A node object for limiting the scope of the search.
Returns:	A single node object or None if nothing matches.
Return type:	`ftw.testbrowser.nodes.NodeWrapper`

find_button_by_label(label, within=None)¶

Finds a form button by its text label.

Parameters:	text (string) – The text to be looked for. within (`ftw.testbrowser.nodes.NodeWrapper`.) – A node object for limiting the scope of the search.
Returns:	The button node or None if nothing matches.
Return type:	`ftw.testbrowser.form.SubmitButton`

find_field_by_text(text, within=None)¶

Finds a form field which has text as label.

Parameters:	text (string) – The text to be looked for. within (`ftw.testbrowser.nodes.NodeWrapper`.) – A node object for limiting the scope of the search.
Returns:	A single node object or None if nothing matches.
Return type:	`ftw.testbrowser.nodes.NodeWrapper`

find_form_by_field(field_label_or_name)¶

Searches for a field and returns the form containing the field. The field is searched by label text or field name. If no field was found, None is returned.

Parameters:	label_or_name (string) – The label or the name of the field.
Returns:	The form instance which has the searched fields or None
Return type:	`ftw.testbrowser.form.Form`.

find_form_by_fields(*labels_or_names)¶

Searches for the form which has fields for the labels passed as arguments and returns the form node.

Returns:	The form instance which has the searched fields.
Return type:	`ftw.testbrowser.form.Form`
Raises:	`ftw.testbrowser.exceptions.FormFieldNotFound`
Raises:	`ftw.testbrowser.exceptions.AmbiguousFormFields`

find_link_by_text(text, within=None)¶

Searches for a link with the passed text. The comparison is done with normalized whitespace and includes the full text within the link, including its subelements’ texts.

Parameters:	text (string) – The text to be looked for. within (`ftw.testbrowser.nodes.NodeWrapper`.) – A node object for limiting the scope of the search.
Returns:	The link object or None if nothing matches.
Return type:	`ftw.testbrowser.nodes.LinkNode`

form_field_labels¶

A list of label texts and field names of each field in any form on the current page.

The list contains the whitespace normalized label text of the each field. If there is no label or it has an empty text, the fieldname is used instead.

Returns:	A list of label texts (and field names).
Return type:	list of strings

forms¶: A dict of form instance where the key is the id or the name of the form and the value is the form node.

get_driver(library=None)¶: Return the driver instance for a library.

headers¶: A dict of response headers.

json¶: If the current page is JSON only, this can be used for getting the converted JSON data as python data structure.

login(username='test-user', password='secret')¶: Login a user by setting the Authorization header.

logout()¶: Logout the current user by removing the Authorization header.

mimetype¶: The mimetype of the respone, e.g. text/html.

See also

contenttype()

on(url_or_object=None, data=None, view=None, library=None)¶

on does almost the same thing as open. The difference is that on does not reload the page if the current page is the same as the requested one.

Be aware that filled form field values may stay when the page is not reloaded.

See also

open()

open(url_or_object=None, data=None, view=None, library=None, referer=False, method=None, headers=None, send_authenticator=False)¶

Opens a page in the browser.

Request library: When running tests on a Plone testing layer and using the @browsing decorator, the mechanize library is used by default, dispatching the request internal directly into Zope. When the testbrowser is used differently (no decorator nor zope app setup), the requests library is used, doing actual requests. If the default does not fit your needs you can change the library per request by passing in LIB_MECHANIZE or LIB_REQUESTS or you can change the library for the session by setting browser.request_library to either of those constants.

Parameters:

url_or_object – A full qualified URL or a Plone object (which has an absolute_url method). Defaults to the Plone Site URL.
data (dict or string) – A dict with data which is posted using a POST request, or request payload as string.
view (string) – The name of a view which will be added at the end of the current URL.
library (LIB_MECHANIZE or LIB_REQUESTS) – Lets you explicitly choose the request library to be used for this request.
referer (Boolean (Default False)) – Sets the referer when set to True.
method (string) – The HTTP request method. Defaults to ‘GET’ when not set, unless data is provided, then its set to ‘POST’.
headers (dict) – A dict with custom headers for this request.
send_authenticator (Boolean (Default False)) – When true, a plone.protect CSRF authenticator token is sent as if we would submit a prepared form. When this flag option is used, the request may be sent as POST. The code using the testbrowser with the send_authenticator option must make sure that plone.protect is installed.

See also

visit()

See also

LIB_MECHANIZE

See also

LIB_REQUESTS

open_html(html)¶

Opens a HTML page in the browser without doing a request. The passed html may be a string or a file-like stream.

Parameters:	html (string or file-like object) – The HTML content to load in the browser.
Returns:	The browser object.

parse(xml_or_html)¶

Parse XML or HTML with the default parser. For XML mime types the XML parser is used, otherwise the HTML parser.

Parameters:	xml (string) – The XML or HTML to parse.

parse_as_html(html=None)¶

Parse the response document with the HTML parser.

See also

ftw.testbrowser.core.Browser.parse

Parameters:	html (string) – The HTML to parse (default: current response).

parse_as_xml(xml=None)¶

Parse the response document with the XML parser.

See also

ftw.testbrowser.core.Browser.parse

Parameters:	xml (string) – The XML to parse (default: current response).

reload()¶

Reloads the current page by redoing the previous requests with the same arguments. This applies for GET as well as POST requests.

Raises:	`ftw.testbrowser.exceptions.BlankPage`
Returns:	The browser object.
Return type:	`ftw.testbrowser.core.Browser`

replace_request_header(name, value)¶

Adds a permanent request header which is sent with every request. Before adding the request header all existing request headers with the same name are removed.

Parameters:	name (string) – Name of the request header value (string) – Value of the request header

See also

replace_request_header()

See also

clear_request_header()

reset()¶: Resets the browser: closes active sessions and resets the internal state.

root¶: The current document root node.

status_code¶

The status code of the last response or None when no request was done yet.

Type:	int

status_reason¶

The status reason of the last response or None when no request was done yet. Examples: "OK", "Not Found".

Type:	string

url¶: The URL of the current page.

visit(*args, **kwargs)¶: Visit is an alias for open().

See also

open()

webdav(method, url_or_object=None, data=None, view=None, headers=None)¶

Makes a webdav request to the Zope server.

It is required that a ZSERVER_FIXTURE is used in the test setup (e.g. PLONE_ZSERVER'' from ``plone.app.testing).

Parameters:

method (string) – The HTTP request method (OPTIONS, PROPFIND, etc)
url_or_object – A full qualified URL or a Plone object (which has an absolute_url method). Defaults to the Plone Site URL.
data (dict) – A dict with data which is posted using a POST request.
view (string) – The name of a view which will be added at the end of the current URL.
headers (dict) – Pass in reqest headers.

xpath(**kwargs)¶

Select one or more HTML nodes by using an xpath selector.

Parameters:	xpath_selector (string) – The xpath selector.
Returns:	Object containg matches.
Return type:	`ftw.testbrowser.nodes.Nodes`

Drivers ¶

Drivers are responsible for making the request and responding to basic questions, such as the current URL or response headers.

RequestsDriver ¶

class ftw.testbrowser.drivers.requestsdriver.RequestsDriver(browser)¶

Bases: object

The requests driver uses the “requests” library for making real requests.

append_request_header(name, value)¶

Add a new permanent request header which is sent with every request until it is cleared.

HTTP allows multiple request headers with the same name. Therefore this method does not replace existing names. Use replace_request_header for replacing headers.

Be aware that the requests library does not support multiple headers with the same name, therefore it is always a replace for the requests module.

Parameters:	name (string) – Name of the request header value (string) – Value of the request header

clear_request_header(name)¶

Removes a permanent header. If there is no such header, the removal is silently skipped.

Parameters:	name (string) – Name of the request header as positional argument

cloned(subbrowser)¶

When a browser was cloned, this method is called on each driver instance so that the instance can do whatever is needed to have a cloned state too.

Parameters:	subbrowser (`ftw.testbrowser.core.Browser`) – The cloned subbrowser instance.

get_response_body()¶

Returns the response body of the last response.

Raises:	`ftw.testbrowser.exceptions.BlankPage`
Returns:	Response body
Return type:	string

get_response_cookies()¶

Retruns a dict-like object containing the cookies set by the last response.

Returns:	Response cookies dict
Return type:	dict

get_response_headers()¶

Returns a dict-like object containing the response headers. Returns an empty dict if there is no response.

Returns:	Response header dict
Return type:	dict

get_url()¶

Returns the current url, if we are on a page, or None.

Returns:	the current URL
Return type:	string or None

make_request(*args, **kwargs)¶

Make a request to the url and return the response body as string.

Parameters:	method (string) – The HTTP request method, all uppercase. url (string) – A full qualified URL. data (dict or string) – A dict with data which is posted using a `POST` request, or the raw request body as a string. headers (dict) – A dict with custom headers for this request. referer_url – The referer URL or `None`.
Returns:	Status code, reason and body
Return type:	tuple: (int, string, string or stream)

reload()¶

Reloads the current page by redoing the previous request with the same arguments. This applies for GET as well as POST requests.

Raises:	`ftw.testbrowser.exceptions.BlankPage`
Returns:	Status code, reason and body
Return type:	tuple: (int, string, string or stream)

reset()¶: Resets the driver: closes active sessions and resets the internal state.

MechanizeDriver ¶

class ftw.testbrowser.drivers.mechdriver.MechanizeDriver(browser)¶

Bases: object

The mechanize driver uses the Mechanize browser with plone.testing integration for making the requests.

append_request_header(name, value)¶

Add a new permanent request header which is sent with every request until it is cleared.

HTTP allows multiple request headers with the same name. Therefore this method does not replace existing names. Use replace_request_header for replacing headers.

Be aware that the requests library does not support multiple headers with the same name, therefore it is always a replace for the requests module.

Parameters:	name (string) – Name of the request header value (string) – Value of the request header

clear_request_header(name)¶

Removes a permanent header. If there is no such header, the removal is silently skipped.

Parameters:	name (string) – Name of the request header as positional argument

cloned(subbrowser)¶

When a browser was cloned, this method is called on each driver instance so that the instance can do whatever is needed to have a cloned state too.

Parameters:	subbrowser (`ftw.testbrowser.core.Browser`) – The cloned subbrowser instance.

get_response_body()¶

Returns the response body of the last response.

Raises:	`ftw.testbrowser.exceptions.BlankPage`
Returns:	Response body
Return type:	string

get_response_cookies()¶

Retruns a dict-like object containing the cookies set by the last response.

Returns:	Response cookies dict
Return type:	dict

get_response_headers()¶

Returns a dict-like object containing the response headers. Returns an empty dict if there is no response.

Returns:	Response header dict
Return type:	dict

get_url()¶

Returns the current url, if we are on a page, or None.

Returns:	the current URL
Return type:	string or None

make_request(*args, **kwargs)¶

Make a request to the url and return the response body as string.

Parameters:	method (string) – The HTTP request method, all uppercase. url (string) – A full qualified URL. data (dict or string) – A dict with data which is posted using a `POST` request, or the raw request body as a string. headers (dict) – A dict with custom headers for this request. referer_url – The referer URL or `None`.
Returns:	Status code, reason and body
Return type:	tuple: (int, string, string or stream)

reload()¶

Reloads the current page by redoing the previous request with the same arguments. This applies for GET as well as POST requests.

Raises:	`ftw.testbrowser.exceptions.BlankPage`
Returns:	Status code, reason and body
Return type:	tuple: (int, string, string or stream)

reset()¶: Resets the driver: closes active sessions and resets the internal state.

TraversalDriver ¶

class ftw.testbrowser.drivers.traversaldriver.TraversalDriver(browser)¶

Bases: object

The traversal driver simulates requests by by calling the zope traversal directly. The purpose of the traversal driver is to be able to use a testbrowser in the same transaction / connection as the test code is run. This makes it possible to write browser tests without transactions.

append_request_header(name, value)¶

Add a new permanent request header which is sent with every request until it is cleared.

HTTP allows multiple request headers with the same name. Therefore this method does not replace existing names. Use replace_request_header for replacing headers.

Be aware that the requests library does not support multiple headers with the same name, therefore it is always a replace for the requests module.

Parameters:	name (string) – Name of the request header value (string) – Value of the request header

clear_request_header(name)¶

Removes a permanent header. If there is no such header, the removal is silently skipped.

Parameters:	name (string) – Name of the request header as positional argument

cloned(subbrowser)¶

When a browser was cloned, this method is called on each driver instance so that the instance can do whatever is needed to have a cloned state too.

Parameters:	subbrowser (`ftw.testbrowser.core.Browser`) – The cloned subbrowser instance.

get_response_body()¶

Returns the response body of the last response.

Raises:	`ftw.testbrowser.exceptions.BlankPage`
Returns:	Response body
Return type:	string

get_response_cookies()¶

Retruns a dict-like object containing the cookies set by the last response.

Returns:	Response cookies dict
Return type:	dict

get_response_headers()¶

Returns a dict-like object containing the response headers. Returns an empty dict if there is no response.

Returns:	Response header dict
Return type:	dict

get_url()¶

Returns the current url, if we are on a page, or None.

Returns:	the current URL
Return type:	string or None

make_request(*args, **kwargs)¶

Make a request to the url and return the response body as string.

Parameters:	method (string) – The HTTP request method, all uppercase. url (string) – A full qualified URL. data (dict or string) – A dict with data which is posted using a `POST` request, or the raw request body as a string. headers (dict) – A dict with custom headers for this request. referer_url – The referer URL or `None`.
Returns:	Status code, reason and body
Return type:	tuple: (int, string, string or stream)

reload()¶

Reloads the current page by redoing the previous request with the same arguments. This applies for GET as well as POST requests.

Raises:	`ftw.testbrowser.exceptions.BlankPage`
Returns:	Status code, reason and body
Return type:	tuple: (int, string, string or stream)

reset()¶: Resets the driver: closes active sessions and resets the internal state.

StaticDriver ¶

class ftw.testbrowser.drivers.staticdriver.StaticDriver(browser)¶

Bases: object

The static driver can load static HTML without doing an actual request. It does not support making requests at all.

append_request_header(name, value)¶

Add a new permanent request header which is sent with every request until it is cleared.

HTTP allows multiple request headers with the same name. Therefore this method does not replace existing names. Use replace_request_header for replacing headers.

Be aware that the requests library does not support multiple headers with the same name, therefore it is always a replace for the requests module.

Parameters:	name (string) – Name of the request header value (string) – Value of the request header

clear_request_header(name)¶

Removes a permanent header. If there is no such header, the removal is silently skipped.

Parameters:	name (string) – Name of the request header as positional argument

cloned(subbrowser)¶

When a browser was cloned, this method is called on each driver instance so that the instance can do whatever is needed to have a cloned state too.

Parameters:	subbrowser (`ftw.testbrowser.core.Browser`) – The cloned subbrowser instance.

get_response_body()¶

Returns the response body of the last response.

Raises:	`ftw.testbrowser.exceptions.BlankPage`
Returns:	Response body
Return type:	string

get_response_cookies()¶

Retruns a dict-like object containing the cookies set by the last response.

Returns:	Response cookies dict
Return type:	dict

get_response_headers()¶

Returns a dict-like object containing the response headers. Returns an empty dict if there is no response.

Returns:	Response header dict
Return type:	dict

get_url()¶

Returns the current url, if we are on a page, or None.

Returns:	the current URL
Return type:	string or None

make_request(method, url, data=None, headers=None, referer_url=None)¶

Make a request to the url and return the response body as string.

Parameters:	method (string) – The HTTP request method, all uppercase. url (string) – A full qualified URL. data (dict or string) – A dict with data which is posted using a `POST` request, or the raw request body as a string. headers (dict) – A dict with custom headers for this request. referer_url – The referer URL or `None`.
Returns:	Status code, reason and body
Return type:	tuple: (int, string, string or stream)

reload()¶

Reloads the current page by redoing the previous request with the same arguments. This applies for GET as well as POST requests.

Raises:	`ftw.testbrowser.exceptions.BlankPage`
Returns:	Status code, reason and body
Return type:	tuple: (int, string, string or stream)

reset()¶: Resets the driver: closes active sessions and resets the internal state.

Browser¶

Drivers¶

RequestsDriver¶

MechanizeDriver¶

TraversalDriver¶

StaticDriver¶

Drivers ¶

RequestsDriver ¶

MechanizeDriver ¶

TraversalDriver ¶

StaticDriver ¶