tclwebtest API documentation

Test args, a required boolean expresion (and only one). Throws assertion_failed if it's false. Usually args is a comparison.
Examples:
    assert { $val == "foo" }
    assert text "Hello world"
    assert full "body>here"
    assert -fail { 0 == 1 }
    assert text -fail "Do not find me"
    assert full -fail "<not"
    

Return to index

::tclwebtest::assertion_failed (public)

::tclwebtest::assertion_failed assertionMsg

Usually called by tclwebtest, this procedure will raise an error with the messsage assertionMsg, which will be caught by a test unit and written to the standard output. There will be no error code.

Parameters:
assertionMsg

Return to index

::tclwebtest::cookies (public)

::tclwebtest::cookies command [ cookies_to_add ]

Parameters:
command - Specify one of the commands: clientvalue, all, persistent, set, clear.

clientvalue

A string that is the concatenation of all cookies that this http client wants to set. E.g. the value of the "Cookie: " http header.

all

Return all cookies that are currently used in this session.

persistent

Return all persistent cookies, e.g. those that the browser would store on the harddisk, in a name/value paired list.

set

Set the currently used cookies of this session to args.Typically used to test persistent cookies, for example those of a permanent login. args must be formatted like the output of cookies persistent.

clear

Clears all the cookies from memory.

cookies_to_add (optional)

Return to index

::tclwebtest::debug (public)

::tclwebtest::debug [ -lib ] msg

Emit the message to stdout, even if logging output is redirected to a file. Intended to be used when writing tests. Its only advantage over using puts is that it does not have to be deleted when writing the test is finished. However, if the variable ::tclwebtest::in_memory exists (through the previous execution of test_run), this procedure will route it's message through ::tclwebtest::log, thus allowing all output to be redirected to a memory string.

Switches:
-lib (boolean) (optional)

Parameters:
msg

Return to index

::tclwebtest::do_request (public)

::tclwebtest::do_request [ -followequiv ] [ -nocomplain ] \
    [ -nocomplain_list nocomplain_list ] [ -noredirect ] \
    [ -files files ] [ -enctype enctype ] url [ query_key_values ]

Do an http request and store everything in the current session. Returns the URL it has reached, which can be different from your request if there were redirections.
Expects a sane reply from the server, e.g. no status "500 Internal Server Error" or 404's and throws an assertion_failed otherwise. Here you have a list of possible http error codes.
If you have problems with URL's that are on another port than at the standard http port 80, look at the tcl bug #452217 at sourceforge, related to duplicate Host: headers.
Switches:
-followequiv (boolean) (defaults to "0") (optional) - follow redirects that are specified inside the html code with the http-equiv tag (for weird websites)
-nocomplain (boolean) (defaults to "0") (optional) - don't fail on 404's and other errors
-nocomplain_list (optional) - a more specialised version of -nocomplain, this parameter accepts a list of the error codes you explicitly want to ignore, and it will fail with those error codes not included in your list. If -nocomplain is present in the request, this parameter is ignored completely. Example:
    do_request -nocomplain {301 401} url
    
-noredirect (boolean) (defaults to "0") (optional) - don't follow server redirections. This is useful for example if you want to verify the redirection chain of steps of a specific site and see the values of the cookies set at every new step. Also useful if you wan't to make sure the url you are getting is the one you requested. Example:
    set original http://slashdot.org/
    set new [do_request $original]
    assert { $new == $original }
    
-files (optional)
-enctype (defaults to "application/x-www-form-urlencoded") (optional)
Parameters:
url - the url to be requested. Examples: http://openacs.org/register/, /foo/bar/some_page.html, some_page.html, file:///tmp/my_test_file.html.
query_key_values (optional) - list of query elements (in the format: key value key value ...) for a POST request. If not set then the request will be a GET, otherwise a POST.

Return to index

::tclwebtest::field (public)

::tclwebtest::field command [ args... ]

tclwebtest keeps an internal pointer, current_form. 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 field is set, then the pointer will be set to the first possible value. As a result, the first (or the only) field 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" ~n fieldname field fill -append "baz" 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.
Parameters:
command - Specify one of the commands: check / unckeck a single checkbox, check / unckeck a group of checkboxes with common name, current, fill, find, select, multiselect, deselect. get_*,
find
Find the first field that matches args , or the first user modifyable field (e.g. not of type hidden nor submit) when no args are given, and set the current_field pointer to it. Valid modifiers for args:
~c (default). caption
~t the type, can be text, textarea, password, hidden, radio, checkbox, select or submit
~v current value
~n name
~f full html source
Returns the field as a list suitable for array set. For a deeper explanation of the matching syntax, take a look at the documentation of link find. Examples:
    field find "title"
    field find "Start Time 6:00"
    field find "End Time"
    field find "Description"
    
