Introduction

The wt script is provided for running "HTTP::WebTest" from the command line.

The test specifications can be read from a parameter file in wtscript format or input as method arguments. The test results can be displayed on the terminal, directed to a file, stored in a scalar variable. The test results can also be emailed. The report can be modified and extended using report plugins.

Each URL/web file is tested by fetching it from the web server using a local instance of an HTTP user agent. The basic test is simply whether or not the fetch was successful. You may also test using literal strings or regular expressions that are either required to exist or forbidden to exist in the fetched page. You may also specify tests for the minimum and maximum number of bytes in the returned page. You may also specify tests for the minimum and maximum web server response time.

Data flow for "HTTP::WebTest":

          --------------              -------------
          |            |              |           |
          | Input      |------------->|  WebTest  |
          | parameters |              |           |
          |            |              -------------
          --------------                  |   ^
                                          |   |
                                          V   |
          -------------               ------------
          |           |    request    |          |
          | Remote    |<--------------|   HTTP   |
          | webserver |-------------->|   user   |
          |           |    response   |   agent  |
          -------------               |          |
                                      ------------

Getting started

This document describes:

• How tests can be specified. See section TEST SPECIFICATION.
• All test parameters supported by core "HTTP::WebTest" plugins. See section TEST PARAMETERS.

See "perldoc wt" for documentation on the wt program.

Other useful documentation is:

• perldoc HTTP::WebTest::Cookbook - examples of wtscript files and examples of "HTTP::WebTest" API usage.
• perldoc HTTP::WebTest::API - full documentaion on API of "HTTP::WebTest".
• perldoc HTTP::WebTest::Plugins - for developers of "HTTP::WebTest" plugins.

Running HTTP::WebTest using a parameter file

Tests defined by wtscript file can be run either using Perl API of "HTTP::WebTest"

    use HTTP::WebTest;

    my $webtest = new HTTP::WebTest;
    $webtest->run_wtscript('script.wt');

or by using program wt supplied with this module.

If you are running dozens of tests, you may want to divide them into several parameter files. This will organize the tests and reduce the size of the output and e-mail messages. However, cookies passed to or received from the web server(s) are not shared between tests in different parameter files.

File format

The wtscript file is a text file containing global parameters and test blocks containing test block parameters. A test block begins with a test_name parameter and ends with an end_test directive. The order of the parameters and test blocks is arbitrary.

Test block parameters MUST occur between a test_name parameter and an end_test directive. (Test block parameters affect only an individual test.) Global parameters must NOT occur between a test_name parameter and an end_test directive. (This requirement does not apply to certain parameters that are both global and test block parameters.)

The following lines are ignored:

• lines consisting of nothing but white space (blanks or tabs)
• lines beginning with a number sign ("#")
• lines beginning with white space (blanks or tabs) followed by a number sign

Parameters are either scalar (single-valued) or lists (single-valued, multi-valued or nested).

You can specify scalar parameters using forms such as:

    name=value
    name =
           value
    name = 'value'

You can specify list parameters using forms such as:

    name = ( first value
             second value )
    name=( first value => second value
           third value => fourth value
         )
    name = ( first value => second value )
    name = (
             'first value'
             'second value' )
    name= (
             first value
             second value
             third value => 'fourth value'
          )
    name =
           ( first value
             'second value' )
    name = (
             'first value'
             'second value'
           )

Lists can be nested. For example:

    name = ( ( first value
               second value ) )

    name = ( 'third value'
             ( fourth value => fifth value ) )

    name = (
             ( first value
               second value )
             third value
             ( fourth value => fifth value )
           )

You can specify a null (placeholder) value using '' or "". Within single or double quotes, the usual Perl string quoting rules apply. Thus, single quotes mean that all enclosed characters are interpreted literally: '\n' is backslash-n rather than a newline character. Double quotes mean that Perl metasymbols are interpreted: "\n\t" is a newline and a tab. Double quoted strings can also contain Perl variables that will be evaluated by Perl. For example, if the variable $myvar contains the string 'foobar', "$myvar" will be replaced by foobar at runtime. Perl variables can be defined by plugin modules or in code sections in the parameter file as described below.

