zope.testbrowser API

zope.testbrowser.interfaces

Browser-like functional doctest interfaces

Interfaces

interface zope.testbrowser.interfaces.ICookies[source]

Extends: zope.interface.common.mapping.IExtendedReadMapping, zope.interface.common.mapping.IExtendedWriteMapping, zope.interface.common.mapping.IMapping

A mapping of cookies for a given url

url

URL

The URL the mapping is currently exposing.

Implementation:zope.schema.URI
Read Only:False
Required:True
Default Value:None
Allowed Type:str
header

Header

The current value for the Cookie header for the URL

Implementation:zope.schema.TextLine
Read Only:False
Required:True
Default Value:None
Allowed Type:str
forURL(url)

Returns another ICookies instance for the given URL.

getinfo(name)

returns dict of settings for the given cookie name.

This includes only the following cookie values:

  • name (str)
  • value (str),
  • port (int or None),
  • domain (str),
  • path (str or None),
  • secure (bool), and
  • expires (datetime.datetime with pytz.UTC timezone or None),
  • comment (str or None),
  • commenturl (str or None).

(Method name is not camelCase because it is intended to feel like an extension to the mapping interface, which uses all lower case, e.g. iterkeys.)

iterinfo(name=None)

iterate over the information about all the cookies for the URL.

Each result is a dictionary as described for getinfo.

If name is given, iterates over all cookies for given name.

(Method name is not camelCase because it is intended to feel like an extension to the mapping interface, which uses all lower case, e.g. iterkeys.)

create(name, value, domain=None, expires=None, path=None, secure=None, comment=None, commenturl=None, port=None)

Create a new cookie with the given values.

If cookie of the same name, domain, and path exists, raises a ValueError.

Expires is a string or a datetime.datetime. timezone-naive datetimes are interpreted as in UTC. If expires is before now, raises AlreadyExpiredError.

If the domain or path do not generally match the current URL, raises ValueError.

change(name, value=None, domain=None, expires=None, path=None, secure=None, comment=None, commenturl=None, port=None)

Change an attribute of an existing cookie.

If cookie does not exist, raises a KeyError.

clearAll()

Clear all cookies for the associated browser, irrespective of URL

clearAllSession()

Clear session cookies for associated browser, irrespective of URL

interface zope.testbrowser.interfaces.IBrowser[source]

A Programmatic Web Browser.

cookies

Cookies

An ICookies mapping for the browser’s current URL.

Implementation:zope.schema.Field
Read Only:False
Required:True
Default Value:None
url

URL

The URL the browser is currently showing.

Implementation:zope.schema.URI
Read Only:False
Required:True
Default Value:None
Allowed Type:str
headers

Headers

Headers of the HTTP response; a httplib.HTTPMessage.

Implementation:zope.schema.Field
Read Only:False
Required:True
Default Value:None
contents

Contents

The complete response body of the HTTP request.

Implementation:zope.schema.Text
Read Only:False
Required:True
Default Value:None
Allowed Type:str
isHtml

Is HTML

Tells whether the output is HTML or not.

Implementation:zope.schema.Bool
Read Only:False
Required:True
Default Value:None
Allowed Type:bool
title

Title

Title of the displayed page

Implementation:zope.schema.TextLine
Read Only:False
Required:False
Default Value:None
Allowed Type:str
handleErrors

Handle Errors

Describes whether server-side errors will be handled by the publisher. If set to False, the error will progress all the way to the test, which is good for debugging.

Implementation:zope.schema.Bool
Read Only:False
Required:True
Default Value:True
Allowed Type:bool
followRedirects

Follow Redirects

Describes whether the browser follows redirects. If set to True, it will automatically issue GET requests for redirect responses; if set to False, it will return redirect responses directly, allowing the caller to make assertions about them.

Implementation:zope.schema.Bool
Read Only:False
Required:True
Default Value:True
Allowed Type:bool
addHeader(key, value)

Adds a header to each HTTP request.

Adding additional headers can be useful in many ways, from setting the credentials token to specifying the browser identification string.

open(url, data=None)

Open a URL in the browser.

The URL must be fully qualified. However, note that the server name and port is arbitrary for Zope 3 functional tests, since the request is sent to the publisher directly.

The data argument describes the data that will be sent as the body of the request.

reload()

Reload the current page.

Like a browser reload, if the past request included a form submission, the form data will be resubmitted.

goBack(count=1)

