Form handling

Getting a form

If you have a single html form in your page, just use the .form attribute:

>>> res = app.get('/form.html')
>>> form = res.form

If you have more then one HTML form in your page, use the .forms property and access via the form index:

>>> form = res.forms[0]

Or the form id:

>>> form = res.forms['myform']

You can check form attributes:

>>> print(
>>> print(form.action)
>>> print(form.method)

Filling a form

You can fill out and submit forms from your tests. Fields are a dict like object:

>>> # dict of fields
>>> form.fields.items() 
[(u'text', [<Text name="text">]), ..., (u'submit', [<Submit name="submit">])]

You can check the current value:

>>> print(form['text'].value)

Then you fill it in fields:

>>> form['text'] = 'Bar'
>>> # When names don't point to a single field:
>>> form.set('text', 'Bar', index=0)

Field types

Input and textarea fields

>>> print(form['textarea'].value)
Some text
>>> form['textarea'] = 'Some other text'

You can force the value of an hidden field:

>>> form['hidden'].force_value('2')

Select fields

Simple select:

>>> print(form['select'].value)
>>> form['select'] = 'option1'

Select multiple:

>>> print(form['multiple'].value) 
['option2', 'option3']
>>> form['multiple'] = ['option1']

You can select an option by its text with .select():

>>> form['select'].select(text="Option 2")
>>> print(form['select'].value)

For select multiple use .select_multiple():

>>> form['multiple'].select_multiple(texts=["Option 1", "Option 2"])
>>> print(form['multiple'].value) 
['option1', 'option2']

Select fields can only be set to valid values (i.e., values in an <option>) but you can also use .force_value() to enter values not present in an option.

>>> form['select'].force_value(['optionX'])
>>> form['multiple'].force_value(['optionX'])


You can check if the checkbox is checked and is value:

>>> print(form['checkbox'].checked)
>>> print(form['checkbox'].value)

You can change the status with the value:

>>> form['checkbox'] = True

Or with the checked attribute:

>>> form['checkbox'].checked =True

If the checkbox is checked then you'll get the value:

>>> print(form['checkbox'].checked)
>>> print(form['checkbox'].value)
checkbox 1

If the checkbox has no value then it will be 'on' if you checked it:

>>> print(form['checkbox2'].value)
>>> form['checkbox2'].checked = True
>>> print(form['checkbox2'].value)

If there are multiple checkboxes of the same name, you can assign a list to that name to check all the checkboxes whose value is present in the list:

>>> form['checkboxes'] = ['a', 'c']
>>> print(form.get('checkboxes', index=0).value)
>>> print(form.get('checkboxes', index=1).value)
>>> print(form.get('checkboxes', index=2).value)


>>> print(form['radio'].value)
Radio 2
>>> form['radio'] = 'Radio 1'


You can deal with file upload by using the Upload class:

>>> from webtest import Upload
>>> form['file'] = Upload('README.rst')
>>> form['file'] = Upload('README.rst', b'data')
>>> form['file'] = Upload('README.rst', b'data', 'text/x-rst')

If the file field has a multiple parameter, you can pass a list of Upload:

>>> from webtest import Upload
>>> form['files'] = [
...    Upload('README.rst'),
...    Upload('LICENSE.rst'),
... ]

Submit a form

Then you can submit the form:

>>> # Submit with no particular submit button pressed:
>>> res = form.submit()
>>> # Or submit a button:
>>> res = form.submit('submit')
>>> print(res)
Response: 200 OK
Content-Type: text/plain

You can also select a specific submit button by its index:

>>> res = form.submit('submit', index=1)
>>> print(res)
Response: 200 OK
Content-Type: text/plain
submit=Submit 2

And you can select it by its value:

>>> res = form.submit('submit', value="Submit 2")
>>> print(res)
Response: 200 OK
Content-Type: text/plain
submit=Submit 2