NAME

HTTP::WebTest::API - API of HTTP::WebTest

SYNOPSIS

    use 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);

DESCRIPTION

This document describes Perl API of "HTTP::WebTest".

METHODS

new ()

Constructor.

Returns

A new "HTTP::WebTest" object.

run_tests ($tests, $optional_params)

Runs a test sequence.

Parameters

$test
A reference to an array that contains test objects.
$optional_params
A reference to a hash that contains optional global parameters for test.

run_wtscript ($wtscript, $optional_params)

Reads wtscript and runs tests it defines.

Parameters

$wtscript
Either the name of wtscript file or wtscript passed as string. Very simple heuristic is used distinguish first from second. If $wtscript contains either "\n" or "\r" it is treated as a wtscript string. Otherwise, it is treated as a file name.
$optional_params

A reference to a hash that contains optional test parameters that can override parameters defined in wtscript.

have_succeed ()

Returns

True if all tests have passed, false otherwise.

parser_package($optional_parser_package)

If $optional_parser is defined sets a parser package to use when parsing wtscript files. Otherwise just returns current parser package.

Returns

The parser package.

parse ($data)

Parses test specification in wtscript format.

Parameters

•: $data
Scalar that contains test specification in wtscript format.

Returns

A list of two elements. First element is a reference to an array that contains test objects. Second element is a reference to a hash that contains optional global test parameters.

It can be passed directly to "run_tests".

Example

    $webtest->run_tests($webtest->parse($data));

LOW-LEVEL API METHODS

Most users don't need to use this part of "HTTP::WebTest" API directly. It could be useful for users who want to:

Write an "HTTP::WebTest" plugin.
Get access to LWP::UserAgent, HTTP::WebTest::Request, HTTP::Response and other objects used by "HTTP::WebTest" during runing test sequence.

tests ()

Returns

A reference to an array that contains test objects.

user_agent ($optional_user_agent)

If $optional_user_agent is a user agent object, it is used by the "HTTP::WebTest" object for all requests. If $optional_user_agent is passed as undef, the HTTP::WebTest object is reset to use the default user agent.

Returns

The user agent object used by the "HTTP::WebTest" object.

plugins ($optional_plugins)

If $optional_plugins is a reference to an array that contains plugin objects, the "HTTP::WebTest" object uses these plugins while running tests. If $optional_plugins is passed as undef, the "HTTP::WebTest" object is reset to use the default set of plugins.

Returns

A reference to an array that contains plugin objects. If you add or remove plugin objects in this array, you will change the set of plugins used by "HTTP::WebTest" object during tests.

create_user_agent ()

Returns

A new LWP::UserAgent object, initialized with default settings.

reset_user_agent ()

Resets the user agent to the default.

reset_plugins ()

Resets the set of plugin objects to the default set.

default_plugins ()

Returns

A reference to the set of default plugin objects.

global_test_param ($param)

Returns

The value of the global test parameter $param.

current_test_num ()

Returns

The number of the current test or, if no test is running, the current test run.

current_test ()

Returns

The HTTP::WebTest::Test object which corresponds to the current test or, if no test is running, the current test run.

current_request ()

Returns

The HTTP::WebTest::Request object used in current test.

current_response ()

Returns

The HTTP::Response object used in current test.

current_response_time ()

Returns

The response time for the HTTP request used in current test.

current_results ()

Returns

A reference to an array that contains the results of checks made by plugins for the current test.

run_test ($test, $optional_params)

Runs a single test.

Parameters

$test
A test object.
$optional_params
A reference to a hash that contains optional global test parameters.

convert_tests (@tests)

Converts test objects @tests of any supported type to internal canonical representation (i.e. to HTTP::WebTest::Test objects).

Returns

A list of HTTP::WebTest::Test objects (list context) or the first value from a list of HTTP::WebTest::Test objects (scalar context).

BACKWARD COMPATIBILITY

"HTTP::WebTest 2.xx" offers a richer API than its predecessor "HTTP::WebTest 1.xx". The old API is still supported, but may be deprecated in the future and is not recommended.

web_test ($file, $num_fail_ref, $num_succeed_ref, $optional_options)

Reads wtscript file and runs tests it defines.

In "HTTP::WebTest 2.xx" you should use method "run_wtscript".

Parameters

$file
Name of a 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 to a hash that 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 to either import "run_web_test" into you namespace with

    use HTTP::WebTest qw(run_web_test);

or use the full name "HTTP::WebTest::run_web_test"

In "HTTP::WebTest 2.xx" you should use the method "run_tests".

Parameters

$tests
A reference to an array that contains a set of test objects.
$num_fail_ref
A reference to a scalar where the number of failed tests will be stored or "undef" if you don't need it.
$num_succed_ref
A reference to a scalar where the number of passed tests will be stored or "undef" if you don't need it.
$optional_params
A reference to a hash that contains optional test parameters.

COPYRIGHT

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

NAME

SYNOPSIS

DESCRIPTION

METHODS

new ()

run_tests ($tests, $optional_params)

run_wtscript ($wtscript, $optional_params)

num_fail ()

num_succeed ()

have_succeed ()

parser_package($optional_parser_package)

parse ($data)

LOW-LEVEL API METHODS

tests ()

user_agent ($optional_user_agent)

plugins ($optional_plugins)

create_user_agent ()

reset_user_agent ()

reset_plugins ()

default_plugins ()

global_test_param ($param)

current_test_num ()

current_test ()

current_request ()

current_response ()

current_response_time ()

current_results ()

run_test ($test, $optional_params)

convert_tests (@tests)

BACKWARD COMPATIBILITY

web_test ($file, $num_fail_ref, $num_succeed_ref, $optional_options)

run_web_test ($tests, $num_fail_ref, $num_succeed_ref, $optional_options)

COPYRIGHT

SEE ALSO