NAME
HTTP::WebTest - Test remote URLs or local web files
SYNOPSIS
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.
DESCRIPTION
Introduction
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:
-------------- -------------
| | | |
| 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 ----------------------
------------Getting Started
If you are new to HTTP::WebTest 2.xx you should read:
HTTP::WebTest::Reference docs - description of test specification, list of test types and reports provided by default plugins.
HTTP::WebTest::Plugins docs - for developers of HTTP::WebTest plugins.
Those documents cover basic usage of HTTP::WebTest. Read this document further if you want to learn advanced capabilites provided by Perl API of HTTP::WebTest.
METHODS
new
Constructor.
Returns
A new HTTP::WebTest object.
tests
Returns
A reference on array which contains test objects.
user_agent ($optional_user_agent)
Can switch user agent used by HTTP::WebTest object if $optional_user_agent is a user agent object. If it is passed as undef resets HTTP::WebTest object to use default user agent.
Returns
An user agent object used by HTTP::WebTest object.
plugins ($optional_plugins)
Can set plugins to be used during tests if $optional_plugins is a reference on array which contains plugin objects. If it is passed as undef resets HTTP::WebTest object to use default set of plugins.
Returns
A reference on array which contains plugin objects. Note that if you add or remove plugin objects to this array it will change set of plugins used by HTTP::WebTest object during tests.
create_user_agent
Returns
A new default user agent.
reset_user_agent
Resets user agent to default.
reset_plugins
Resets set of plugin objects to default.
default_plugins
Returns
A reference on set of default plugin objects.
global_test_param ($param)
Returns
A value of global test sequence parameter $param.
last_test
Returns
A test object which corresponds to last test being or been run.
last_request
Returns
A request object used in last test.
last_response
Returns
A response object returned for last request.
last_response_time
Returns
A response time for last request.
last_results
Returns
A reference on array which contains results of checks made by plugins for last test.
run_test ($test, $optional_params)
Runs single test.
Parameters
$test
A test object.
$optional_params
A reference on hash which contains optional global parameters for test.
run_tests ($tests, $optional_params)
Runs a test sequence.
Parameters
$test
A reference on array which contains test objects.
$optional_params
A reference on hash which contains optional global parameters for test.
convert_tests (@tests)
Converts test objects @tests of any supported type to canonic representation (i.e. to HTTP::WebTest::Test objects).
Returns
A list of HTTP::WebTest::Test objects in list context or first value from list of HTTP::WebTest::Test object in scalar context.
validate_test ($test)
Validates test.
Returns
A hash with results of checks.
parse ($data)
Parses wtscript passed in scalar variable $data.
Returns
A reference on an array which contains test objects.
run_wtscript ($file, $optional_params)
Reads wtscript and runs tests it defines.
Parameters
$file
A filename of wtscript file.
$optional_params
A reference on hash which contains optional test parameters which can override parameters defined in wtscript.
num_fail
Returns
A number of failed tests.
num_succeed
Returns
A number of passed tests.
have_succeed
Returns
True if all tests have been passed.
BACKWARD COMPATIBILITY
HTTP::WebTest 2.xx offers more rich API than its predecessor HTTP::WebTest 1.xx. However while deprecated old API is still supported.
It is not recommended to use it in new applications.
web_test ($file, $num_fail_ref, $num_succeed_ref, $optional_options)
Reads wtscript and runs tests it defines.
In HTTP::WebTest 2.xx you should use method run_wtscript.
Parameters
$file
A filename of wtscript file.
$num_fail_ref
A reference on scalar where a number of failed tests will be stored or
undefif you don't need it.$num_succed_ref
A reference on scalar where a number of passed tests will be stored or
undefif you don't need it.$optional_params
A reference on hash which contains optional test parameters which can override parameters defined in wtscript.
run_web_test ($tests, $num_fail_ref, $num_succeed_ref, $optional_options)
This is not a method. It is subroutine which creates a HTTP::WebTest object and runs test sequence using it.
You need either import run_web_test into you namespace with
use HTTP::WebTest qw(run_web_test);or use full name HTTP::WebTest::run_web_test
In HTTP::WebTest 2.xx you should use method run_tests.
Parameters
$tests
A reference on array which contains a set of test objects.
$num_fail_ref
A reference on scalar where a number of failed tests will be stored or
undefif you don't need it.$num_succed_ref
A reference on scalar where a number of passed tests will be stored or
undefif you don't need it.$optional_params
A reference on hash which contains optional test parameters.
RESTRICTIONS / BUGS
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.
AUTHOR
Richard Anderson <Richard.Anderson@unixscripts.com> have wrote 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
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.