It is also possible to specify a Perl expression in place of a scalar value, one of a list parameter's values or an entire list. Curly brackets are used to denote Perl code inside wtscript files. "HTTP::WebTest" compiles this Perl code as anonymous subroutines which are called when values of corresponding test parameters are required. When these subroutines are called "HTTP::WebTest" object is passed to them as the first argument.

Some examples of syntax:

    # scalar value
    name = { 1 + 1 }

    # element of a list
    name = (
             'first value'
             { "second " . "value" }
           )

    # entire list (must be a reference to an array)
    name = { [ a => 'b', c => 'd' ] }

    # accessing HTTP::WebTest object
    name = { my $webtest = shift; ..... }

Examples of wtscript files

The parameters below specify tests. The tests specified by the "text_forbid" parameter apply to both the "MyCompany home page" and the "Yahoo home page" tests. Hence, if either returned page contains one of the case-insensitive strings in text_forbid, the test fails. If any test fails or the fetch of the URL fails, an e-mail will be sent to tester@mycompany.com.

    apache_exec = /usr/sbin/apache
    ignore_case = yes
    mail = errors
    mail_addresses = ( tester@mycompany.com )
    mail_server = mailhost.mycompany.com
    text_forbid = ( Premature end of script headers
                    an error occurred while processing this directive
                  )

    test_name = 'MyCompany home page (static)'
        file_path = ( raycosoft_home.html => . )
        text_require = (
            <a href="/dept/peopledev/new_employee/"><font color="#0033cc">
            <a href="https://www.raycosoft.com/"><font color=
                       )
    end_test

    test_name = Yahoo home page
        url = www.yahoo.com
        text_require = ( <a href=r/qt>Quotations</a>...<br> )
        min_bytes = 13000
        max_bytes = 99000
        min_rtime = 0.010
        max_rtime = 30.0
    end_test

Calling HTTP::WebTest from a Perl program

Each hash in the array defines tests for one URL. Keys in the hashes are test parameter names and values in hashes are values of test parameters. Optional global test parameters can be passed in a hash passed as the second argument.

Subroutine references can be specified instead of test parameter values. Referenced subroutines are called during test run when values of corresponding test parameters are required. These subroutines are called in an object-oriented fashion, so the "HTTP::WebTest" object is passed as the first argument.

Tests can be run as

    use HTTP::WebTest;

    my $webtest = new HTTP::WebTest;
    $webtest->run_tests(
                        [ # test 1
                          { param1 => value1,
                            param2 => value2 },
                          # test 2
                          { param1 => value1,
                            param2 => value2 },
                        ],
                        { global_param1 => value1,
                          global_param2 => value2 }
                       );

Example

This Perl script tests Yahoo home page and sends full test report to "tester@mycompany.com".

    use HTTP::WebTest;

    my $tests = [
                 { test_name    => 'Yahoo home page',
                   url          => 'http://www.yahoo.com',
                   text_require => [ '<a href=r/qt>Quotations</a>...<br>' ],
                   min_bytes    => 13000,
                   max_bytes    => 99000,
                 }
                ];

    my $params = { mail_server    => 'mailhost.mycompany.com',
                   mail_addresses => [ 'tester@mycompany.com' ],
                   mail           => 'all',
                   ignore_case    => 'yes',
                 };

    my $webtest = new HTTP::WebTest;
    $webtest->run_tests($tests, $params);

Core plugin modules

HTTP::WebTest::Plugin::ContentSizeTest

This plugin checks the size of the fetched web page.

HTTP::WebTest::Plugin::Cookies

This plugin controls sending and receiving cookies.

HTTP::WebTest::Plugin::DefaultReport

This plugin manages the test report.

