The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
HTTP-WebTest-1.99_01
River stage one • 1 direct dependent • 1 total dependent
++
/ HTTP::WebTest

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:

perldoc HTTP::WebTest::Reference - description of test specification, list of test types and reports provided by default plugins.

perldoc HTTP::WebTest::Cookbook - examples of wtscript files and example of HTTP::WebTest API usage.

perldoc HTTP::WebTest::Plugins - for developers of HTTP::WebTest plugins.

Those documents cover basic usage of HTTP::WebTest. This document describes 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 undef if you don't need it.

  • $num_succed_ref

    A reference on scalar where a number of passed tests will be stored or undef if 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 undef if you don't need it.

  • $num_succed_ref

    A reference on scalar where a number of passed tests will be stored or undef if 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.

SEE ALSO

HTTP::WebTest::Reference

HTTP::WebTest::Reference

HTTP::WebTest::Plugins

wt