Browser¶

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 unittest2 import TestCase

class TestSomething(TestCase):
    layer = PLONE_FUNCTIONAL_TESTING

    @browsing
    def test_login_form(self, browser):
        browser.open(view='login_form')
        self.assertEquals('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.

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.

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(text, within=None)¶

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 source of the current page (usually HTML).

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(css_selector)¶

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

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.

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

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

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`

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.

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(xpath_selector, query_info=None)¶

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`

ftw.testbrowser.core.LIB_MECHANIZE = 'mechanize library'¶: Constant for choosing the mechanize library (interally dispatched requests)

ftw.testbrowser.core.LIB_REQUESTS = 'requests library'¶: Constant for choosing the requests library (actual requests)

Browser¶

Previous topic

Next topic

This Page