HTTP::WebTest::Plugin::Loader

This plugin supports adding external plugin modules.

HTTP::WebTest::Plugin::ResponseTimeTest

This plugin tests the response times of the web server.

HTTP::WebTest::Plugin::SetRequest

This plugin initializes the HTTP requests.

HTTP::WebTest::Plugin::StatusTest

This plugin checks the status of the HTTP responses.

HTTP::WebTest::Plugin::TextMatchTest

This plugin tests whether the content of the HTTP response matches or doesn't match selected text or regular expressions.

Information about test parameters supported by core plugins is summarized below in the section TEST PARAMETERS.

Other plugin modules bundled with HTTP::WebTest

HTTP::WebTest::Plugin::Click

This plugin supports using names of links and buttons on HTML pages to build additional tests.

HTTP::WebTest::Plugin::Delay

This plugin module allows the user to specify pauses in the test sequence.

HTTP::WebTest::Plugin::HarnessReport

This report plugin can generate test reports that are compatible with Test::Harness.

HTTP::WebTest::Plugin::Hooks

This plugin allows the user to define callback parameters that are evaluated at runtime. This allows the user to define additional tests without writing a plugin module.

Information about test parameters supported by add-on plugin modules is summarized below in section TEST PARAMETERS.

Plugin modules released separately from HTTP::WebTest

HTTP::WebTest::Plugin::Apache

This plugin supports testing web files using a local instance of Apache.

HTTP::WebTest::Plugin::TagAttTest

This plugin allows to forbid or require tags and/or attributes in a web page.

HTTP::WebTest::Plugin::DateTest

Evaluate the "age" of embedded date strings in response body.

HTTP::WebTest::Plugin::XMLReport

Report plugin for HTTP::WebTest, generates output in XML format.

Writing plugin modules

accept_cookies

These cookies exist only while the program is executing and do not affect subsequent runs. These cookies do not affect your browser or any software other than the test program. These cookies are only accessible to other tests executed during test sequence execution.

See also the <send_cookies> parameter.

Allowed values

"yes", "no"

Default value

"yes"

auth

click_button

Given name of submit button (i.e. "<input type="submit">" tag or "<input type="image">" inside of "<form>" tag) on previously requested HTML page, builds test request to the submitted page.

Note that you still need to pass all form parameters yourself using "params" test parameter.

Example

See example in HTTP::WebTest::Cookbook.

click_link

Given name of link (i.e. "<a>" tag) on previosly requested HTML page, builds test request to the linked page.

Example

See example in HTTP::WebTest::Cookbook.

cookie

It is deprecated parameter and may be removed in future versions of HTTP::WebTest.

cookies

    cookies = ( cookie1_spec
                cookie2_spec
                ...
                cookieN_spec )

Currently there are two ways to specify a cookie.

•

Named style

A cookie is specified by a set of "param => value" pairs:

    (
      param => value
      ...
    )
    

List of all supported "param => value" pairs:

    cookies = ( ( name   => Cookie1
                  value  => cookie value )

                ( name   => Cookie2
                  value  => cookie value
                  path   => /
                  domain => .company.com ) )

                ( name   => Cookie2
                  value  => cookie value
                  rest   => ( Comment => this is a comment ) )

    my $tests = [
                  ...
                  {
                    test_name => 'cookie',
                    cookies   => [ [
                                     name  => 'Cookie1',
                                     value => 'Value',
                                   ],
                                   [
                                     name  => 'Cookie2',
                                     value => 'Value',
                                     path  => '/',
                                   ] ],
                    ...
                  }
                  ...
                ]

•

Row list style

This style of cookie specification is deprecated and may be removed in future versions of HTTP::WebTest.

Each cookie is specified by following list:

    ( VERSION
      NAME
      VALUE
      PATH
      DOMAIN
      PORT
      PATH_SPEC
      SECURE
      MAXAGE
      DISCARD
      NAME1
      VALUE1
      NAME2
      VALUE2
      ...
    )
    

