/ 
Monkeywrench-1.0
River stage zero No dependents
/ HTTP::Monkeywrench

NAME

HTTP::Monkeywrench - Web testing application

SYNOPSIS

use HTTP::Monkeywrench;
 $session = [
   {
   name  =E<gt> 'URL Name',
   url   =E<gt> 'http://url',
   }
 ];
 HTTP::Monkeywrench-E<gt>test($session);

REQUIRES

CGI
Net::SMTP
HTTP::Cookies
LWP::UserAgent
Time::HiRes
Data::Dumper

EXPORTS

None

DESCRIPTION

HTTP::Monkeywrench is a test-harness application to test the integrity of a user's path through a web site.

To run HTTP::Monkeywrench->test(), first set up a Perl script that contains sessions (described below), settings if desired (also described below), and a call to HTTP::Monkeywrench->test(), passing it the settings hashref first, followed by the desired session hashrefs you want to test. HTTP::Monkeywrench->test($settings, $session1,... $sessionN)

HTTP::Monkeywrench can also be used in an object-oriented fashion -- simply take the result of HTTP::Monkeywrench->new (optionally passing the settings hashref) and call the test() method against it as above (optionally omitting the settings hashref.)

Each session arrayref contains one or more hashrefs, called clicks, which contain descriptive elements of a specific web page to be tested. The elements are described below under SESSION.

SESSION

$session1 (ARRAYREF of HASHREFS)

A session is an arrayref of complex hashrefs that can be sent to the HTTP::Monkeywrench->test application to perform tests on a website as a virtual user.

The following keys can be in each 'Click' hashref. Fields with a "*" are required:

name (SCALAR)

A name to visually reference that 'click' in the reports

*url (SCALAR)

The url for Monkeywrench to test for that click.

params (HASHREF)

The params to send to dynamic pages and cgi's. Params should be set up as such: { username => 'joe', password => 'blow' }

method (SCALAR)

'method' should be either 'POST' or 'GET'. If method is left blank, method will default to 'GET'.

auth (ARRAYREF)

'auth' is the username and password if the site your are testing is password protected. 'auth' params must be passed to each element of a session that is accessing the same site. Example: ['username','password']

success_res (ARRAYREF)

An arrayref of items for Monkeywrench to test for their existence. Each element of the array can either be a text string or a regexp object. If a string from success_res is not found in the page, Monkeywrench will report an error. EXAMPLE: ['string',qr/regexp_object/,'etc']

error_res (ARRAYREF)

The same as success_res, except that an error will only be reported if strings in error_res ARE found on the page being tested.

cookies (ARRAYREF of ARRAYREFS)

A preset cookie can be sent to a page. In order to send a cookie to a page the following elements should be included as an arrayref:

[$version, $key, $val, $path, $domain, $port, $path_spec, $secure, $maxage, $discard, \%rest]

An example cookie would look like:

[['0', 'sessnum', 'expires&2592000&type&consumer', '/','cookiemonster.org', '8014', '', '', '2000-09-11 16:15:15Z', '']],

acceptcookie (BIT)

A numeric flag set to 1 or 0 to tell Monkeywrench if it should accept and save a cookie passed from a server. Default is 0, cookies will not be accepted.

sendcookie (BIT)

A numeric flag set to 1 or 0 to tell Monkeywrench to send a saved or pre made cookie back to the server. Default is 0, cookies will not be sent.

showhtml (BIT)

A numeric flag set to 1 or 0 to have the source html of a page displayed within the report. When set to 1 the reports can get messy if the page is heavy on html.

SETTINGS HASH

$settings (HASHREF)

The settings hash is optional as are each of the elements of $settings. Elements that are not declared or set are defaulted to 0 (off).

match_detail (BIT)

A numeric flag set to 1 or 0. If set to 1 Match detail shows all of the reports of success_res and error_res no matter if they pass or fail.

show_cookies (BIT)

A numeric flag set to 1 or 0. If set to 1 show_cookies will show all the cookies in the report, either passed from the session or sent from the server.

smtp_server (SCALAR)

The SMTP server to be used by Net::SMTP. Only required if user wants output of Monkeywrench to be sent to an email address.

send_mail (ARRAYREF)

The send_mail arrayref is also only required if user plans on sending output to one or more email addresses.

send_if_err (BIT)

The send_if_err bit is a flag that should be set to either 1 or 0 and is only used if the user wants the Monkeywrench output sent via email. If set to 1 the output will only be sent to the email address(es) in the event of a failure in the success or error checking or any result code other than 200.

If set to 1, the results will be printed to the screen. If set to 0 nothing will be printed to the screen. The default setting is 1.

