|
NAMEHTTP::WebTest - Testing static and dynamic web contentSYNOPSISuse HTTP::WebTest; my $webtest = new HTTP::WebTest; # run test from file $webtest->run_wtscript('script.wt'); # or (to pass test parameters as method arguments) $webtest->run_tests($tests); DESCRIPTIONIntroductionThis module runs tests on remote URLs containing Perl/JSP/HTML/JavaScript/etc. and generates a detailed test report. This module can be used "as-is" or its functionality can be extended using plugins. Plugins can define test types and provide additional report capabilities. This module comes with a set of default plugins but can be easily extended with third party plugins.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 startedThis module has complex functionality, but using it to run simple tests is simple. Create a file of test parameters in the wtscript format and use the wt program to process the file using the command "wt filename". The only required parameters are "test_name" and "url".This document describes:
See "perldoc wt" for documentation on the wt program. Other useful documentation is:
TEST SPECIFICATIONThe test specifications can be read from a parameter file (in the wtscript format described below) or passed as method arguments as an array of hashes.Running HTTP::WebTest using a parameter file"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" 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:
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 programIf you are using the Perl API of "HTTP::WebTest", the test parameters can be defined as an array of hashes.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); PLUGIN MODULESCore plugin modules"HTTP::WebTest" is implemented in a modular structure that allows programmers to easily add modules to run additional tests or define additional simple tests without writing a module. "HTTP::WebTest" provides a number of core plugin modules which are loaded by default:
Information about test parameters supported by core plugins is summarized below in the section TEST PARAMETERS. Other plugin modules bundled with HTTP::WebTestFollowing plugin modules come with HTTP::WebTest but they are not loaded by default. To use such plugin module load it using global test parameter "plugins".
Information about test parameters supported by add-on plugin modules is summarized below in section TEST PARAMETERS. Plugin modules released separately from HTTP::WebTestFollowing additional "HTTP::WebTest" plugins are avialable separately from CPAN.
Writing plugin modulesSee perldoc HTTP::WebTest::Plugins for information about writing HTTP::WebTest plugin modules.ADD-ONSBesides additional plugins other HTTP::WebTest add-ons are available from CPAN:
TEST PARAMETERSMost parameters can be used as both global and test block parameters. If you specify such parameter outside a test block, that value is the default value for all test blocks. The global value can be overriden in each test block by specifying the parameter within the test block.Parameters marked as GLOBAL PARAMETER can be used only as global and cannot be overriden in test blocks. Parameters marked as NON-CORE PARAMETER are defined in add-on plugin modules which must be loaded explicitly using the parameter "plugins". accept_cookiesOption to accept cookies from the web server.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" authA list which contains two elements: userid/password pair to be used for web page access authorization.click_buttonNON-CORE PARAMETER from HTTP::WebTest::Plugin::ClickGiven 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_linkNON-CORE PARAMETER from HTTP::WebTest::Plugin::ClickGiven 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. cookieSynonym to "cookies".It is deprecated parameter and may be removed in future versions of HTTP::WebTest. cookiesThis is a list parameter that specifies cookies to send to the web server:cookies = ( cookie1_spec cookie2_spec ... cookieN_spec ) Currently there are two ways to specify a cookie.
Example (wtscript file): 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 ) ) Example (Perl script): my $tests = [ ... { test_name => 'cookie', cookies => [ [ name => 'Cookie1', value => 'Value', ], [ name => 'Cookie2', value => 'Value', path => '/', ] ], ... } ... ]
An example cookie would look like: 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_reportGLOBAL PARAMETERThis 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" delayNON-CORE PARAMETER from HTTP::WebTest::Plugin::DelayDuration of pause (in seconds) before running test. Allowed values Any number greater that zero. end_testThis is not really a parameter, it is part of wtscript format. It marks the end of test block.fh_outGLOBAL PARAMETERA 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_nameNON-CORE PARAMETER from HTTP::WebTest::Plugin::ClickGive 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_redirectsIf set to "yes" then HTTP-WebTest automatically follows redirects. It means that you never see HTTP responses with status codes 301 and 302. This feature is disabled if this test parameter is set to "no".Allowed values "yes", "no" Default value "yes" http_headersA list of HTTP header/value pairs. Can be used to override default HTTP headers or to add additional HTTP headers.Example http_headers = ( Accept => text/plain, text/html ) ignore_caseOption to do case-insensitive string matching for "text_forbid", "text_require", "regex_forbid" and "regex_require" test parameters.Allowed values "yes", "no" Default value "no" Option to e-mail output to one or more addresses specified by "mail_addresses" test parameter. mail_addressesGLOBAL PARAMETERA list of e-mail addresses where report will be send (if sending report is enabled with "mail" test parameter).
Default value "no" mail_failure_subjectGLOBAL PARAMETERSets "Subject" header for test report e-mails when some tests fail. In this string some character sequences have special meaning:
Default Value "WEB TESTS FAILED! FOUND %f ERROR(S)" mail_fromGLOBAL PARAMETERSets From: header for test report e-mails. Default Value Name of user under which test script runs. mail_serverGLOBAL PARAMETERFully-qualified name of of the mail server (e.g., mailhost.mycompany.com). Default value "localhost" mail_success_subjectGLOBAL PARAMETERSets "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_bytesMaximum number of bytes expected in returned page.Allowed values Any integer greater that zero and greater than "min_bytes" (if "min_bytes" is specified). max_rtimeMaximum web server response time (seconds) expected.Allowed values Any number greater that zero and greater than "min_rtime" (if "min_rtime" is specified). methodHTTP request method.See RFC 2616 (HTTP/1.1 protocol). Allowed values "GET", "POST" Default value "GET" min_bytesMinimum number of bytes expected in returned page.Allowed values Any integer less than "max_bytes" (if "max_bytes" is specified). min_rtimeMinimum web server response time (seconds) expected.Allowed values Any number less than "max_rtime" (if "max_rtime" is specified). on_finishNON-CORE PARAMETER from HTTP::WebTest::Plugin::HooksThe 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_requestNON-CORE PARAMETER from HTTP::WebTest::Plugin::HooksThe 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_responseNON-CORE PARAMETER from HTTP::WebTest::Plugin::HooksThis 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_startNON-CORE PARAMETER from HTTP::WebTest::Plugin::HooksThe 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_refGLOBAL PARAMETERA 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. paramsA 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.)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
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". pauthA list which contains two elements: userid/password pair to be used for proxy server access authorization.pluginsGLOBAL PARAMETERA 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 ) proxiesA list of service name/proxy URL pairs that specify proxy servers to use for requests.Example proxies = ( http => http://http_proxy.mycompany.com ftp => http://ftp_proxy.mycompany.com ) regex_forbidList of regular expressions that are forbidden to exist in the returned page.For more information, see perldoc perlre or see Programming Perl, 3rd edition, Chapter 5. See also the "text_forbid" and "ignore_case" parameters. regex_requireList of regular expressions that are required to exist in the returned page.For more information, see perldoc perlre or see Programming Perl, 3rd edition, Chapter 5. See also the "text_require" and "ignore_case" parameters. relative_urlsIf set to "yes" than "HTTP-WebTest" supports relative URLs. See test parameter "url" for more information.Allowed values "yes", "no" Default value "no" send_cookiesOption to send cookies to web server. This applies to cookies received from the web server or cookies specified using the "cookies" test parameter.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_cookiesOption to display any cookies sent or received.Allowed values "yes", "no" Default value "no" show_headersInclude request and response headers in the test report.Allowed values "yes", "no" Default value "no" show_htmlInclude content of HTTP response in the test report.Allowed values "yes", "no" Default value "no" status_codeGiven numeric HTTP Status Code, tests response returned that value.Default value 200 (OK). terseOption to display shorter test report.
Default value "no" test_nameName associated with this URL in the test report and error messages.text_forbidList of text strings that are forbidden to exist in the returned page.See also the "regex_forbid" and "ignore_case" parameters. text_requireList of text strings that are required to exist in the returned page.See also the "regex_require" and "ignore_case" parameters. timeoutSet the timeout value in seconds.Default value 180 urlURL to test.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_agentSet the product token that is used to identify the user agent on the network.Default value "HTTP-WebTest/NN" where "NN" is version number of HTTP-WebTest. RESTRICTIONS / BUGSThis module have been tested only on Unix (e.g., Solaris, Linux, AIX, etc.) but it should work on Win32 systems.If you want to test https:// web sites you may have to install additional modules to enable SSL support in LWP. In short you may have to install Crypt::SSLeay module. For details see README.SSL file in LWP distro. AUTHORSRichard Anderson <richard@richard-anderson.org> wrote "HTTP::WebTest 1.xx", using some ideas from the CPAN Monkeywrench module.Ilya Martynov <ilya@martynov.org> implemented the plug-in concept, the extended API and completely rewrote "HTTP::WebTest". Please don't email authors directly. Use the SourceForge "HTTP::WebTest" mail list (see SUPPORT, next section). SUPPORTPlease email bug reports, suggestions, questions, etc. to the SourceForge "HTTP::WebTest" maillist. You can sign up at http://lists.sourceforge.net/lists/listinfo/http-webtest-general . The email address is "http-webtest-general@lists.sourceforge.net".COPYRIGHTCopyright (c) 2000-2001 Richard Anderson. All rights reserved.Copyright (c) 2001-2003 Ilya Martynov. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. SEE ALSOHTTP::WebTest::CookbookHTTP::WebTest::API HTTP::WebTest::Plugins wt POD ERRORSHey! The above document had some coding errors, which are explained below:
Visit the GSP FreeBSD Man Page Interface. |