Any element not marked below as REQUIRED may be defaulted by specifying a null value or ''.

    cookies = ( ( 0
                  WebTest cookie #1
                  cookie value
                  /
                  .mycompany.com
                  ''
                  0
                  0
                  200
                  1
                ) )

See RFC 2965 for details (ftp://ftp.isi.edu/in-notes/rfc2965.txt).

default_report

This parameter controls whether the default report plugin is used for test report creation. Value "yes" means that default report plugin will be used, value "no" means that it will not. It can also be used to disable all output (i.e. if this parameter has value "no" and no other report plugins are loaded).

Allowed values

"yes", "no"

Default value

"yes"

delay

Duration of pause (in seconds) before running test.

Allowed values

Any number greater that zero.

end_test

fh_out

A filehandle (or anything else that supports "print") to use for test report output. This parameter is ignored if test parameter "output_ref" is specified also.

This parameter can be used only when passing the test parameters as arguments from a calling Perl script.

form_name

Give form name attribute (i.e. "<form name="foo">") on previously requested HTML page, builds test request to the submitted page.

Note that you still need to pass all form parameters yourself using "params" test parameter.

handle_redirects

Allowed values

"yes", "no"

Default value

"yes"

http_headers

Example

    http_headers = ( Accept => text/plain, text/html )

ignore_case

Allowed values

"yes", "no"

Default value

"no"

mail

Option to e-mail output to one or more addresses specified by "mail_addresses" test parameter.

mail_addresses

A list of e-mail addresses where report will be send (if sending report is enabled with "mail" test parameter).

• all

  Send e-mail containing test results.

• errors

  Send e-mail only if one or more tests fails.

• no

  Do not send e-mail.

Default value

"no"

mail_failure_subject

Sets "Subject" header for test report e-mails when some tests fail. In this string some character sequences have special meaning:

%f

the number of failed tests

%s

the number of successful tests

%t

the total number of tests

%%

replaced with single "%"

Default Value

"WEB TESTS FAILED! FOUND %f ERROR(S)"

mail_from

Sets From: header for test report e-mails.

Default Value

Name of user under which test script runs.

mail_server

Fully-qualified name of of the mail server (e.g., mailhost.mycompany.com).

Default value

"localhost"

mail_success_subject

Sets "Subject" header for test report e-mails when all tests are passed successfully. In this string some character sequences have special meaning (see "mail_failure_subject" parameter for their description).

Default Value

"Web tests succeeded"

max_bytes

Allowed values

Any integer greater that zero and greater than "min_bytes" (if "min_bytes" is specified).

max_rtime

Allowed values

Any number greater that zero and greater than "min_rtime" (if "min_rtime" is specified).

method

See RFC 2616 (HTTP/1.1 protocol).

Allowed values

"GET", "POST"

Default value

"GET"

min_bytes

Allowed values

Any integer less than "max_bytes" (if "max_bytes" is specified).

min_rtime

Allowed values

Any number less than "max_rtime" (if "max_rtime" is specified).

on_finish

The value of this test parameter is ignored. However, it is evaluted before the test sequence is run, so it can be used to run finalization code when the test sequence is finished.

Example

See example in HTTP::WebTest::Cookbook.

on_request

The value of this test parameter is ignored. However, it is evaluted before the HTTP request is done, so it can be used to do initalization before the request.

on_response

This is a list parameter which is treated as test result. It is evaluted when the HTTP response for the test request is received.

It can be used to define custom tests without writing new plugins. It can also be used to run some code when the HTTP response for the test request is received.

Allowed values

    ( YESNO1, COMMENT1
      YESNO2, COMMENT2
      ....
      YESNON, COMMENTN )

Here "YESNO", "COMMENT" is a test result. "YESNO" is either "yes" if test is successful or "no" if it is not. "COMMENT" is a comment associated with this test.

Example

See example in HTTP::WebTest::Cookbook.

on_start

The value of this test parameter is ignored. However, it is evaluted before the test sequence is run, so it can be used to do initalization before the test sequence run.

Example

See example in HTTP::WebTest::Cookbook.

output_ref

A reference to a scalar that accumulates text of test report. If this test parameter is specified then value of test parameter "fh_out" is ignore.

This parameter can be used only when passing the test parameters as arguments from a calling Perl script.

params

If the method key is set to "GET", these pairs are URI-escaped and appended to the requested URL.

Example (wtscript file):

    url = http://www.hotmail.com/cgi-bin/hmhome
    params = ( curmbox
               F001 A005
               from
               HotMail )

generates the HTTP request with URI:

    http://www.hotmail.com/cgi-bin/hmhome?curmbox=F001%20A005&from=HotMail

If the method key is set to "POST", as long as all values are scalars they are URI-escaped and put into content of the HTTP request. "application/x-www-form-urlencoded" content type is set for such HTTP request.

If the method key is set to "POST", some values may be defined as lists. In this case HTTP::WebTest uses "multipart/form-data" content type used for "Form-based File Upload" as specified in RFC 1867. Each parameter with list value is treated as file part specification with the following interpretation:

    ( FILE, FILENAME, HEADER => VALUE... )

where

• FILE

  The name of a file to open. This file will be read and its content placed in the request.

• FILENAME

  The optional filename to be reported in the request. If it is not specified than basename of "FILE" is used.

• HEADER => VALUE

  Additional optional headers for file part.

Example (wtscript file):

    url = http://www.server.com/upload.pl
    method = post
    params = ( submit => ok
               file   => ( '/home/ilya/file.txt', 'myfile.txt' ) )

It generates HTTP request with "/home/ilya/file.txt" file included and reported under name "myfile.txt".

pauth

plugins

A list of module names. Loads these modules and registers them as HTTP::WebTest plugins. If the name of the plugin starts with "::", it is prepended with "HTTP::WebTest::Plugin". So

    plugins = ( ::Click )

is equal to

    plugins = ( HTTP::WebTest::Plugin::Click )

proxies

Example

    proxies = ( http => http://http_proxy.mycompany.com
                ftp  => http://ftp_proxy.mycompany.com )

regex_forbid

For more information, see perldoc perlre or see Programming Perl, 3rd edition, Chapter 5.

See also the "text_forbid" and "ignore_case" parameters.

regex_require

For more information, see perldoc perlre or see Programming Perl, 3rd edition, Chapter 5.

See also the "text_require" and "ignore_case" parameters.

relative_urls

Allowed values

"yes", "no"

Default value

"no"

send_cookies

This does NOT give the web server(s) access to cookies created with a browser or any user agent software other than this program. The cookies created while this program is running are only accessible to other tests in the same test sequence.

See also the <accept_cookies> parameter.

Allowed values

"yes", "no"

Default value

"yes"

show_cookies

Allowed values

"yes", "no"

Default value

"no"

show_headers

Allowed values

"yes", "no"

Default value

"no"

show_html

Allowed values

"yes", "no"

Default value

"no"

status_code

Default value

200 (OK).

terse

• summary

  Only a one-line summary for each URL

• failed_only

  Only tests that failed and the summary

• no

  Show all tests and the summary

Default value

"no"

test_name

text_forbid

See also the "regex_forbid" and "ignore_case" parameters.

text_require

See also the "regex_require" and "ignore_case" parameters.

timeout

Default value

180

url

If test parameter "relative_urls" is set to "yes" than URL for each test is treated as relative to the URL in the previous test. URL in the first test is treated as relative to "http://localhost".

If test parameter "relative_urls" is set to "no" than each URL is treated as absolute. In this case if schema part of URL is omitted (i.e. URL doesn't start with "http://", "ftp://", etc) then "http://" is implied.

user_agent

Default value

"HTTP-WebTest/NN"

where "NN" is version number of HTTP-WebTest.