all

Returns a list that contains all data of all fields.

current

Used to set or get the value of the currently selected form field. This is a pointer value, with 0 being the first field, 1 the second, etc. When no ?value? is given, the pointer is returned, otherwise set. Usually you will prefer to use field find args to select form fields.

fill
Fill args into a field that takes text as input - either text, textarea or password. It also moves the current_field pointer to the next field. By default tclwebtest will replace the content of the field, but you can specify the optional boolean parameter -append to append the selected text to the value the form currently contains. Example:
field fill -append { and some more options...}
If you specify a pattern the first field that matches will be filled instead of the current_field. The pattern goes at the end of the command, after the new value. Example:
field fill "bar" ~n fieldname
check / uncheck

Check or uncheck the currently selected checkbox field.

select

Select a value of a radio button or a select field. If it is a multiple select then deselect the others. You can select a specific index (starting from 0) of the select field with the -index parameter. If you want to know the options of the select, use field get_choices. This returns a list of pairs in the form value/text, where value is equal to text if the HTML of the <option> tag doesn't have a value attribute.

multiselect

Add one or more values to the current selection of a multiple select field. If a value is not found in the selection box, you will get an assertion error indicating which values are available, and which were the ones you asked and weren't found.

deselect

Delete the selection of a multiple select field. (Not possible with drop-downs and radio buttons)

get_*

Returns the specified attribute of a form field. Typical attributes you can retrieve from most fields are name, value, type and full. The availability of these and other attributes depends on the HTML code used by the field.

Return to index

::tclwebtest::form (public)

::tclwebtest::form command [ args... ]

tclwebtest keeps an internal pointer, current_form. 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.
Parameters:
command - Specify one of the commands: find, submit, current, get_*, all.
find
Set the current_form pointer to the form that matches or to the first form when called without args. Valid modifiers for 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
~n name of the form
~f the full html source of the form

Returns the form as a list suitable for array set. For a deeper explanation of the matching syntax, take a look at the documentation of link find. Examples:
    form find "dropdown"
    form find ~n "form1"
    
submit
Submit the current form. Invokes form find if no current form has previously been set. You can use this without parameters (only the first submit button of the form will be used to build the query) or specify a regular expression to select the submit button you want to use/push. You can also use the search modifiers like with form find. Examples:
# required to avoid getting forbidden access (403) user_agent_id "Custom mozilla" # get number of found entries for tclwebtest do_request http://www.google.com/ field fill tclwebtest form submit # go directly to the first entry do_request http://www.google.com/ field fill tclwebtest form submit {feeling lucky}
current
Returns the currently selected form. Example:
    # the third form
    form find "firma"
    assert { [form current] == 2 }
    
get_*

Returns the specified attribute of a form. TODO write a selftest for this.

all

Return a list of all forms.

Return to index

::tclwebtest::http_auth (public)

::tclwebtest::http_auth url_prefix username password

Registers in an internal global variable the username and password which should be used for pages requiring basic http autorization and which match url_prefix. You can assign only one username and password per url_prefix, although you can have register multiple url prefixes if each matches a different directory. Matches are ordered in length and descending order.
Note: This function depends on the availability of the base64 tcl package in your working environment. If it can not be sourced, a fake version of base64::encode will be used instead, which doesn't work notifies the fake use in the final log during execution of the test units.

Parameters:
url_prefix - the part of the url which has to match the following do_request commands in order to use http authentication.
username - the username you would use to authenticate. Only one username is allowed per url_prefix. If username is the empty string, the url_prefix will be unregistered.
password - the associated password for the combination of url_prefix and username.

Return to index

::tclwebtest::init (public)

::tclwebtest::init

Defines all tclwebtest wide variables that carry state information and sets them to a default value. To be used upon initialization and to reset the variables. The variables will exist in the ::tclwebtest:: namespace.

When running tclwebtest normally from a shell don't need to call this explicitely, it will be called during the first call of package require. If you are running tclwebtest from within AOLServer however you need to call ::tclwebtest::init explicitely in the beginning of your session because the connection thread might have been reused from the previous connection and could contain old variable values.

Return to index

::tclwebtest::known_bug (public)

::tclwebtest::known_bug [ -abort ]

There should be something like this that can be wrapped around some asserts like this:
    assert bla    # still good
    known_bug {
        assert bli
        assert blu
    }
    
