twill language reference¶
The following commands are built into twill. Note that all text after a ‘#’ is ignored as a comment, unless it’s in a quoted string.
Browsing¶
go <url> – visit the given URL.
back – return to the previous URL.
reload – reload the current URL.
follow <link name> – follow the given link.
Note: When used from Python, you get the new URL after executing
these commands (after possible redirects) with browser.url.
Assertions¶
code <code> – assert that the last page loaded had this HTTP status,
e.g. code 200 asserts that the page loaded fine.
find <pattern> [<flags>] – assert that the page contains the
specified regular expression pattern. The variable __match__ is set to
the first matching subgroup (or the entire matching string, if no subgroups
are specified). When called from Python, the matching string is also returned.
Fhe command also accepts some flags: i, for case-insensitive matching, m for multi-line mode and s for dotall matching. The flag x uses XPath expressions instead of regular expressions (see below).
find <xpath> x – assert that the page contains the element
matched by the XPath expression. The variable __match__ is set to
the first matching element’s text content. When called from Python, the
matching text is also returned.
not_find <pattern> [<flags>] – assert that the page does not contain the specified regular expression pattern. This command accepts the same flags as find.
Alternative spelling: “notfind”
not_find <xpath> x – assert that the page does not contain the element pointed by the XPath expression.
url <pattern> – assert that the current URL matches the given regex
pattern. The variable __match__ is set to the first matching subgroup
(or the entire matching string, if no subgroups are specified).
When called from Python, the matching string is returned.
title <pattern> – assert that the title of this page matches this
regular expression. The variable __match__ is set to the first matching
subgroup (or the entire matching string, if no subgroups are specified).
When called from Python, the matching string is returned.
Display¶
echo <string> – echo the string to the screen.
info – display information about the current page.
redirect_output <filename> – append all twill output to the given file.
reset_output – display all output to the screen.
save_html [<filename>] – save the current page’s HTML into a file. If no filename is given, derive the filename from the URL.
show – show the current page’s HTML.
Alternative spelling: “showhtml” or “show html”
show_links – show all of the links on the current page.
Alternative spellings: “showlinks” or “show links”
show_forms – show all of the forms on the current page.
Alternative spellings: “showforms” or “show forms”
show_history – show the browser history.
Alternative spellings: “showhistory” or “show history”
show_cookies – show the current cookies.
Alternative spellings: “showcookies” or “show cookies”
Note: When used from Python, you get these objects using the properties
of the browser with the same names, e.g. browser.html, browser.links,
browser.forms, browser.history and browser.cookies.
Forms¶
submit [<button_name>] – click the submit button with the given name. Instead of the name of the button you can also specify the number of the form element that shall be used as the submit button. If you do not specify a button name or number, the form is submitted via the last submission button clicked; if nothing had been clicked, use the first submit button on the form. See details on form handling for more information. In rare cases you may need to specify the form explicitly, you can do so by adding the form name or number as an additional parameter to the button name or number.
form_value <form_name> <field_name> <value> — set the given field in the given form to the given value. For read-only form controls, the click may be recorded for use by submit, but the value is not changed unless the ‘config’ command has changed the default behavior. See ‘config’ and details on form handling for more information on the ‘form_value’ command.
For list controls, you can use ‘form_value <form_name> <field_name> +value’ or ‘form_value <form_name> <field_name> -value’ to select or deselect a particular value.
Alternative spellings: “formvalue” or “fv”
fv – abbreviation for ‘form_value’.
form_action <form_name> <action> – change the form action URL to the given URL.
Alternative spellings: “formaction” or “fa”
fa – abbreviation for ‘form_action’.
form_clear – clear all values in the form.
Alternative spelling: “formclear”
form_file <form_name> <field_name> <filename> [ <content_type> ] – attach a file to a file upload button by filename.
Alternative spelling: ‘formfile’.
show_forms – show all of the forms on the current page.
Alternative spellings: “showforms” or “show forms”
Debugging¶
debug <what> <level> – turn on or off debugging/tracing for various functions. The first argument is either ‘http’ to show HTTP headers, ‘equiv-refresh’ to show “meta refresh” redirects, or ‘commands’ to show twill commands. The second argument is ‘0’ for off, ‘1’ for on.
Variable handling¶
set_global <name> <value> – set variable <name> to value <value> in global dictionary. The value can be retrieved with ‘$value’.
Alternative spelling: “setglobal”
set_local <name> <value> – set variable <name> to value <value> in local dictionary. The value can be retrieved with ‘$value’.
Alternative spelling: “setlocal”
The local dictionary is file-specific, while the global module is general to all the commands. Local variables will override global variables if they exist.
Note that you can do variable interpolation in strings with ${var}, e.g.
setglobal a 1
setglobal b 2
fv thisform thatfield "${a}${b}"
Other commands¶
tidy_ok – check to see if HTML Tidy runs on this page without any
errors or warnings. This check is very stringent, but you can relax the
default configuration by setting tidy_* configuration options.
exit [<code>] – exit with the given integer code, if specified. ‘code’ defaults to 0.
run <command> – execute the given Python command.
run_file <file1> [ <file2> … ] – execute the given file(s).
Alternative spellings: “runfile” or “rf”
rf – abbreviation for ‘run_file’.
add_cleanup <file1> [ <file2> … ] – add the given cleanup file(s). These will be run after the current file has executed (successfully or not).
agent – set the browser’s “User-agent” string.
timeout [<seconds>] – set browser timeout to given number of seconds. Defaults to 10 seconds. Set to 0 for no timeout.
sleep [<seconds>] – sleep the given number of seconds. Defaults to 1 second.
reset_browser – reset the browser.
extend_with <module> – import commands from Python module. This acts
like from <module> import * does in Python, so e.g. a function
fn in extmodule would be available as fn.
See extras/examples/extend_example.py for an example.
get_input <prompt> – get keyboard input and store it in __input__.
When called from Python, this function returns the input value.
Alternative spelling: “getinput”
get_password <prompt> – get silent keyboard input and store
it in __password__. When called from Python, this function returns
the input value.
Alternative spelling: “getpassword”
add_auth <realm> <uri> <user> <password> – add HTTP Basic Authentication information for the given realm/URI combination. For example,
add_auth IdyllStuff http://www.idyll.org/ titus test
tells twill that a request from the authentication realm
“IdyllStuff” under http://www.idyll.org/ should be answered with
username ‘titus’, password ‘test’. If the ‘with_default_realm’ option
is set to True, ignore ‘realm’.
config [<key> [<value>]] – show/set configuration options.
Configuration options starting with tidy_ will be used when checking
documents with HTML Tidy. For example,
config tidy_drop_empty_elements no
add_extra_headers <name> <value> – add an extra HTTP header to each HTTP request.
show_extra_headers – show the headers being added to each HTTP request.
clear_extra_headers – clear the headers being added to each HTTP request.
Special variables¶
__input__ – result of last getinput.
__match__ – matched text from last find, title, or url.
__password__ – result of last getpassword.
__url__ – current URL.
Details on form handling¶
Both the form_value (or fv) and submit commands rely on a certain amount of implicit cleverness to do their work. In odd situations, it can be annoying to determine exactly what form field form_value is going to pick based on your field name, or what form and field submit is going to “click” on.
Here is the pseudocode for how form_value and submit figure out what form to use (function twill.browser.form):
for each form on page:
if supplied regex pattern matches the form name, select
if no form name, try converting to an integer N & using N-1 as
an index into the list or forms on the page (i.e. form 1 is the
first form on the page).
Here is the pseudocode for how form_value and submit figure out what form field to use (function twill.browser.form_field):
search current form for control name with exact match to field_name;
if single (unique) match, select.
if no match, convert field_name into a number and use as an index, if
possible.
if no match, search current form for control name with regex match to
field_name; if single (unique) match, select.
if *still* no match, look for exact matches to submit-button values.
if single (unique) match, select.
Here is the pseudocode for submit:
if a form was _not_ previously selected by form_value:
if there's only one form on the page, select it.
otherwise, fail.
if a field is not explicitly named:
if a submit button was "clicked" with form_value, use it.
otherwise, use the first submit button on the form, if any.
otherwise:
find the field using the same rules as form_value
finally, if a button has been picked, submit using it;
otherwise, submit without using a button