Programmable browser for functional black-box tests
Project description
zope.testbrowser provides an easy-to-use programmable web browser with special focus on testing. It is used in Zope, but it’s not Zope specific at all. For instance, it can be used to test or otherwise interact with any web site.
Detailed Documentation
Different Browsers
HTTP Browser
The zope.testbrowser.browser module exposes a Browser class that simulates a web browser similar to Mozilla Firefox or IE.
>>> from zope.testbrowser.browser import Browser >>> browser = Browser()
This version of the browser object can be used to access any web site just as you would do using a normal web browser.
WSGI Test Browser
There is also a special version of the Browser class which uses WebTest and can be used to do functional testing of WSGI applications. It can be imported from zope.testbrowser.wsgi:
>>> from zope.testbrowser.wsgi import Browser
>>> from wsgiref.simple_server import demo_app
>>> browser = Browser('http://localhost/', wsgi_app=demo_app)
>>> print browser.contents
Hello world!
...
To use this browser you have to:
use the wsgi extra of the zope.testbrowser egg,
You can also use it with zope layers by:
write a subclass of zope.testbrowser.wsgi.Layer and override the make_wsgi_app method,
use an instance of the class as the test layer of your test.
Example:
>>> import zope.testbrowser.wsgi >>> class SimpleLayer(zope.testbrowser.wsgi.Layer): ... def make_wsgi_app(self): ... return simple_app
Where simple_app is the callable of your WSGI application.
Bowser Usage
We will test this browser against a WSGI test application:
>>> from zope.testbrowser.ftests.wsgitestapp import WSGITestApplication >>> wsgi_app = WSGITestApplication()
An initial page to load can be passed to the Browser constructor:
>>> browser = Browser('http://localhost/@@/testbrowser/simple.html', wsgi_app=wsgi_app)
>>> browser.url
'http://localhost/@@/testbrowser/simple.html'
The browser can send arbitrary headers; this is helpful for setting the “Authorization” header or a language value, so that your tests format values the way you expect in your tests, if you rely on zope.i18n locale-based formatting or a similar approach.
>>> browser.addHeader('Authorization', 'Basic mgr:mgrpw')
>>> browser.addHeader('Accept-Language', 'en-US')
An existing browser instance can also open web pages:
>>> browser.open('http://localhost/@@/testbrowser/simple.html')
>>> browser.url
'http://localhost/@@/testbrowser/simple.html'
Once you have opened a web page initially, best practice for writing testbrowser doctests suggests using ‘click’ to navigate further (as discussed below), except in unusual circumstances.
The test browser complies with the IBrowser interface; see zope.testbrowser.interfaces for full details on the interface.
>>> from zope.testbrowser import interfaces >>> from zope.interface.verify import verifyObject >>> verifyObject(interfaces.IBrowser, browser) True
Page Contents
The contents of the current page are available:
>>> print browser.contents
<html>
<head>
<title>Simple Page</title>
</head>
<body>
<h1>Simple Page</h1>
</body>
</html>
Making assertions about page contents is easy.
>>> '<h1>Simple Page</h1>' in browser.contents True
Utilizing the doctest facilities, it also possible to do:
>>> browser.contents '...<h1>Simple Page</h1>...'
Note: Unfortunately, ellipsis (…) cannot be used at the beginning of the output (this is a limitation of doctest).
Checking for HTML
Not all URLs return HTML. Of course our simple page does:
>>> browser.open('http://localhost/@@/testbrowser/simple.html')
>>> browser.isHtml
True
But if we load an image (or other binary file), we do not get HTML:
>>> browser.open('http://localhost/@@/testbrowser/zope3logo.gif')
>>> browser.isHtml
False
HTML Page Title
Another useful helper property is the title:
>>> browser.open('http://localhost/@@/testbrowser/simple.html')
>>> browser.title
'Simple Page'
If a page does not provide a title, it is simply None:
>>> browser.open('http://localhost/@@/testbrowser/notitle.html')
>>> browser.title
However, if the output is not HTML, then an error will occur trying to access the title:
>>> browser.open('http://localhost/@@/testbrowser/zope3logo.gif')
>>> browser.title
Traceback (most recent call last):
...
BrowserStateError: not viewing HTML
Headers
As you can see, the contents of the browser does not return any HTTP headers. The headers are accessible via a separate attribute, which is an httplib.HTTPMessage instance (httplib is a part of Python’s standard library):
>>> browser.open('http://localhost/@@/testbrowser/simple.html')
>>> browser.headers
<httplib.HTTPMessage instance...>
The headers can be accessed as a string:
>>> print browser.headers Status: 200 OK Content-Length: 123 Content-Type: text/html;charset=utf-8
Or as a mapping:
>>> browser.headers['content-type'] 'text/html;charset=utf-8'
Controls
One of the most important features of the browser is the ability to inspect and fill in values for the controls of input forms. To do so, let’s first open a page that has a bunch of controls:
>>> browser.open('http://localhost/@@/testbrowser/controls.html')
Obtaining a Control
You look up browser controls with the ‘getControl’ method. The default first argument is ‘label’, and looks up the form on the basis of any associated label.
>>> control = browser.getControl('Text Control')
>>> control
<Control name='text-value' type='text'>
>>> browser.getControl(label='Text Control') # equivalent
<Control name='text-value' type='text'>
If you request a control that doesn’t exist, the code raises a LookupError:
>>> browser.getControl('Does Not Exist')
Traceback (most recent call last):
...
LookupError: label 'Does Not Exist'
If you request a control with an ambiguous lookup, the code raises an AmbiguityError.
>>> browser.getControl('Ambiguous Control')
Traceback (most recent call last):
...
AmbiguityError: label 'Ambiguous Control' matches:
<TextControl(ambiguous-control-name=First)>
<TextControl(ambiguous-control-name=Second)>
This is also true if an option in a control is ambiguous in relation to the control itself.
>>> browser.getControl('Sub-control Ambiguity')
Traceback (most recent call last):
...
AmbiguityError: label 'Sub-control Ambiguity' matches:
<SelectControl(ambiguous-subcontrol=[*, ambiguous])>
<Item name='ambiguous' id=None contents='Sub-control Ambiguity Exemplified' value='ambiguous' label='Sub-control Ambiguity Exemplified'>
Ambiguous controls may be specified using an index value. We use the control’s value attribute to show the two controls; this attribute is properly introduced below.
>>> browser.getControl('Ambiguous Control', index=0)
<Control name='ambiguous-control-name' type='text'>
>>> browser.getControl('Ambiguous Control', index=0).value
'First'
>>> browser.getControl('Ambiguous Control', index=1).value
'Second'
>>> browser.getControl('Sub-control Ambiguity', index=0)
<ListControl name='ambiguous-subcontrol' type='select'>
>>> browser.getControl('Sub-control Ambiguity', index=1).optionValue
'ambiguous'
Label searches are against stripped, whitespace-normalized, no-tag versions of the text. Text applied to searches is also stripped and whitespace normalized. The search finds results if the text search finds the whole words of your text in a label. Thus, for instance, a search for ‘Add’ will match the label ‘Add a Client’ but not ‘Address’. Case is honored.
>>> browser.getControl('Label Needs Whitespace Normalization')
<Control name='label-needs-normalization' type='text'>
>>> browser.getControl('label needs whitespace normalization')
Traceback (most recent call last):
...
LookupError: label 'label needs whitespace normalization'
>>> browser.getControl(' Label Needs Whitespace ')
<Control name='label-needs-normalization' type='text'>
>>> browser.getControl('Whitespace')
<Control name='label-needs-normalization' type='text'>
>>> browser.getControl('hitespace')
Traceback (most recent call last):
...
LookupError: label 'hitespace'
>>> browser.getControl('[non word characters should not confuse]')
<Control name='non-word-characters' type='text'>
Multiple labels can refer to the same control (simply because that is possible in the HTML 4.0 spec).
>>> browser.getControl('Multiple labels really')
<Control name='two-labels' type='text'>
>>> browser.getControl('really are possible')
<Control name='two-labels' type='text'>
>>> browser.getControl('really') # OK: ambiguous labels, but not ambiguous control
<Control name='two-labels' type='text'>
A label can be connected with a control using the ‘for’ attribute and also by containing a control.
>>> browser.getControl( ... 'Labels can be connected by containing their respective fields') <Control name='contained-in-label' type='text'>
Get also accepts one other search argument, ‘name’. Only one of ‘label’ and ‘name’ may be used at a time. The ‘name’ keyword searches form field names.
>>> browser.getControl(name='text-value') <Control name='text-value' type='text'> >>> browser.getControl(name='ambiguous-control-name') Traceback (most recent call last): ... AmbiguityError: name 'ambiguous-control-name' matches: <TextControl(ambiguous-control-name=First)> <TextControl(ambiguous-control-name=Second)> >>> browser.getControl(name='does-not-exist') Traceback (most recent call last): ... LookupError: name 'does-not-exist' >>> browser.getControl(name='ambiguous-control-name', index=1).value 'Second'
Combining ‘label’ and ‘name’ raises a ValueError, as does supplying neither of them.
>>> browser.getControl(label='Ambiguous Control', name='ambiguous-control-name') Traceback (most recent call last): ... ValueError: Supply one and only one of "label" and "name" as arguments >>> browser.getControl() Traceback (most recent call last): ... ValueError: Supply one and only one of "label" and "name" as arguments
Radio and checkbox fields are unusual in that their labels and names may point to different objects: names point to logical collections of radio buttons or checkboxes, but labels may only be used for individual choices within the logical collection. This means that obtaining a radio button by label gets a different object than obtaining the radio collection by name. Select options may also be searched by label.
>>> browser.getControl(name='radio-value')
<ListControl name='radio-value' type='radio'>
>>> browser.getControl('Zwei')
<ItemControl name='radio-value' type='radio' optionValue='2' selected=True>
>>> browser.getControl('One')
<ItemControl name='multi-checkbox-value' type='checkbox' optionValue='1' selected=True>
>>> browser.getControl('Tres')
<ItemControl name='single-select-value' type='select' optionValue='3' selected=False>
Characteristics of controls and subcontrols are discussed below.
Control Objects
Controls provide IControl.
>>> ctrl = browser.getControl('Text Control')
>>> ctrl
<Control name='text-value' type='text'>
>>> verifyObject(interfaces.IControl, ctrl)
True
They have several useful attributes:
the name as which the control is known to the form:
>>> ctrl.name 'text-value'the value of the control, which may also be set:
>>> ctrl.value 'Some Text' >>> ctrl.value = 'More Text' >>> ctrl.value 'More Text'the type of the control:
>>> ctrl.type 'text'a flag describing whether the control is disabled:
>>> ctrl.disabled Falseand a flag to tell us whether the control can have multiple values:
>>> ctrl.multiple False
Additionally, controllers for select, radio, and checkbox provide IListControl. These fields have four other attributes and an additional method:
>>> ctrl = browser.getControl('Multiple Select Control') >>> ctrl <ListControl name='multi-select-value' type='select'> >>> ctrl.disabled False >>> ctrl.multiple True >>> verifyObject(interfaces.IListControl, ctrl) True
‘options’ lists all available value options.
>>> ctrl.options ['1', '2', '3']‘displayOptions’ lists all available options by label. The ‘label’ attribute on an option has precedence over its contents, which is why our last option is ‘Third’ in the display.
>>> ctrl.displayOptions ['Un', 'Deux', 'Third']‘displayValue’ lets you get and set the displayed values of the control of the select box, rather than the actual values.
>>> ctrl.value [] >>> ctrl.displayValue [] >>> ctrl.displayValue = ['Un', 'Deux'] >>> ctrl.displayValue ['Un', 'Deux'] >>> ctrl.value ['1', '2']‘controls’ gives you a list of the subcontrol objects in the control (subcontrols are discussed below).
>>> ctrl.controls [<ItemControl name='multi-select-value' type='select' optionValue='1' selected=True>, <ItemControl name='multi-select-value' type='select' optionValue='2' selected=True>, <ItemControl name='multi-select-value' type='select' optionValue='3' selected=False>]The ‘getControl’ method lets you get subcontrols by their label or their value.
>>> ctrl.getControl('Un') <ItemControl name='multi-select-value' type='select' optionValue='1' selected=True> >>> ctrl.getControl('Deux') <ItemControl name='multi-select-value' type='select' optionValue='2' selected=True> >>> ctrl.getControl('Trois') # label attribute <ItemControl name='multi-select-value' type='select' optionValue='3' selected=False> >>> ctrl.getControl('Third') # contents <ItemControl name='multi-select-value' type='select' optionValue='3' selected=False> >>> browser.getControl('Third') # ambiguous in the browser, so useful Traceback (most recent call last): ... AmbiguityError: label 'Third' matches: <Item name='3' id=None contents='Tres' value='3' label='Third'> <Item name='3' id=None contents='Trois' value='3' label='Third'> <Item name='3' id='multi-checkbox-value-3' __label={'__text': 'Three\n '} checked='checked' name='multi-checkbox-value' type='checkbox' id='multi-checkbox-value-3' value='3'> <Item name='3' id='radio-value-3' __label={'__text': ' Drei'} type='radio' name='radio-value' value='3' id='radio-value-3'>
Finally, submit controls provide ISubmitControl, and image controls provide IImageSubmitControl, which extents ISubmitControl. These both simply add a ‘click’ method. For image submit controls, you may also provide a coordinates argument, which is a tuple of (x, y). These submit the forms, and are demonstrated below as we examine each control individually.
ItemControl Objects
As introduced briefly above, using labels to obtain elements of a logical radio button or checkbox collection returns item controls, which are parents. Manipulating the value of these controls affects the parent control.
>>> browser.getControl(name='radio-value').value
['2']
>>> browser.getControl('Zwei').optionValue # read-only.
'2'
>>> browser.getControl('Zwei').selected
True
>>> verifyObject(interfaces.IItemControl, browser.getControl('Zwei'))
True
>>> browser.getControl('Ein').selected = True
>>> browser.getControl('Ein').selected
True
>>> browser.getControl('Zwei').selected
False
>>> browser.getControl(name='radio-value').value
['1']
>>> browser.getControl('Ein').selected = False
>>> browser.getControl(name='radio-value').value
[]
>>> browser.getControl('Zwei').selected = True
Checkbox collections behave similarly, as shown below.
Controls with subcontrols–
Various Controls
The various types of controls are demonstrated here.
Text Control
The text control we already introduced above.
Password Control
>>> ctrl = browser.getControl('Password Control') >>> ctrl <Control name='password-value' type='password'> >>> verifyObject(interfaces.IControl, ctrl) True >>> ctrl.value 'Password' >>> ctrl.value = 'pass now' >>> ctrl.value 'pass now' >>> ctrl.disabled False >>> ctrl.multiple FalseHidden Control
>>> ctrl = browser.getControl(name='hidden-value') >>> ctrl <Control name='hidden-value' type='hidden'> >>> verifyObject(interfaces.IControl, ctrl) True >>> ctrl.value 'Hidden' >>> ctrl.value = 'More Hidden' >>> ctrl.disabled False >>> ctrl.multiple FalseText Area Control
>>> ctrl = browser.getControl('Text Area Control') >>> ctrl <Control name='textarea-value' type='textarea'> >>> verifyObject(interfaces.IControl, ctrl) True >>> ctrl.value ' Text inside\n area!\n ' >>> ctrl.value = 'A lot of\n text.' >>> ctrl.disabled False >>> ctrl.multiple FalseFile Control
File controls are used when a form has a file-upload field. To specify data, call the add_file method, passing:
A file-like object
a content type, and
a file name
>>> ctrl = browser.getControl('File Control') >>> ctrl <Control name='file-value' type='file'> >>> verifyObject(interfaces.IControl, ctrl) True >>> ctrl.value is None True >>> import cStringIO>>> ctrl.add_file(cStringIO.StringIO('File contents'), ... 'text/plain', 'test.txt')The file control (like the other controls) also knows if it is disabled or if it can have multiple values.
>>> ctrl.disabled False >>> ctrl.multiple FalseSelection Control (Single-Valued)
>>> ctrl = browser.getControl('Single Select Control') >>> ctrl <ListControl name='single-select-value' type='select'> >>> verifyObject(interfaces.IListControl, ctrl) True >>> ctrl.value ['1'] >>> ctrl.value = ['2'] >>> ctrl.disabled False >>> ctrl.multiple False >>> ctrl.options ['1', '2', '3'] >>> ctrl.displayOptions ['Uno', 'Dos', 'Third'] >>> ctrl.displayValue ['Dos'] >>> ctrl.displayValue = ['Tres'] >>> ctrl.displayValue ['Third'] >>> ctrl.displayValue = ['Dos'] >>> ctrl.displayValue ['Dos'] >>> ctrl.displayValue = ['Third'] >>> ctrl.displayValue ['Third'] >>> ctrl.value ['3']Selection Control (Multi-Valued)
This was already demonstrated in the introduction to control objects above.
Checkbox Control (Single-Valued; Unvalued)
>>> ctrl = browser.getControl(name='single-unvalued-checkbox-value') >>> ctrl <ListControl name='single-unvalued-checkbox-value' type='checkbox'> >>> verifyObject(interfaces.IListControl, ctrl) True >>> ctrl.value True >>> ctrl.value = False >>> ctrl.disabled False >>> ctrl.multiple True >>> ctrl.options [True] >>> ctrl.displayOptions ['Single Unvalued Checkbox'] >>> ctrl.displayValue [] >>> verifyObject( ... interfaces.IItemControl, ... browser.getControl('Single Unvalued Checkbox')) True >>> browser.getControl('Single Unvalued Checkbox').optionValue 'on' >>> browser.getControl('Single Unvalued Checkbox').selected False >>> ctrl.displayValue = ['Single Unvalued Checkbox'] >>> ctrl.displayValue ['Single Unvalued Checkbox'] >>> browser.getControl('Single Unvalued Checkbox').selected True >>> browser.getControl('Single Unvalued Checkbox').selected = False >>> browser.getControl('Single Unvalued Checkbox').selected False >>> ctrl.displayValue [] >>> browser.getControl( ... name='single-disabled-unvalued-checkbox-value').disabled TrueCheckbox Control (Single-Valued, Valued)
>>> ctrl = browser.getControl(name='single-valued-checkbox-value') >>> ctrl <ListControl name='single-valued-checkbox-value' type='checkbox'> >>> verifyObject(interfaces.IListControl, ctrl) True >>> ctrl.value ['1'] >>> ctrl.value = [] >>> ctrl.disabled False >>> ctrl.multiple True >>> ctrl.options ['1'] >>> ctrl.displayOptions ['Single Valued Checkbox'] >>> ctrl.displayValue [] >>> verifyObject( ... interfaces.IItemControl, ... browser.getControl('Single Valued Checkbox')) True >>> browser.getControl('Single Valued Checkbox').selected False >>> browser.getControl('Single Valued Checkbox').optionValue '1' >>> ctrl.displayValue = ['Single Valued Checkbox'] >>> ctrl.displayValue ['Single Valued Checkbox'] >>> browser.getControl('Single Valued Checkbox').selected True >>> browser.getControl('Single Valued Checkbox').selected = False >>> browser.getControl('Single Valued Checkbox').selected False >>> ctrl.displayValue []Checkbox Control (Multi-Valued)
>>> ctrl = browser.getControl(name='multi-checkbox-value') >>> ctrl <ListControl name='multi-checkbox-value' type='checkbox'> >>> verifyObject(interfaces.IListControl, ctrl) True >>> ctrl.value ['1', '3'] >>> ctrl.value = ['1', '2'] >>> ctrl.disabled False >>> ctrl.multiple True >>> ctrl.options ['1', '2', '3'] >>> ctrl.displayOptions ['One', 'Two', 'Three'] >>> ctrl.displayValue ['One', 'Two'] >>> ctrl.displayValue = ['Two'] >>> ctrl.value ['2'] >>> browser.getControl('Two').optionValue '2' >>> browser.getControl('Two').selected True >>> verifyObject(interfaces.IItemControl, browser.getControl('Two')) True >>> browser.getControl('Three').selected = True >>> browser.getControl('Three').selected True >>> browser.getControl('Two').selected True >>> ctrl.value ['2', '3'] >>> browser.getControl('Two').selected = False >>> ctrl.value ['3'] >>> browser.getControl('Three').selected = False >>> ctrl.value []Radio Control
This is how you get a radio button based control:
>>> ctrl = browser.getControl(name='radio-value')This shows the existing value of the control, as it was in the HTML received from the server:
>>> ctrl.value ['2']We can then unselect it:
>>> ctrl.value = [] >>> ctrl.value []We can also reselect it:
>>> ctrl.value = ['2'] >>> ctrl.value ['2']displayValue shows the text the user would see next to the control:
>>> ctrl.displayValue ['Zwei']This is just unit testing:
>>> ctrl <ListControl name='radio-value' type='radio'> >>> verifyObject(interfaces.IListControl, ctrl) True >>> ctrl.disabled False >>> ctrl.multiple False >>> ctrl.options ['1', '2', '3'] >>> ctrl.displayOptions ['Ein', 'Zwei', 'Drei'] >>> ctrl.displayValue = ['Ein'] >>> ctrl.value ['1'] >>> ctrl.displayValue ['Ein']The radio control subcontrols were illustrated above.
Image Control
>>> ctrl = browser.getControl(name='image-value') >>> ctrl <ImageControl name='image-value' type='image'> >>> verifyObject(interfaces.IImageSubmitControl, ctrl) True >>> ctrl.value '' >>> ctrl.disabled False >>> ctrl.multiple FalseSubmit Control
>>> ctrl = browser.getControl(name='submit-value') >>> ctrl <SubmitControl name='submit-value' type='submit'> >>> browser.getControl('Submit This') # value of submit button is a label <SubmitControl name='submit-value' type='submit'> >>> browser.getControl('Standard Submit Control') # label tag is legal <SubmitControl name='submit-value' type='submit'> >>> browser.getControl('Submit') # multiple labels, but same control <SubmitControl name='submit-value' type='submit'> >>> verifyObject(interfaces.ISubmitControl, ctrl) True >>> ctrl.value 'Submit This' >>> ctrl.disabled False >>> ctrl.multiple False
Using Submitting Controls
Both the submit and image type should be clickable and submit the form:
>>> browser.getControl('Text Control').value = 'Other Text'
>>> browser.getControl('Submit').click()
>>> print browser.contents
<html>
...
<em>Other Text</em>
<input type="text" name="text-value" id="text-value" value="Some Text" />
...
<em>Submit This</em>
<input type="submit" name="submit-value" id="submit-value" value="Submit This" />
...
</html>
Note that if you click a submit object after the associated page has expired, you will get an error.
>>> browser.open('http://localhost/@@/testbrowser/controls.html')
>>> ctrl = browser.getControl('Submit')
>>> ctrl.click()
>>> ctrl.click()
Traceback (most recent call last):
...
ExpiredError
All the above also holds true for the image control:
>>> browser.open('http://localhost/@@/testbrowser/controls.html') >>> browser.getControl('Text Control').value = 'Other Text' >>> browser.getControl(name='image-value').click() >>> print browser.contents <html> ... <em>Other Text</em> <input type="text" name="text-value" id="text-value" value="Some Text" /> ... <em>1</em> <em>1</em> <input type="image" name="image-value" id="image-value" src="zope3logo.gif" /> ... </html>>>> browser.open('http://localhost/@@/testbrowser/controls.html') >>> ctrl = browser.getControl(name='image-value') >>> ctrl.click() >>> ctrl.click() Traceback (most recent call last): ... ExpiredError
But when sending an image, you can also specify the coordinate you clicked:
>>> browser.open('http://localhost/@@/testbrowser/controls.html')
>>> browser.getControl(name='image-value').click((50,25))
>>> print browser.contents
<html>
...
<em>50</em>
<em>25</em>
<input type="image" name="image-value" id="image-value"
src="zope3logo.gif" />
...
</html>
Forms
Because pages can have multiple forms with like-named controls, it is sometimes necessary to access forms by name or id. The browser’s forms attribute can be used to do so. The key value is the form’s name or id. If more than one form has the same name or id, the first one will be returned.
>>> browser.open('http://localhost/@@/testbrowser/forms.html')
>>> form = browser.getForm(name='one')
Form instances conform to the IForm interface.
>>> verifyObject(interfaces.IForm, form) True
The form exposes several attributes related to forms:
The name of the form:
>>> form.name 'one'The id of the form:
>>> form.id '1'The action (target URL) when the form is submitted:
>>> form.action 'http://localhost/@@/testbrowser/forms.html'The method (HTTP verb) used to transmit the form data:
>>> form.method 'GET'
Besides those attributes, you have also a couple of methods. Like for the browser, you can get control objects, but limited to the current form…
>>> form.getControl(name='text-value') <Control name='text-value' type='text'>
…and submit the form.
>>> form.submit('Submit')
>>> print browser.contents
<html>
...
<em>First Text</em>
...
</html>
Submitting also works without specifying a control, as shown below, which is it’s primary reason for existing in competition with the control submission discussed above.
Now let me show you briefly that looking up forms is sometimes important. In the forms.html template, we have four forms all having a text control named text-value. Now, if I use the browser’s get method,
>>> browser.getControl(name='text-value')
Traceback (most recent call last):
...
AmbiguityError: name 'text-value' matches:
<TextControl(text-value=First Text)>
<TextControl(text-value=Second Text)>
<TextControl(text-value=Third Text)>
<TextControl(text-value=Fourth Text)>
>>> browser.getControl('Text Control')
Traceback (most recent call last):
...
AmbiguityError: label 'Text Control' matches:
<TextControl(text-value=Third Text)>
<TextControl(text-value=Fourth Text)>
I’ll always get an ambiguous form field. I can use the index argument, or with the getForm method I can disambiguate by searching only within a given form:
>>> form = browser.getForm('2')
>>> form.getControl(name='text-value').value
'Second Text'
>>> form.submit('Submit')
>>> browser.contents
'...<em>Second Text</em>...'
>>> form = browser.getForm('2')
>>> form.getControl('Submit').click()
>>> browser.contents
'...<em>Second Text</em>...'
>>> browser.getForm('3').getControl('Text Control').value
'Third Text'
The last form on the page does not have a name, an id, or a submit button. Working with it is still easy, thanks to a index attribute that guarantees order. (Forms without submit buttons are sometimes useful for JavaScript.)
>>> form = browser.getForm(index=3) >>> form.submit() >>> browser.contents '...<em>Fourth Text</em>...<em>Submitted without the submit button.</em>...'
If a form is requested that does not exists, an exception will be raised.
>>> form = browser.getForm('does-not-exist')
Traceback (most recent call last):
LookupError
If the HTML page contains only one form, no arguments to getForm are needed:
>>> oneform = Browser(wsgi_app=wsgi_app)
>>> oneform.open('http://localhost/@@/testbrowser/oneform.html')
>>> form = oneform.getForm()
If the HTML page contains more than one form, index is needed to disambiguate if no other arguments are provided:
>>> browser.getForm() Traceback (most recent call last): ValueError: if no other arguments are given, index is required.
Submitting a posts body directly
In addition to the open method, zope.testbrowser.testing.Browser has a post method that allows a request body to be supplied. This method is particularly helpful when testing Ajax methods.
Let’s visit a page that echos some interesting values from it’s request:
>>> browser.open('http://localhost/echo.html')
>>> print browser.contents
HTTP_ACCEPT_LANGUAGE: en-US
HTTP_CONNECTION: close
HTTP_HOST: localhost
HTTP_USER_AGENT: Python-urllib/2.4
PATH_INFO: /echo.html
REQUEST_METHOD: GET
Body: ''
Now, we’ll try a post. The post method takes a URL, a data string, and an optional content type. If we just pass a string, then a URL-encoded query string is assumed:
>>> browser.post('http://localhost/echo.html', 'x=1&y=2')
>>> print browser.contents
CONTENT_LENGTH: 7
CONTENT_TYPE: application/x-www-form-urlencoded
HTTP_ACCEPT_LANGUAGE: en-US
HTTP_CONNECTION: close
HTTP_HOST: localhost
HTTP_USER_AGENT: Python-urllib/2.4
PATH_INFO: /echo.html
REQUEST_METHOD: POST
x: 1
y: 2
Body: ''
The body is empty because it is consumed to get form data.
We can pass a content-type explicitly:
>>> browser.post('http://localhost/echo.html',
... '{"x":1,"y":2}', 'application/x-javascript')
>>> print browser.contents
CONTENT_LENGTH: 13
CONTENT_TYPE: application/x-javascript
HTTP_ACCEPT_LANGUAGE: en-US
HTTP_CONNECTION: close
HTTP_HOST: localhost
HTTP_USER_AGENT: Python-urllib/2.4
PATH_INFO: /echo.html
REQUEST_METHOD: POST
Body: '{"x":1,"y":2}'
Here, the body is left in place because it isn’t form data.
Performance Testing
Browser objects keep up with how much time each request takes. This can be used to ensure a particular request’s performance is within a tolerable range. Be very careful using raw seconds, cross-machine differences can be huge, pystones is usually a better choice.
>>> browser.open('http://localhost/@@/testbrowser/simple.html')
>>> browser.lastRequestSeconds < 10 # really big number for safety
True
>>> browser.lastRequestPystones < 10000 # really big number for safety
True
Handling Errors
Often WSGI middleware or the application itself gracefully handle application errors, such as invalid URLs:
>>> browser.open('http://localhost/invalid')
Traceback (most recent call last):
...
HTTPError: HTTP Error 404: Not Found
Note that the above error was thrown by mechanize and not by the application. For debugging purposes, however, it can be very useful to see the original exception caused by the application. In those cases you can set the handleErrors property of the browser to False. It is defaulted to True:
>>> browser.handleErrors True
So when we tell the application not to handle the errors,
>>> browser.handleErrors = False
we get a different, internal error from the application:
>>> browser.open('http://localhost/invalid')
Traceback (most recent call last):
...
NotFound: /invalid
- NB: Setting the handleErrors attribute to False will only change anything if
the WSGI application obeys the wsgi.handleErrors or paste.throw_errors WSGI environment variables. i.e. it does not catch and handle the original exception when these are set appropriately.
When the testbrowser is raising HttpErrors, the errors still hit the test. Sometimes we don’t want that to happen, in situations where there are edge cases that will cause the error to be predictably but infrequently raised. Time is a primary cause of this.
To get around this, one can set the raiseHttpErrors to False.
>>> browser.handleErrors = True >>> browser.raiseHttpErrors = False
This will cause HttpErrors not to propagate.
>>> browser.open('http://localhost/invalid')
The headers are still there, though.
>>> '404 Not Found' in str(browser.headers) True
If we don’t handle the errors, and allow internal ones to propagate, however, this flag doesn’t affect things.
>>> browser.handleErrors = False >>> browser.open('http://localhost/invalid') Traceback (most recent call last): ... NotFound: /invalid>>> browser.raiseHttpErrors = True
Hand-Holding
Instances of the various objects ensure that users don’t set incorrect instance attributes accidentally.
>>> browser.nonexistant = None Traceback (most recent call last): ... AttributeError: 'Browser' object has no attribute 'nonexistant'>>> form.nonexistant = None Traceback (most recent call last): ... AttributeError: 'Form' object has no attribute 'nonexistant'>>> control.nonexistant = None Traceback (most recent call last): ... AttributeError: 'Control' object has no attribute 'nonexistant'>>> link.nonexistant = None Traceback (most recent call last): ... AttributeError: 'Link' object has no attribute 'nonexistant'
HTTPS support
Depending on the scheme of the request the variable wsgi.url_scheme will be set correctly on the request:
>>> browser.open('http://localhost/echo_one.html?var=wsgi.url_scheme') >>> print browser.contents 'http'>>> browser.open('https://localhost/echo_one.html?var=wsgi.url_scheme') >>> print browser.contents 'https'
see http://www.python.org/dev/peps/pep-3333/ for details.
CHANGES
4.0.0 (2011-03-14)
LP #721252: AmbiguityError now shows all matching controls.
Integrate with WebTest. zope.testbrowser.wsgi.Browser is a Browser implementation that uses webtest.TestApp to drive a WSGI application. This this replaces the wsgi_intercept support added in 3.11.
Re-write the test application as a pure WSGI application using WebOb. Run the existing tests using the WebTest based Browser
Move zope.app.testing based Browser into zope.app.testing (leaving backwards compatibility imports in-place). Released in zope.app.testing 3.9.0.
3.11.1 (2011-01-24)
Fixing brown bag release 3.11.0.
3.11.0 (2011-01-24)
Added wsgi_intercept support (came from zope.app.wsgi.testlayer).
3.10.4 (2011-01-14)
Move the over-the-wire.txt doctest out of the TestBrowserLayer as it doesn’t need or use it.
Fix test compatibility with zope.app.testing 3.8.1.
3.10.3 (2010-10-15)
Fixed backwards compatibility with zope.app.wsgi.testlayer.
3.10.2 (2010-10-15)
Fixed Python 2.7 compatibility in Browser.handleErrors.
3.10.1 (2010-09-21)
Fixed a bug that caused the Browser to keep it’s previous contents The places are: - Link.click() - SubmitControl.click() - ImageControl.click() - Form.submit()
Also adjusted exception messages at the above places to match pre version 3.4.1 messages.
3.10.0 (2010-09-14)
LP #98437: use mechanize’s built-in submit() to submit forms, allowing mechanize to set the “Referer:” (sic) header appropriately.
Fixed tests to run with zope.app.testing 3.8 and above.
3.9.0 (2010-05-17)
LP #568806: Update dependency mechanize >= 0.2.0, which now includes the ClientForm APIs. Remove use of urllib2 APIs (incompatible with mechanize 0.2.0) in favor of mechanize equivalents. Thanks to John J. Lee for the patch.
Use stdlib doctest module, instead of zope.testing.doctest.
Caution: This version is no longer fully compatible with Python 2.4: handleErrors = False no longer works.
3.8.1 (2010-04-19)
Pinned dependency on mechanize to prevent use of the upcoming 0.2.0 release before we have time to adjust to its API changes.
LP #98396: testbrowser resolves relative URLs incorrectly.
3.8.0 (2010-03-05)
Added follow convenience method which gets and follows a link.
3.7.0 (2009-12-17)
Moved zope.app.testing dependency into the scope of the PublisherConnection class. Zope2 specifies its own PublisherConnection which isn’t dependent on zope.app.testing.
Fixed LP #419119: return None when the browser has no contents instead of raising an exception.
3.7.0a1 (2009-08-29)
Remove dependency on zope.app.publisher in favor of zope.browserpage, zope.browserresource and zope.ptresource.
Remove dependencies on zope.app.principalannotation and zope.securitypolicy by using the simple PermissiveSecurityPolicy. We aren’t testing security in our tests.
Replaced the testing dependency on zope.app.zcmlfiles with explicit dependencies of a minimal set of packages.
Remove unneeded zope.app.authentication from ftesting.zcml.
Test dependency on zope.securitypolicy instead of its app variant.
3.6.0a2 (2009-01-31)
Test dependency on zope.site.folder instead of zope.app.folder.
Remove useless test dependency in zope.app.component.
3.6.0a1 (2009-01-08)
Author e-mail to zope-dev rather than zope3-dev.
New lines are no longer stripped in XML and HTML code contained in a textarea; fix requires ClientForm >= 0.2.10 (LP #268139).
Added cookies attribute to browser for easy manipulation of browser cookies. See brief example in main documentation, plus new cookies.txt documentation.
3.5.1 (2008-10-10)
Provide a work around for a mechanize/urllib2 bug on Python 2.6 missing ‘timeout’ attribute on ‘Request’ base class.
Provide a work around for a mechanize/urllib2 bug in creating request objects that won’t handle fragment URLs correctly.
3.5.0 (2008-03-30)
Added a zope.testbrowser.testing.Browser.post method that allows tests to supply a body and a content type. This is handy for testing Ajax requests with non-form input (e.g. JSON).
Remove vendor import of mechanize.
Fix bug that caused HTTP exception tracebacks to differ between version 3.4.0 and 3.4.1.
Workaround for bug in Python Cookie.SimpleCookie when handling unicode strings.
Fix bug introduced in 3.4.1 that created incompatible tracebacks in doctests. This necessitated adding a patched mechanize to the source tree; patches have been sent to the mechanize project.
Fix https://bugs.launchpad.net/bugs/149517 by adding zope.interface and zope.schema as real dependencies
Fix browser.getLink documentation that was not updated since the last API modification.
Move tests for fixed bugs to a separate file.
Removed non-functional and undocumented code intended to help test servers using virtual hosting.
3.4.2 (2007-10-31)
Resolve ZopeSecurityPolicy deprecation warning.
3.4.1 (2007-09-01)
Updated to mechanize 0.1.7b and ClientForm 0.2.7. These are now pulled in via egg dependencies.
zope.testbrowser now works on Python 2.5.
3.4.0 (2007-06-04)
Added the ability to suppress raising exceptions on HTTP errors (raiseHttpErrors attribute).
Made the tests more resilient to HTTP header formatting changes with the REnormalizer.
3.4.0a1 (2007-04-22)
Initial release as a separate project, corresponds to zope.testbrowser from Zope 3.4.0a1
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