which would mean bli and blu are known bugs. This proc could then include the wrapped code in some reporting.
It should also support aborting the whole test, so it can be put in the beginning of a test file (makes sense when several test files are run at once)

Switches:
-abort (boolean) (defaults to "0") (optional)

Return to index

::tclwebtest::link (public)

::tclwebtest::link command [ args... ]

Search for the first link in the extracted links that matches the given criteria and return an index-value pair list with it's contents, which can be converted to an array if you want to extract specific attributes manually. If there is no link that matches, throws assertion_failed. Example of retrieving links, which you could use with do_request to create a simple web crawler:
    link reset_current
    while { ![catch { link find -next } ] } {
        debug "found a link: [link get_text] to [link get_url]"
    }
    
Parameters:
command - Specify one of the commands: find, follow, all, reset_current, current, get_*.
find
Find and return the first link that matches args (or the first link if no args are given). Valid modifiers for args:
~c (default). content, the text between the <a></a> tags
~u url (content of the href attribute)
~f full html source

Additionally, you can use the following switches in args:

-index

???

-next

Used alone to loop throught available links. If current_link is the last link of the page, it will throw assertion_failed unless you are using the switch -fail too.

-fail

Negates the outcome, e.g. if a link is searched and not found, it won't throw assertion_failed, if the search was negated, then assertion_failed would be thrown, etc.

Matching syntax
The syntax of the matching functionality is inspired by the filter function in the Mutt mailclient. A list of arguments can be given as search criteria. When an argument is the "~" followed by a single character it acts as modifier that determines in which data field the following argument has to match. There is always a default data field.
So e.g. a hyperlink has the data fields content (the text between the <a>...</a> tags), url (the href attribute) and full (the full html source of that link). content is the default data field, so you can search for a link that contains some text like that:
    link find "sometext"
    
If you are looking for a specific url add the ~u modifier:
    link find ~u "/some/url"
    
Several search criteria are automatically concatenated with AND. So you can search for:
    link find "sometext" ~u "/some/url" "someothertext" ~f "<a[^>]+class=\"?someclass\"?[^>]>"
    
All those attributes have to match - the link must contain "sometext" AND "someothertext" in its text, point to the specified url AND must have a class attribute. Note that e.g. the class attribute is not parsed in a specified data field, so it has to be retrieved by searching the full html source of the field (but at least its possible to search for it at all). Search criterias can contain a "!" to specify that the following argument must NOT match. "!" can optionally be prepended or followed by a "~" modifier. For example:
    link find "sometext" ! ~u "/but/not/this/url"
    
The matching will always be done with "regexp -nocase". I wonder if case sensitive matching will ever be necessary for website testing. See the proc find_in_array_list for the matching implementation.
Currently search arguments are appended at the end of the command and get parsed into the args parameter of the proc. This allows for the maybe more convenient syntax:
    link find "some text with spaces" ~u "/some/url"
    
as opposed to putting everything in a seperate list:
    link find { "some text with spaces" ~u "/some/url" }
    
Commands supporting this behaviour are find, form and field.
follow
this is the same like doing link find (which means that you can use a regular expression as parameter), and then do_request with the previous result. Example:
    link follow "Download"
    link follow "Back to contents"
    link follow ~u {em[[:alpha:]]+sa}
    
Note that after this command you can get the current URL with response url, useful if you followed a link by text and you want to store/verify the url tclwebtest chose.
all
Returns all links. Example:
    assert { [llength [link all]] == 3 }

    do_request some_url
    
    foreach { data } [link all] {
        array set one_link $data
        log "found link, dumping contents"
        foreach { key } [array names one_link] {
            log "  $key: $a_link($key)"
        }
    }
    
Note that this example is different from the previous one which retrieves all links, in that here you can't use the get command to extract only the text of a link, because link works like a state machine, and after the all command it points at the last link of the current page.
The only keys you can rely on being available are url, content and full. You might see more when you log all the packaged data, but these are for internal use and you shouldn't use them.
Besides getting everything at once, you can use the familiar expression sintax to get only specific links. Also, this command accepts the switch -onlyurl, which will return only the available urls instead of the whole information of each link which was shown with the previous example. You can also add the -absolute switch to convert all links to absolute urls. The following example connects to Slashdot and then retrieves all links with the text content "Read more" which have the word article in their urls:
    do_request http://slashdot.org/
    foreach url [link all -onlyurl {read more} ~u article] {
        log "$url"
    }
    
reset_current

This will delete the internal pointer current_link, which will behave as if the current page was just loaded and no link search had been done. Usefull to go back from link find -next.

current

