zope.testbrowser 3.4.1

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'

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'

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'
>>> 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
  False
  

• and 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'
  

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
  False
  

• Hidden 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
  False
  

• Text 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
  False
  

• File 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
  False
  

• Selection 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
  True
  

• Checkbox 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
  False
  

• Submit 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>

Spaces in URL

When URLs have spaces in them, they’re handled correctly (before the bug was fixed, you’d get “ValueError: too many values to unpack”):

>>> browser.open('http://localhost/@@/testbrowser/navigate.html')
>>> browser.getLink('Spaces in the URL').click()

.goBack() Truncation

The .goBack() method used to truncate the .contents.

>>> browser.open('http://localhost/@@/testbrowser/navigate.html')
>>> actual_length = len(browser.contents)

>>> browser.open('http://localhost/@@/testbrowser/navigate.html')
>>> browser.open('http://localhost/@@/testbrowser/simple.html')
>>> browser.goBack()
>>> len(browser.contents) == actual_length
True