tclwebtest API documentation - all procs

::tclwebtest::absolute_link (private)

::tclwebtest::absolute_link url

Prepend host and context if either one is missing, derived from previously called url's.

Parameters:

url

Return to index

::tclwebtest::add_referer_header (private)

::tclwebtest::add_referer_header header_list_name previous_url

Given the name of a list containing the headers of the next http request, adds to this list previous_url as referer depending on the value of previous_url and ::tclwebtest::referer_policy.

Parameters:

header_list_name
previous_url

Return to index

::tclwebtest::add_value_to_form_get_query (private)

::tclwebtest::add_value_to_form_get_query holder_name field_name \
    field_value

form_submit helper for get query operations.

Parameters:

holder_name - name of the variable holding the temporary memory used to store additional query parameters.
field_name - name of the field to be added to the query.
field_value - value of the field to be added to the query.

Return to index

::tclwebtest::add_value_to_form_post_query (private)

::tclwebtest::add_value_to_form_post_query holder_name field_name \
    field_value

form_submit helper for post query operations.

Parameters:

holder_name - name of the variable holding the temporary memory used to store additional query parameters.
field_name - name of the field to be added to the query.
field_value - value of the field to be added to the query.

Return to index

::tclwebtest::api_format_common_elements (private)

::tclwebtest::api_format_common_elements doc_elements_var

Parameters:

doc_elements_var

Return to index

::tclwebtest::api_format_see (private)

::tclwebtest::api_format_see see

Parameters:

see

Return to index

::tclwebtest::api_format_see_list (private)

::tclwebtest::api_format_see_list sees

Generate an HTML list of referenced procs and pages.

Parameters:

sees

Return to index

::tclwebtest::api_proc_documentation (private)

::tclwebtest::api_proc_documentation [ -format format ] [ -script ] \
    [ -source ] proc_name

Generates formatted documentation for a procedure.

Switches:

-format (defaults to "text/html") (optional) - the type of documentation to generate. Currently, only text/html and text/plain are supported.
-script (boolean) (optional) - include information about what script this proc lives in?
-source (boolean) (optional) - include the source code for the script?

Parameters:

proc_name - the name of the procedure for which to generate documentation.

Returns:

the formatted documentation string.

Error:

if the procedure is not defined.

Return to index

::tclwebtest::api_proc_pretty_name

::tclwebtest::api_proc_pretty_name [ -link ] proc

Return a pretty version of a proc name

Switches:

-link (boolean) (optional)

Parameters:

proc

Return to index

::tclwebtest::api_script_documentation (private)

::tclwebtest::api_script_documentation [ -format format ] path

Generates formatted documentation for a content page. Sources the file to obtain the comment or contract at the beginning.

Switches:

-format (defaults to "text/html") (optional) - the type of documentation to generate. Currently, only text/html is supported.

Parameters:

path - the path of the Tcl file to examine, relative to the OpenACS root directory.

Returns:

the formatted documentation string.

Error:

if the file does not exist.

Return to index

::tclwebtest::assert (public)

::tclwebtest::assert [ args... ]

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::assert_body (private)

::tclwebtest::assert_body [ -fail ] search_expr

Test an expression against the full html source of the result page.

Switches:

-fail (boolean) (optional)

Parameters:

search_expr

Return to index

::tclwebtest::assert_text (private)

::tclwebtest::assert_text [ -fail ] search_expr

Test an expression against the visible text of the result page. TODO make a more meaningful message

Switches:

-fail (boolean) (optional)

Parameters:

search_expr

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::build_do_request_retry (private)

::tclwebtest::build_do_request_retry type

do_request is a really complex function with lots of switches. When do_request has to be retried with a slight modification in it's parameters, like changing the url to follow a redirection or retry with an http password, there is a lot of code to type for each instance of the retry. To avoid cluttering do_request even more, this function parses the arguments for the eval and returns them in a list.

The problem is that the eval command has to be built carefully with a list instead of a quoted string. Otherwise, if for example the redirection location contained a few semicolons, the eval command would parse the semicolon and split the string in two individual commands, which is not what we were looking for, because the semicolon was part of the new location.

There are basically two different do_request retries, which are chosen with the type parameter: redirect or httpauth. The former will use the variable location as url, the second will use the variable url as url, appending later the query's key values if there were any.

Parameters:

type

Return to index

::tclwebtest::code_lines (private)

::tclwebtest::code_lines filename linenumber

loads a file an returns a few lines up to and including the linenumber

Parameters:

filename
linenumber

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::count_lines (private)

::tclwebtest::count_lines msg

Given a string, returns 1 + the number of line endings the string has.

