tclwebtest - brief documentation

API Documentation

This is a brief description of the commands that tclwebtest offers. Use those and any other desired tcl commands to write a .test file, and run it like this: tclwebtest yourfilename.test.

There is an overview of the output framework too.


do_request url
Do a request for the specified url and store the result. Upon first invocation url must be absolute, like for example "http://testserver/demo". Subsequent calls can be done with relative url's. Supported protocols are http: and file:. Due to a bug ports other then 80 do not work (sigh).
assert ?-fail? boolean_expression
Test if the boolean_expression is true (false when -fail is set), and throw an assertion_failed otherwise. For example: assert { [llength $some_list] > 0 }
assert text ?-fail? expression
Test if the expression matches the user viewable text of the result page (using regexp -nocase).


link find ?search_args?
Find and return the first link that matches search_args (or the first link if no search_args are given). Valid modifiers for search_args:
~c (default). content, the text between the <a></a> tags
~u url (content of the href attribute)
~f full html source
For a deeper explanation of the link commands, take a look at matching.txt.
link follow ?search_args?
calls link find, and then do_request with the result.

Form handling

tclwebtest keeps two internal pointers, current_form and current_field. Operations that do not explicitely specify a target operate on the element of the current pointer. When such an operation is called before a current form or field is set, then the pointer will be set to the first possible value. As a result, the first (or the only) form is always the default.

Setting field values (via field fill / check / uncheck / select) does the following: it searches for the first applicable field (e.g. a field check searches a checkbox) starting from the current_field position, sets the value, and then advances the current_field pointer by one. Thus it is possible to handle a form of two text entries and a checkbox using this brief (and hopefully convenient) syntax:

field fill "foo"
field fill "bar"
field check
form submit

This assumes that there are two text (or textarea or password) fields, followed by one checkbox. The commands would have to be reordered if the form items were in another order.

field find ?search_args?
Find the first field that matches search_args , or the first user modifyable field (e.g. not of type hidden nor submit) when no search_args are given, and set the current_field pointer to it. Valid modifiers for search_args:
~c (default). caption
~t the type, for example text or select
~v current value
~n name
~f full html source

Returns the field as a list suitable for array set.
field fill text ?search_args?
Fill text into a field that takes text as input - either text, textarea or password.
field check / field uncheck ?search_args?
Check or uncheck a checkbox field.
field select text ?search_args?
Select a value of a radio button or a select field. If it is a multiple select then deselect the others.
field multiselect list_of_choices ?search_args?
Add one or more values to the current selection of a multiple select field.
field deselect ?search_args?
Delete the selection of a multiple select field. (Not possible with drop-downs and radio buttons)
form find ?search_args?
Set the current_form pointer to the form that matches or to the first form when called without search_args. Valid modifiers for search_args:

~c (default). The user viewable text (content) that is between the <form></form> tags.
~a the form's action
~m method - either get or post, in lower case
~f the full html source of the form

Returns the form as a list suitable for array set.
form submit
Submit the current form. Invokes form find if no current form has previously been set.

Matching expressions

tclwebtest uses a strange syntax for expression matching in the form and link commands, which is inspired by the mutt mailclient. This allows to differentiate between the various attributes of html elements that are parsed by tclwebtest.

E.g. a link contains the three attributes url, content (=user viewable text) and full html source. By default, tclwebtest searches in content, so you can simply say link find "login" to search for a link that contains specific text. If you rather want to search for a part of the url, add the ~u modifier, like this: link find ~u "/register/login".

If there are several subexpressions, they all have to match (read: AND). NOT can be assigned to a subexpression by prepending a "!".

For example, to find the first link that has "add-to-cart" but not "substract" as part of its url and that contains "pizza" in the user viewable text:
link find ~u "add-to-cart" ! ~u "substract" "pizza"

All text matching is done with case insensitive regular expressions (calling regexp -nocase). Note that because of this you have to escape special characters, such as the ".". Nesting of expressions with braces and OR is not implemented.


cookies all
Return all cookies that are currently used in this session
cookies persistent
Return all persistent cookies, e.g. those that the browser would store on the harddisk, in a name/value paired list
cookies set cookie_list
Set the currently used cookies of this session to cookie_list . Typically used to test persistent cookies, for example those of a permanent login. cookie_list must be formatted like the output of cookies persistent.


response text
Returns the user viewable part of the response page
response body
Returns the full html source of the response page
response status
Returns the http status code of the last response (e.g. 200, 304, 404, ...). Note that do_request must be told explicitely to not complain about error http codes, e.g. 404 and 500
response headers
Returns the http headers that the server sent

Tcl level

Note that the test scripts will be evaluated in their own tcl level, not in the global level. Thus if you want to set/access global variables you need to declare them like this:
global some_global_var
puts $some_global_var

Tilmann Singer
Last modified: Fri Aug 22 16:34:05 CEST 2003