| API Documentation |
.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).
Links
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
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
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