Parameters:

msg

Return to index

::tclwebtest::current_dir_url (private)

::tclwebtest::current_dir_url url

Return the URL (without trailing slash) of the directory on the server of the given URL. Here are some examples: Last requested URL Proc returns http://peter.cph02.collaboraid.net http://peter.cph02.collaboraid.net http://peter.cph02.collaboraid.net/ http://peter.cph02.collaboraid.net http://peter.cph02.collaboraid.net/simulation/ http://peter.cph02.collaboraid.net/simulation http://peter.cph02.collaboraid.net/simulation?object_id=532 http://peter.cph02.collaboraid.net http://peter.cph02.collaboraid.net/simulation/index?object_id=423 http://peter.cph02.collaboraid.net/simulation

Parameters:

url

Return to index

::tclwebtest::deal_with_field (private)

::tclwebtest::deal_with_field start_idx stop_idx

Parse a field that is supposed to be on the specified position in the body. Add it to the fields list of the current_form - or modify the fields list if it is a radiobutton.

Parameters:

start_idx
stop_idx

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::do_request_file (private)

::tclwebtest::do_request_file url

Parameters:

url

Return to index

::tclwebtest::dummy_arg_parse_proc (private)

::tclwebtest::dummy_arg_parse_proc [ -debug ] [ -tidy ] \
    [ -processes processes ] [ -repeat repeat ] \
    [ -config_file config_file ] [ args... ]

Used to parse the commandline switches for the executable.

Switches:

-debug (boolean) (optional)
-tidy (boolean) (optional)
-processes (defaults to "1") (optional)
-repeat (defaults to "1") (optional)
-config_file (optional)

Return to index

::tclwebtest::evaluate_memory_string (private)

::tclwebtest::evaluate_memory_string [ -in_memory ] [ -log_end ] \
    [ -uplevel uplevel ] to_eval start_time file_name config_file \
    memory_code

Evaluates the given string and logs success or failure. Returns zero and 1 respectively.

Switches:

-in_memory (boolean) (defaults to "0") (optional) - special mode which makes a difference for logging of error messages
-log_end (boolean) (defaults to "0") (optional)
-uplevel (defaults to "0") (optional)

Parameters:

to_eval - code to evaluate, which is content of config_file plus contents of file_name.
start_time - clock seconds before calling this function
file_name - name of the file which contains the code to evaluate, can be anything with when using -in_memory.
config_file - configuration code
memory_code - like to_eval but without config_file.

Return to index

::tclwebtest::extract_forms_if_necessary (private)

::tclwebtest::extract_forms_if_necessary

Return to index

::tclwebtest::extract_links_if_necessary (private)

::tclwebtest::extract_links_if_necessary

Extract all links from the body of this sessions request.

Return to index

::tclwebtest::fake_base64_encode (private)

::tclwebtest::fake_base64_encode [ args... ]

This function substitutes base64::encode when the package can't be imported. It doesn't do anything at all, only log a message that we are using a fake version, and returns a constant string.

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::field_all (private)

::tclwebtest::field_all

See Also:

• field

Return to index

::tclwebtest::field_check (private)

::tclwebtest::field_check [ args... ]

field check ?search_args ...? Check a checkbox

Return to index

::tclwebtest::field_check_multiple (private)

::tclwebtest::field_check_multiple checkbox_name checkbox_values

Loop over a group of checkboxes with a given name and select those with a value matching a list of values.

Parameters:

checkbox_name
checkbox_values

Return to index

::tclwebtest::field_current (private)

::tclwebtest::field_current [ -index ] [ new_index ]

Switches:

-index (boolean) (optional)

Parameters:

new_index (optional)

See Also:

• field

Return to index

::tclwebtest::field_deselect (private)

::tclwebtest::field_deselect [ args... ]

Return to index

::tclwebtest::field_fill (private)

::tclwebtest::field_fill [ -append ] value [ args... ]

Switches:

-append (boolean) (optional)

Parameters:

value

See Also:

• field

Return to index

::tclwebtest::field_fill_hidden (private)

::tclwebtest::field_fill_hidden value [ args... ]

Fill the specified text in the first hidden field. This just updates the field(value), not the actual html code in field(full) and is a copy of fill above

Parameters:

value

Return to index

::tclwebtest::field_find (private)

::tclwebtest::field_find [ -next ] [ args... ]

Switches:

-next (boolean) (optional)

See Also:

• field

Return to index

::tclwebtest::field_get (private)

::tclwebtest::field_get attribute_name [ args... ]

return the specified attribute of a field. TODO write a selftest for this

Parameters:

