HTTP::WebTest - Test remote URLs or local web files
All HTTP::WebTest API cannot be summarized here. Only basic usage.
use HTTP::WebTest; my $webtest = new HTTP::WebTest; $webtest->run_wtscript('script.wt'); $webtest->run_tests($tests);
See below for all API.
This module runs tests on remote URLs or local web files containing Perl/JSP/HTML/JavaScript/etc. and generates a detailed test report. This module has plugin based architecture. Plugins can define test types and provide various report capabilities. This module comes with a set of default plugins but can be easily extended with third party plugins.
The test specifications can be read from a parameter file (wtscript) or input as method arguments. If you are testing a local file, Apache is started on a private/dynamic port with a configuration file in a temporary directory. The module can display the test results via report plugin(s). Default report plugin can output them on the terminal, directs them to a file or scalar variable and/or email them.
Data flow for HTTP::WebTest using a remote URL:
HTTP::WebTest
-------------- ------------- | | | | | Input |------------->| WebTest | | parameters | | | | | ------------- -------------- | ^ | | V | ------------- ------------ | | request | | | Remote |<--------------| HTTP | | webserver |-------------->| user | | | response | agent | ------------- | | ------------
Data flow diagram for HTTP::WebTest using a local web file:
-------------- --------------------- | | | | | Input | | Web page code | | parameters | | (Perl/HTML/etc.) | | | | | -------------- --------------------- | | | --------------------------- | | V V ------------------------ ------------- | | | |---------->| Temporary Apache | | WebTest | | directories (htdocs, | | |<----------| conf, logs) | ------------- | | | ^ ------------------------ | | | ^ V | V | ------------ ---------------------- | | request | | | HTTP |------------>| Temporary local | | user | | instance of Apache | | agent |<------------| | | | response ---------------------- ------------
This document is good starting point. It describes:
How tests can be specificated. See section TEST SPECIFICATION.
All test parameters supported by core HTTP::WebTest plugins. See section TEST PARAMETERS.
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 HTTP::WebTest::API.
perldoc HTTP::WebTest::Plugins - for developers of HTTP::WebTest plugins.
The test specifications can be read from a parameter file (wtscript) or input in form of array of hashes.
HTTP::WebTest can read test specification from file in format called as wtscript. Tests defined by wtscript file can be run either using Perl API of HTTP::WebTest
wtscript
use HTTP::WebTest; my $webtest = new HTTP::WebTest; $webtest->run_wtscript('script.wt');
or by using program wt supplied with this module.
The following is ignored in wtscript file:
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
The order of the parameters in the parameter file is arbitrary, with the following exceptions:
Test block parameters MUST occur between a test_name parameter and an end_test directive.
Global parameters must NOT occur between a test_name parameter and an end_test directive. (This requirement does not apply to parameters that are both global and test block parameters.)
Parameters are either scalar (single-valued) or lists (single or multi-valued).
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' )
(The equals sign must be followed by a space, tab or newline; all other spaces are optional.)
PARAMETER VALUES BEGINNING AND ENDING WITH A SINGLE QUOTE WILL HAVE THE SINGLE QUOTES REMOVED. For example, 'foobar' is parsed as a value of foobar and ''foobar'' is parsed as a value of 'foobar'. To specify a null (placeholder) value, use ''.
You MUST enclose the parameter value in single quotes if you want to specify:
a value beginning with a left parenthesis
a value ending with a right parenthesis
a value beginning with leading white space (blanks or tabs)
a value ending with trailing white space (blanks or tabs)
a value beginning and ending with single quotes
The parameters below specify tests of a local file and a remote URL. The tests specified by the text_forbid parameter apply to both the "RayCosoft 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@unixscripts.com.
text_forbid
apache_exec = /usr/sbin/apache ignore_case = yes mail = errors mail_addresses = ( tester@unixscripts.com ) mail_server = mailhost.unixscripts.com text_forbid = ( Premature end of script headers an error occurred while processing this directive ) test_name = 'RayCosoft 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
The parameters below specify a test of a local file containing Perl code using the Apache::ASP module. The includes.htm file requires five include files and two Perl modules, which are copied using the include_file_path parameter.
includes.htm
include_file_path
apache_exec = /usr/sbin/apache ignore_case = yes include_file_path = ( footer.inc => htdocs/apps/myapp/inc header.inc => htdocs/apps/myapp/inc head.inc => htdocs/apps/myapp/inc go.script => htdocs/shared/includes go.include => htdocs/shared/includes ../utils/DBconn.pm => lib/perl/utils ../utils/Window.pm => lib/perl/utils ) test_name = includes.htm file_path = ( includes.htm => apps/myapp ) min_bytes = 33000 max_bytes = 35000 text_require = ( input type=hidden name=control value= ) text_forbid = ( Premature end of script headers an error occurred while processing this directive ) end_test
If you are using Perl API of HTTP::WebTest then test sequence can be defined in form of array of hashes.
Each hash in array defines tests for one URL. Keys in hashes are test parameter names and values in hashes are values of test parameters. Also there can be defined global test parameters in form of hash for each test sequence.
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 } );
This Perl script tests Yahoo home page and sends full test report to tester@unixscripts.com.
tester@unixscripts.com
use HTTP::WebTest; my $tests = [ { 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 $options = { mail_server => 'mailhost.unixscripts.com', mail_addresses => [ 'tester@unixscripts.com' ], mail => 'all', ignore_case => 'yes', }; $webtest->run_tests($tests, $options);
Option to accept cookies from the web server.
yes, no
yes
no
Absolute or relative path name of directory containing Apache files. See the APACHE DIRECTORY AND FILES section. This parameter is ignored unless the file_path parameter is specified.
file_path
/usr/local/etc/http-webtest
Absolute or relative path name of Apache executable. This command can be in your $PATH. This parameter is ignored unless the file_path parameter is specified.
$PATH
/usr/sbin/apache
Apache logging level. If you use a level less than warn (i.e., debug, info, or notice), the program may generate irrelevant errors. This parameter is ignored unless the file_path parameter is specified. See also the ignore_error_log parameter.
warn
debug
info
notice
ignore_error_log
debug, info, notice, warn, error, crit, alert, emerg
error
crit
alert
emerg
Maximum number of seconds to wait for Apache to start. This parameter is ignored unless the file_path parameter is specified.
60
Additional Apache command line options. Many of the options cause Apache to exit immediately after starting, so the web page tests will not run. This parameter is ignored unless the file_path parameter is specified.
A list of userid/password pairs to be used for web page access authorization.
Synonym to cookies.
cookies
Specifies a cookie(s) to send to the web server.
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 ''.
version (REQUIRED)
Version number of cookie spec to use, usually 0.
name (REQUIRED)
Name of cookie. Cannot begin with a $ character.
value (REQUIRED)
Value of cookie.
path (REQUIRED)
URL path name for which this cookie applies. Must begin with a / character. See also path_spec.
domain (REQUIRED)
Domain for which cookie is valid. (REQUIRED). Should begin with a period. Must either contain two periods or be equal to .local.
.local
port
List of allowed port numbers that the cookie may be returned to. If not specified, cookie can be returned to any port. Must be specified using the format N or N, N, ..., N where N is one or more digits.
N
N, N, ..., N
path_spec
Ignored if version is less than 1. Option to ignore the value of path. Default value is 0.
1
Use the value of path.
Ignore the specified value of path.
secure
Option to require secure protocols for cookie transmission. Default value is 0.
Use only secure protocols to transmit this cookie.
Secure protocols are not required for transmission.
maxage
Number of seconds until cookie expires.
discard
Option to discard cookie when the program finishes. Default 0. (The cookie will be discarded regardless of the value of this element.)
Discard cookie when the program finishes.
Don't discard cookie.
name/value
Zero, one or several name/value pairs may be specified. The name parameters are words such as Comment or CommentURL and the value parameters are strings that may contain embedded blanks.
See RFC 2965 for details (ftp://ftp.isi.edu/in-notes/rfc2965.txt).
You may specify multiple cookies within each test block by specifying multiple instances of the cookies parameter.
Use arrayref of arrayrefs containing cookies to pass with the HTTP request.
Each array must have at least 5 elements; if the number of elements is over 10 it must have an even number of elements.
The pathname of a local web server error log. The module counts the number of lines in the error log before and after each request. If the number of lines increases, an error is counted and the additional lines are listed in the report. This argument should be used only when the local web server is running in single-process mode. Otherwise, requests generated by other processes/users may add lines to the error log that are not related to the requests generated by this module. See also parameter ignore_error_log.
A filehandle (or anything else that supports print) to use for test report output. This parameter make sense only in Perl scripts.
print
Two-element list. First element is the file to test, either an absolute or a relative pathname. Second element is the subdirectory pathname, relative to the Apache htdocs directory, to copy the file to. The copied file will have the same basename as the first element and the relative pathname of the second element. To copy the file directly to the htdocs directory, use a pathname of . or ./..
.
./.
Option to do case-insensitive string matching for text_forbid, text_require, regex_forbid and regex_require test parameters.
text_require
regex_forbid
regex_require
Option to ignore any errors found in the Apache error log. The default behavior is to flag an error if the fetch causes any errors to be added to the error log and echo the errors to the program output. This check is available only if error_log parameter is specified. See also the apache_loglevel parameter.
error_log
apache_loglevel
List with an even number of elements. Odd-numbered elements are files to copy to the the temporary Apache directory before running the tests. These files can be specified using either an absolute or a relative pathname. Even-numbered elements are the subdirectory pathname, relative to the Apache ServerRoot directory, to copy the corresponding file to. The copied file will have the same basename as the odd-numbered element and the relative pathname of the corresponding even-numbered element. To copy the file directly to the ServerRoot directory, use a pathname of . or ./..
Option to e-mail output to one or more addresses specified by mail_addresses test parameter.
mail_addresses
all
Send e-mail containing test results.
errors
Send e-mail only if one or more tests fails.
Do not send e-mail.
A list of e-mail addresses where report will be send (if sending report is enabled with mail test parameter).
mail
Sets From: header for report e-mails.
Name of user under which test script runs.
Fully-qualified name of of the mail server (e.g., mailhost.mycompany.com).
localhost
Maximum number of bytes expected in returned page.
Any integer greater that zero and greater than min_bytes (if min_bytes is specified).
min_bytes
Maximum web server response time (seconds) expected.
Any number greater that zero and greater than min_rtime (if min_rtime is specified).
min_rtime
HTTP request method.
GET, PUT
GET
PUT
Minimum number of bytes expected in returned page.
Any integer less than max_bytes (if max_bytes is specified).
max_bytes
Minimum web server response time (seconds) expected.
Any number less than max_rtime (if max_rtime is specified).
max_rtime
A reference on scalar which accumulates text of test report. This parameter make sense only in Perl scripts.
A list of name/value pairs to be passed as parameters to the URL. (This element is used to test pages that process input from forms.) Unless the method key is set to POST, these pairs are URI-escaped and appended to the requested URL.
POST
A list of userid/password pairs to be used for proxy server access authorization.
A list of module names. Loads these modules and registers them as HTTP::WebTest plugins. If name of plugin starts with :: prepends it with HTTP::WebTest::Plugin. So
::
HTTP::WebTest::Plugin
plugins = ( ::ValidateHTML )
is equal to
plugins = ( HTTP::WebTest::Plugin::ValidateHTML )
A list of service name/proxy URL pairs that specify proxy servers to use for requests.
For example (wtscript usage):
proxies = ( http => http://http_proxy.mycompany.com ftp => http://ftp_proxy.mycompany.com )
List of regular expressions that are URI forbidden to exist in the returned page.
List of regular expressions that are URI required to exist in the returned page.
Option to send cookies to web server. This applies to cookies received from the web server or cookies specified using the cookies test parameter.
Option to display any cookies sent or received.
Include content of HTTP response in the test report.
Option to display shorter test report.
summary
Only a one-line summary for each URL
failed_only
Only tests that failed and the summary
Show all tests and the summary
Name associated with this url in the test report and error messages.
List of text strings that are forbidden to use exist in the returned page.
List of text strings that are required to use exist in the returned page.
URL to test. If schema is omitted then HTTP is implied.
Content of this section should be autogenerated from POD docs in plugin modules.
This module have been tested only on Unix (e.g., Solaris, Linux, AIX, etc.) but it should work on Win32 systems.
Local file tests don't work on Win32 systems.
The module's HTTP requests time out after 3 minutes (the default value for LWP::UserAgent). If the file_path parameter is specified, Apache must be installed.
Richard Anderson <Richard.Anderson@unixscripts.com> have wrote HTTP::WebTest 1.xx.
HTTP::WebTest 1.xx
Ilya Martynov <ilya@martynov.org> made rewrite of HTTP::WebTest. He is maintaining HTTP::WebTest now. Please email him bug reports, suggestions, questions, etc.
Copyright (c) 2000-2001 Richard Anderson. All rights reserved.
Copyright (c) 2001,2002 Ilya Martynov. All rights reserved.
This module is free software. It may be used, redistributed and/or modified under the terms of the Perl Artistic License.
HTTP::WebTest::Cookbook
HTTP::WebTest::API
HTTP::WebTest::Plugins
wt
4 POD Errors
The following errors were encountered while parsing the POD:
You forgot a '=back' before '=head3'
=back without =over
To install HTTP::WebTest, copy and paste the appropriate command in to your terminal.
cpanm
cpanm HTTP::WebTest
CPAN shell
perl -MCPAN -e shell install HTTP::WebTest
For more information on module installation, please visit the detailed CPAN module installation guide.