Browser¶
-
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.
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 offtw.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
See also
-
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: See also
-
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
-
context
¶ Returns the current context (Plone object) of the currently viewed page.
Returns: The Plone context object
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
-
expect_http_error
(**kwds)¶ Context manager for expecting certain HTTP errors. The
code
andreason
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
- code (
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:
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:
-
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:
-
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:
-
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
-
on
(url_or_object=None, data=None, view=None, library=None)¶ on
does almost the same thing asopen
. The difference is thaton
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
(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, themechanize
library is used by default, dispatching the request internal directly into Zope. When the testbrowser is used differently (no decorator nor zope app setup), therequests
library is used, doing actual requests. If the default does not fit your needs you can change the library per request by passing inLIB_MECHANIZE
orLIB_REQUESTS
or you can change the library for the session by settingbrowser.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
orLIB_REQUESTS
) – Lets you explicitly choose the request library to be used for this request. - referer (Boolean (Default
False
)) – Sets the referer when set toTrue
. - 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, aplone.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 asPOST
. The code using the testbrowser with thesend_authenticator
option must make sure thatplone.protect
is installed.
See also
See also
LIB_MECHANIZE
See also
LIB_REQUESTS
- url_or_object – A full qualified URL or a Plone object (which has
an
-
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
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
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
See also
-
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.
-
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.
- method (string) – The HTTP request method (
-
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
- raise_http_errors – HTTPError exceptions are raised on 4xx
and 5xx response codes when enabled (Default:
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
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
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
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
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.
-