attribute_name

Return to index

::tclwebtest::field_multiselect (private)

::tclwebtest::field_multiselect value_list [ args... ]

Parameters:

value_list

Return to index

::tclwebtest::field_select (private)

::tclwebtest::field_select [ -index ] search_arg [ args... ]

field select ?-index? value ?search_args ...? To be used with radio buttons or select fields. Select the entry that contains the specified text in its caption or the nth entry by specifying -index and a number as value (starting from 0). If the field is a select with multiple selections, then the new value will replace previously selected ones.

Switches:

-index (boolean) (optional)

Parameters:

search_arg

Return to index

::tclwebtest::field_select2 (private)

::tclwebtest::field_select2 [ args... ]

field select2 ~i index ~c caption ~v value ~d ID assumes you've found the form and the field first

Return to index

::tclwebtest::field_uncheck (private)

::tclwebtest::field_uncheck [ args... ]

Return to index

::tclwebtest::find_field_of_type (private)

::tclwebtest::find_field_of_type types search_args

Set the current field accordingly (used by the "field xxx" procs)

Parameters:

types
search_args

Return to index

::tclwebtest::find_in_array_list (private)

::tclwebtest::find_in_array_list [ -index ] [ -return_matches ] \
    array_list modifier_key_list expression

A wrapper around regexp that adds some functionality inspired by the limit function in the mutt mailclient: args can be more then one element and each will be interpreted as regexp against which string will be tested. Several lists with searchable content can be passed to this proc, and by default the first one will be searched. If an arg starts with ~ then the following character will identify which list to search. TODO add example If an element of args is a single ! then the following regexp (with optional ~x) must not match. Always -nocase. Maybe it should be extended to be case sensitive when there is at least one upper case in the expression.

Switches:

-index (boolean) (optional)
-return_matches (boolean) (optional) - if this is set to true, instead of stopping with the first match, the function will continue accumulating more matches and will return them in a list. Used with index will return a list of indices.

Parameters:

array_list
modifier_key_list
expression

Return to index

::tclwebtest::finish_form_get_query (private)

::tclwebtest::finish_form_get_query holder_name file_holder_name \
    form_name

form_submit helper for finishing get query operations, it will call do_request after building the query correctly from the parameter list holder_name.

Parameters:

holder_name - name of the variable holding the temporary memory used to store all the query parameters.
file_holder_name
form_name - name of the array containing all the form fields.

Return to index

::tclwebtest::finish_form_post_query (private)

::tclwebtest::finish_form_post_query holder_name file_holder_name \
    form_name

form_submit helper for finishing post query operations, it will call do_request after building the query correctly from the parameter list holder_name.

Parameters:

holder_name - name of the variable holding the temporary memory used to store all the query parameters.
file_holder_name
form_name - name of the array containing all the form fields.

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::form_all (private)

::tclwebtest::form_all

return a list of all forms

Return to index

::tclwebtest::form_current (private)

::tclwebtest::form_current [ -index ]

just return the current form

Switches:

-index (boolean) (optional)

Return to index

::tclwebtest::form_find (private)

::tclwebtest::form_find [ args... ]

find - set currentform to the first form or to a form on the page with specified criteria

Return to index

::tclwebtest::form_get (private)

::tclwebtest::form_get attribute_name [ args... ]

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

Parameters:

attribute_name

Return to index

::tclwebtest::form_submit (private)

::tclwebtest::form_submit [ args ]

Using the current form, it will search for a post/get method and use it to retrieve the next page. Only one submit button will be used, either the first found, or the one specified by args with a regular expression.

Parameters:

args (optional) - Regular expression which should match one available submit button.

Return to index

::tclwebtest::get_attribute (private)

::tclwebtest::get_attribute string att_name [ default_value ]

Extracts the value of the named attribute out of the given html fragment. E.g. the url of href="..."

Parameters:

string
att_name
default_value (optional)

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::link_all (private)

::tclwebtest::link_all [ -fail ] [ -onlyurl ] [ -absolute ] \
    [ args... ]

Switches:

-fail (boolean) (optional)
-onlyurl (boolean) (optional)
-absolute (boolean) (optional)

See Also:

• link

Return to index

::tclwebtest::link_current (private)

::tclwebtest::link_current

Return to index

::tclwebtest::link_find (private)

::tclwebtest::link_find [ -index ] [ -next ] [ -fail ] [ args... ]

find a link with the given attributes or the first one and return the full list or the index.

Switches:

-index (boolean) (optional)
-next (boolean) (optional)
-fail (boolean) (optional)

Return to index

::tclwebtest::link_follow (private)