Returns the currently selected link. If no link is selected, the first one will be returned, or an assertion thrown if there are no links at all.

get_*
Returns the specified attribute of a link. Example:
    debug "found a link: [link get_text]"
    assert { [link get_full] == "<a href=\"mailto:tils@tils.net\">Tilmann Singer</a>" }
    

Return to index

::tclwebtest::log (public)

::tclwebtest::log msg

Log msg to log_channel. If the variable ::tclwebtest::in_memory exists (through the previous execution of ::tclwebtest::test_run), ::tclwebtest::log_channel will be treated like a string instead of a file object (which defaults to stdout).

Parameters:
msg

Return to index

::tclwebtest::open_browser (public)

::tclwebtest::open_browser html [ tmp_file ]

Save the given html result in a temporary file and launch a browser. Intended to be inserted into a test while writing it to give a more thorough feedback than with debug.
Currently not satisfying since some referenced files such as images and stylesheets are required for a pleasing display. Maybe it is sufficient to parse the html for all those links, download the files and save them in a temporary directory, and replace them in the parsed html for local references.

Parameters:
html
tmp_file (optional)

Return to index

::tclwebtest::referer (public)

::tclwebtest::referer url_or_type

Use this command to modify the referer url field which will be sent by tclwebtest in the following http requests, or change the policy. Calling reset_session will reset the policy to the default value (1).

Parameters:
url_or_type - can be any of the following values:

0 (numerical) or emtpy string ("")

Using one of these values will desactivate sending the referer field in subsequent http requests.

1 (numerical)

tclwebtest will send the real referer expected to be sent by a usual browser: if you are making the first request, no referer will be sent, otherwise, the location you are coming from will be sent as referer. Note that this applies to both link and do_request commands. You will have to call reset_session to clean the old referer url, as well as other session variables like cookies. This is the default value.

string

Any url you may want to specify, which means that all the following requests will use it in the referer http field. Calling reset_session will eliminate the forged url.

Return to index

::tclwebtest::regsplit (public)

::tclwebtest::regsplit rex string

Utility proc to split the given string into elements that are matched by the first parentheses pair in the regular expression and returns a list of all matches.

Parameters:
rex
string

Return to index

::tclwebtest::reset_session (public)

::tclwebtest::reset_session

Deprecated.
Used to reset the session to a pristine state, as if there had been no use of tclwebtest at all. Example:
    do_request "file://$TESTHOME/select.html"
    assert { [string length [response text]] > 0 }

    reset_session

    assert { [response text] == "" }

    debug "l: [string length [response text]]"
    
Deprecated, use ::tclwebtest::init instead.

See Also:
::tclwebtest::init

Return to index

::tclwebtest::response (public)

::tclwebtest::response command

Parameters:
command - Specify one of the commands: text, body, full, body_without_comments, status, url, headers.

text

Returns the user viewable part of the response page.

body

Returns the full html source of the response page.

full

Same as body.

body_without_comments

Like response body but stripping html comments.

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.

url

Returns the current url.

headers

Returns the http headers that the server sent.

Return to index

::tclwebtest::translate_entities (public)

::tclwebtest::translate_entities string

Given a link or a link description, this procecedure subtitutes the Html character entities for the real thing, for example & gets changed to &.

Parameters:
string - The string to process.

Returns:
The string processed.

Return to index

::tclwebtest::user_agent_id (public)

::tclwebtest::user_agent_id id

By default tclwebtest identifies itself as "tclwebtest/$VERSION". With this command you can change the the agent string. This is useful to test web sites which send different HTML depending on the user browser, or you need to fake an identity because some webmaster decided to restrict access to his page to a subset of the popular browsers. You can find a list of common user agent strings at: http://www.pgts.com.au/pgtsj/pgtsj0208c.html
Parameters:
id - Indicate the user agent you want to set, which should be a string. There are a few shortcuts built into tclwebtest, you can set id to opera70, msie60, netscape70, mozilla09 and elinks04. Use list to retrieve a pair list in the form shortcut, agent string with the currently available shortcuts. Use original if you want to set back the default tclwebtest string. Example:
    log "Showing available builtin user agent strings:"
    array set agents [user_agent_id list]
    foreach id [array names agents] {
        log "  $id: $agents($id)"
    }
    
    log "Let's fool Google"
    do_request -nocomplain http://www.google.com/search?q=linux
    user_agent_id "super mozilla like browser"
    do_request http://www.google.com/search?q=linux
    

Return to index

Generated Sun May 09 01:12:28 CEST 2004. http://tclwebtest.sourceforge.net/