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

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

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.

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

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

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

url

URL

The URL the mapping is currently exposing.

Implementation

zope.schema.URI

Read Only

False

Required

True

Default Value

None

Allowed Type

str

interface zope.testbrowser.interfaces.IBrowser[source]

A Programmatic Web Browser.

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.

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

cookies

Cookies

An ICookies mapping for the browser’s current URL.

Implementation

zope.schema.Field

Read Only

False

Required

True

Default Value

None

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

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.

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.

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.

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

headers

Headers

Headers of the HTTP response; a httplib.HTTPMessage.

Implementation

zope.schema.Field

Read Only

False

Required

True

Default Value

None

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

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

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.

title

Title

Title of the displayed page

Implementation

zope.schema.TextLine

Read Only

False

Required

False

Default Value

None

Allowed Type

str

url

URL

The URL the browser is currently showing.

Implementation

zope.schema.URI

Read Only

False

Required

True

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

click()

click the link, going to the URL referenced

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

text

Text

The contained text of the link

Implementation

zope.schema.TextLine

Read Only

False

Required

False

Default Value

None

Allowed Type

str

url

URL

The normalized URL of the link

Implementation

zope.schema.TextLine

Read Only

False

Required

False

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

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

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.

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

method

Method

The method used to submit the form.

Implementation

zope.schema.Choice

Read Only

False

Required

True

Default Value

None

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

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.

clear()

Clear the value of the control.

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

name

Name

The name of the control.

Implementation

zope.schema.TextLine

Read Only

False

Required

True

Default Value

None

Allowed Type

str

type

Type

The type of the control

Implementation

zope.schema.Choice

Read Only

False

Required

True

Default Value

None

value

Value

The value of the control

Implementation

zope.schema.Field

Read Only

False

Required

True

Default Value

None

interface zope.testbrowser.interfaces.IListControl[source]

Extends: zope.testbrowser.interfaces.IControl

A radio button, checkbox, or select control

controls

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

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.

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

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

optionValue

Value

The value of the subcontrol

Implementation

zope.schema.TextLine

Read Only

False

Required

False

Default Value

None

Allowed Type

str

selected

Selected

Whether the subcontrol is selected

Implementation

zope.schema.Bool

Read Only

False

Required

True

Default Value

None

Allowed Type

bool

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

property 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

property headers

See zope.testbrowser.interfaces.IBrowser

property isHtml

See zope.testbrowser.interfaces.IBrowser

property 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

property title

See zope.testbrowser.interfaces.IBrowser

toStr(s)[source]

Convert possibly unicode object to native string using response charset

property url

See zope.testbrowser.interfaces.IBrowser