::tclwebtest::link_follow [ args... ]

just a shortcut for "do_request [link find args]"

Return to index

::tclwebtest::link_get (private)

::tclwebtest::link_get attribute_name [ args... ]

return the specified attribute of a link. TODO write a selftest for this

Parameters:

attribute_name

Return to index

::tclwebtest::link_reset_current (private)

::tclwebtest::link_reset_current

see "field find -next" above

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::match_http_url_authorization (private)

::tclwebtest::match_http_url_authorization url_prefix

Searches in the user/pass http auth cache for the given url prefix If found, returns the string to be injected as http header. Otherwise returns the empty string.

Parameters:

url_prefix

Return to index

::tclwebtest::maybe_tidy (private)

::tclwebtest::maybe_tidy

Runs tidy on the current result page if the option TIDY is set. Output is sent to log_channel

Return to index

::tclwebtest::memory_lines (private)

::tclwebtest::memory_lines memory_string line_number

Similar in spirit to code_lines, chops memory_string until it is reduced to a few lines, up to and including the line_number, then the chopped version is returned.

Parameters:

memory_string
line_number

Return to index

::tclwebtest::normalize_html (private)

::tclwebtest::normalize_html html

Yet another html-mangling proc. This one calls translate_entities and replaces all multiple occurences of whitespace with a single space. Thus it returns proper strings for text that e.g. spans several lines in the html source.

Parameters:

html

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::parse_caption_after (private)

::tclwebtest::parse_caption_after position

Similar purpose to above, but simply parses till the first html element.

Parameters:

position

Return to index

::tclwebtest::parse_caption_before (private)

::tclwebtest::parse_caption_before position

Try to find a field's possible caption by scanning the text before it.

Parameters:

position

Return to index

::tclwebtest::post_process_url (private)

::tclwebtest::post_process_url url

Do some url cleanup, like substitution of '/./', '/..', etc.

Parameters:

url

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::replace_current_field (private)

::tclwebtest::replace_current_field new_field

Parameters:

new_field

See Also:

• field

Return to index

::tclwebtest::require_https_support (private)

::tclwebtest::require_https_support

Configures https support if not already done. Throws an error when not possible (most likely due to missing tls library).

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::run_test (private)

::tclwebtest::run_test [ -in_memory ] config_file file_name

Source the given file (must be a filename, not a directory). Return 0 when successful, 1 when the test failed. Output is done via the log command, so it goes to wherever log_channel points to.

Switches:

-in_memory (boolean) (optional) - If this switch is used, both config_file and file_name will be treated as strings which already contain the contents of the configuration and the script to run. Additionally, ::tclwebtest::log_channel will be treated like a normal string instead of a file, and logs will be appended to it.

Parameters:

config_file
file_name

Return to index

::tclwebtest::scan_cookie_expiration_time (private)

::tclwebtest::scan_cookie_expiration_time time_string

Used to parse the different cookie time values thrown by servers. It tries iteratively different formats until one of them is parsed correctly, and then returns the cookie expiration time in seconds since the starting epoch. If unable to parse the time, assertion_failed is raised to abort the request.

Parameters:

time_string

Return to index

::tclwebtest::set_cookie (private)

::tclwebtest::set_cookie set_cookie_string

Parses the value of the http "Set-cookie: " header into the global cookies list. Doesn't do anything with the path argument, e.g. if it is not / than this proc will behave wrongly. Also it currently depends on the Expires= information to be parsable by the tcl command clock scan. If that is not the case then it will throw an error.

Parameters:

set_cookie_string

Return to index

::tclwebtest::strip_html_comments (private)

::tclwebtest::strip_html_comments html

Parameters:

html

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 &amp; 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

::tclwebtest::util_expand_entities (private)

::tclwebtest::util_expand_entities html

Parameters:

html

Return to index

::tclwebtest::util_remove_html_tags (private)

::tclwebtest::util_remove_html_tags html

Parameters:

html

Return to index

::tclwebtest::util_striphtml (private)

::tclwebtest::util_striphtml html

Parameters:

html

Return to index

::tclwebtest::util_wrap_list (private)

::tclwebtest::util_wrap_list [ -eol eol ] [ -indent indent ] \
    [ -length length ] items

Wraps text to a particular line length.

Switches:

-eol (defaults to " \") (optional) - the string to be used at the end of each line.
-indent (defaults to "4") (optional) - the number of spaces to use to indent all lines after the first.
-length (defaults to "70") (optional) - the maximum line length.

Parameters:

items - the list of items to be wrapped. Items are HTML-formatted. An individual item will never be wrapped onto separate lines.

Return to index