METHODS

new ( [ \%settings ] )

Returns a new Monkeywrench object. Optionally takes a settings hash.

settings ( $self, [ \%settings ] )

Returns settings hash. Passing hashref will change settings in object.

test ( [ \%settings ], \@session [ , \@session, ... ] )

Usable as both a static method and object method. Runs a series Monkeywrench tests on a web server using the parameters set forth in the sessions you pass.

get_response ($click)

get_response is a recursive method that loops through all possible redirects until a final response is returned, which is then returned to the caller.

send_monkeymail ( $content, \$smtp_server \@address )

send_monkeymail is called if the config script has an email address and depending on how send_if_err is setup. $content is the output of the session(s) called by the config script and the \@address arrayref contains the address(es) that the output will be sent to. $smtp_server is the smtp server for Net::SMTP to connect to and is also required in order for send_monkeymail to be called.

REVISION HISTORY $Log: Monkeywrench.pm,v $ Revision 1.13 2000/09/12 00:14:54 david More POD fixes.

Revision 1.12  2000/09/08 01:40:23  greg
removed C<> surrounding SYNOPSIS as it was breaking pod2html.

Revision 1.10  2000/09/08 01:01:10  greg
fixed POD

Revision 1.9  2000/09/08 00:37:49  david
 - Moved and rearranged some POD.

Revision 1.8  2000/09/07 22:26:26  derek
 - Removed _init method and incoporated code into new method.
 - Added a return obj that is populated during the test method and is returned
   at the end of the test method.
 - Other misc code changes for efficiency and readability.
 - Fixed minor POD problems and added documentation for new settings.

Revision 1.7  2000/09/06 21:49:35  david
 - Changed POD formatting (looks better in a POD reader, not in an editor.)
 - added some extra sanity to send_monkeymail()

Revision 1.6  2000/09/01 23:10:51  derek
 - Documentation fixes, additions.

Revision 1.5  2000/08/23 21:25:37  derek
 - Added send_monkeymail method to handle sending reports via email.
 - Modified test method to put all output data into $content variable instead
   of printing each chunk separately.
 - Added documentation for send_monkeymail method, new oop features, and new
   settings options for the config files.

Revision 1.4  2000/08/03 01:03:34  david
 now uses strict (no change required)
OO enhancements
 - initialization portion of test() method moved to methods new(), _init(),
   and settings(), test() works as an object method, but still works as a
   static method. Objects are reusable (you can call test any number of times.)
 - settings(), cgi(), cookie_jar(), and ua() access methods set up to make
   more extensible

Revision 1.3  2000/02/28 23:52:07  derek
 - Added and changed lots of POD
 - Added new report element, Code, to display the response code of the page

Revision 1.2  2000/02/18 03:36:18  derek
 - Fixed logic problem in reading the settings from what user passes
 - Fixed minor display issue

Revision 1.1.1.1  2000/02/17 21:04:05  derek
 - Start

SEE ALSO

perl(1).

KNOWN BUGS

None

TODO

  • Recorder Utility

  • Recorder Utility - Currently, scenarios must be created painstakenly by editing complex conf files. A better solution would be a CGI or mod_perl handler which 'watches' you surf a site and creates the configuration script for you.

  • Link checking ability (checks integrity of all links on the pages it checks)

  • HTML checking - Checks the HTML on pages for HTML compliance (you can optionally specify the HTML w3c spec you want to comply to). We might integrate WebLINT or other packages which do this (they may even check links).

  • Load Testing - Most load testing tools hit one page over and over measuring how many simultaneous requests per second a site can handle. This approach is highly flawed since it does not approximate true traffic on your site where lots of people might be performing different actions on your site at the same time (not just pounding one page.) Monkeywrench is well suited to being a true load testing tool where multiple sessions, mimicking actual users doing lots of different things on your site, are run simultaneously to see how many requests a second your site can handle under more realistic conditions. We envision adding a client server componant to the load balancing tool that would let you run Monkeywrench clients on lots of machines all hitting the same site. Then a Monkeywrench server would collect and report on the results.

  • Configuration - Currently, the test scenarios reside in configuration scripts which you run directly. It would be better if the configuration information was separated from the script which reads and runs the configuration information. One idea is to store configuration/session info into XML files which you could just pass to Monkeywrench at the command line.

  • Write more, longer TODOs.

COPYRIGHT

Copyright (c) 2000, Cnation Inc. All Rights Reserved. This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.

AUTHORS

Derek Cline 	<derek@cnation.com>
Adam Pisoni	<adam@cnation.com>
David Pisoni	<david@cnation.com>