Go back in history by a certain amount of visisted pages.

The count argument specifies how far to go back. It is set to 1 by default.

Return an ILink from the page.

The link is found by the arguments of the method. One or more may be used together.

o text – A regular expression trying to match the link’s text,
in other words everything between <a> and </a> or the value of the submit button.
o url – The URL the link is going to. This is either the
href attribute of an anchor tag or the action of a form.

o id – The id attribute of the anchor tag submit button.

o index – When there’s more than one link that matches the
text/URL, you can specify which one you want.
lastRequestSeconds

Seconds to Process Last Request

Return how many seconds (or fractions) the last request took.

The values returned have the same resolution as the results from time.clock.

Implementation:zope.schema.Field
Read Only:True
Required:True
Default Value:None
getControl(label=None, name=None, index=None)

Get a control from the page.

Only one of label and name may be provided. label searches form labels (including submit button values, per the HTML 4.0 spec), and name searches form field names.

Label value is searched as case-sensitive whole words within the labels for each control–that is, a search for ‘Add’ will match ‘Add a contact’ but not ‘Address’. A word is defined as one or more alphanumeric characters or the underline.

If no values are found, the code raises a LookupError.

If index is None (the default) and more than one field matches the search, the code raises an AmbiguityError. If an index is provided, it is used to choose the index from the ambiguous choices. If the index does not exist, the code raises a LookupError.

getForm(id=None, name=None, action=None, index=None)

Get a form from the page.

Zero or one of id, name, and action may be provided. If none are provided the index alone is used to determine the return value.

If no values are found, the code raises a LookupError.

If index is None (the default) and more than one form matches the search, the code raises an AmbiguityError. If an index is provided, it is used to choose the index from the ambiguous choices. If the index does not exist, the code raises a LookupError.

click()

click the link, going to the URL referenced

url

URL

The normalized URL of the link

Implementation:zope.schema.TextLine
Read Only:False
Required:False
Default Value:None
Allowed Type:str
attrs

Attributes

The attributes of the link tag

Implementation:zope.schema.Dict
Read Only:False
Required:False
Default Value:None
Allowed Type:dict
text

Text

The contained text of the link

Implementation:zope.schema.TextLine
Read Only:False
Required:False
Default Value:None
Allowed Type:str
tag

Tag

The tag name of the link (a or area, typically)

Implementation:zope.schema.TextLine
Read Only:False
Required:True
Default Value:None
Allowed Type:str
interface zope.testbrowser.interfaces.IForm[source]

An HTML form of the page.

action

Action

The action (or URI) that is opened upon submittance.

Implementation:zope.schema.TextLine
Read Only:False
Required:True
Default Value:None
Allowed Type:str
method

Method

The method used to submit the form.

Implementation:zope.schema.Choice
Read Only:False
Required:True
Default Value:None
enctype

Encoding Type

The type of encoding used to encode the form data.

Implementation:zope.schema.TextLine
Read Only:False
Required:True
Default Value:None
Allowed Type:str
name

Name

The value of the name attribute in the form tag, if specified.

Implementation:zope.schema.TextLine
Read Only:False
Required:True
Default Value:None
Allowed Type:str
id

Id

The value of the id attribute in the form tag, if specified.

Implementation:zope.schema.TextLine
Read Only:False
Required:True
Default Value:None
Allowed Type:str
getControl(label=None, name=None, index=None)

Get a control in the page.

Only one of label and name may be provided. label searches form labels (including submit button values, per the HTML 4.0 spec), and name searches form field names.

Label value is searched as case-sensitive whole words within the labels for each control–that is, a search for ‘Add’ will match ‘Add a contact’ but not ‘Address’. A word is defined as one or more alphanumeric characters or the underline.

If no values are found, the code raises a LookupError.

If index is None (the default) and more than one field matches the search, the code raises an AmbiguityError. If an index is provided, it is used to choose the index from the ambiguous choices. If the index does not exist, the code raises a LookupError.

submit(label=None, name=None, index=None, coord=(1, 1))

Submit this form.

The label, name, and index arguments select the submit button to use to submit the form. You may label or name, with index to disambiguate.

Label value is searched as case-sensitive whole words within the labels for each control–that is, a search for ‘Add’ will match ‘Add a contact’ but not ‘Address’. A word is defined as one or more alphanumeric characters or the underline.

The control code works identically to ‘get’ except that searches are filtered to find only submit and image controls.

interface zope.testbrowser.interfaces.IControl[source]

A control (input field) of a page.

name

Name

The name of the control.

Implementation:zope.schema.TextLine
Read Only:False
Required:True
Default Value:None
Allowed Type:str
value

Value

The value of the control

Implementation:zope.schema.Field
Read Only:False
Required:True
Default Value:None
type

Type

The type of the control

Implementation:zope.schema.Choice
Read Only:False
Required:True
Default Value:None
disabled

Disabled

Describes whether a control is disabled.

Implementation:zope.schema.Bool
Read Only:False
Required:False
Default Value:False
Allowed Type:bool
multiple

Multiple

Describes whether this control can hold multiple values.

Implementation:zope.schema.Bool
Read Only:False
Required:False
Default Value:False
Allowed Type:bool
clear()

Clear the value of the control.

interface zope.testbrowser.interfaces.IListControl[source]

Extends: zope.testbrowser.interfaces.IControl

A radio button, checkbox, or select control

options

Options

A list of possible values for the control.

Implementation:zope.schema.List
Read Only:False
Required:True
Default Value:None
Allowed Type:list
displayOptions

Options

A list of possible display values for the control.

Implementation:zope.schema.List
Read Only:False
Required:True
Default Value:None
Allowed Type:list
displayValue

Value

The value of the control, as rendered by the display

Implementation:zope.schema.Field
Read Only:False
Required:True
Default Value:None
getControl(label=None, value=None, index=None)

return subcontrol for given label or value, disambiguated by index if given. Label value is searched as case-sensitive whole words within the labels for each item–that is, a search for ‘Add’ will match ‘Add a contact’ but not ‘Address’. A word is defined as one or more alphanumeric characters or the underline.

controls

a list of subcontrols for the control. mutating list has no effect on control (although subcontrols may be changed as usual).

interface zope.testbrowser.interfaces.ISubmitControl[source]

Extends: zope.testbrowser.interfaces.IControl

click()

click the submit button

interface zope.testbrowser.interfaces.IImageSubmitControl[source]

Extends: zope.testbrowser.interfaces.ISubmitControl

click(coord=(1, 1))

click the submit button with optional coordinates

interface zope.testbrowser.interfaces.IItemControl[source]

a radio button or checkbox within a larger multiple-choice control

control

Control

The parent control element.

Implementation:zope.schema.Object
Read Only:False
Required:True
Default Value:None
Must Provide:zope.testbrowser.interfaces.IControl
disabled

Disabled

Describes whether a subcontrol is disabled.

Implementation:zope.schema.Bool
Read Only:False
Required:False
Default Value:False
Allowed Type:bool
selected

Selected

Whether the subcontrol is selected

Implementation:zope.schema.Bool
Read Only:False
Required:True
Default Value:None
Allowed Type:bool
optionValue

Value

The value of the subcontrol

Implementation:zope.schema.TextLine
Read Only:False
Required:False
Default Value:None
Allowed Type:str

Exceptions

exception zope.testbrowser.interfaces.AlreadyExpiredError[source]
exception zope.testbrowser.interfaces.ExpiredError[source]

The browser page to which this was attached is no longer active

zope.testbrowser.browser

Webtest-based Functional Doctest interfaces

Classes

class zope.testbrowser.browser.Browser(url=None, wsgi_app=None)[source]

A web user agent.

addHeader(key, value)[source]

See zope.testbrowser.interfaces.IBrowser

contents

See zope.testbrowser.interfaces.IBrowser

follow(*args, **kw)[source]

Select a link and follow it.

getControl(label=None, name=None, index=None)[source]

See zope.testbrowser.interfaces.IBrowser

getForm(id=None, name=None, action=None, index=None)[source]

See zope.testbrowser.interfaces.IBrowser

See zope.testbrowser.interfaces.IBrowser

goBack(count=1)[source]

See zope.testbrowser.interfaces.IBrowser

headers

See zope.testbrowser.interfaces.IBrowser

isHtml

See zope.testbrowser.interfaces.IBrowser

lastRequestSeconds

See zope.testbrowser.interfaces.IBrowser

open(url, data=None, referrer=None)[source]

See zope.testbrowser.interfaces.IBrowser

reload()[source]

See zope.testbrowser.interfaces.IBrowser

title

See zope.testbrowser.interfaces.IBrowser

toStr(s)[source]

Convert possibly unicode object to native string using response charset

url

See zope.testbrowser.interfaces.IBrowser