# $Id: Plugins.pod,v 1.2 2002/01/28 06:32:02 m_ilya Exp $

=head1 NAME

HTTP::WebTest::Plugins - Plugin developers documentation.

=head1 SYNOPSIS

Not applicable.

=head1 DESCRIPTION

This document is good starting point for developers who wish to extend
L<HTTP::WebTest|HTTP::WebTest> functionality with external plugins.

=head1 ABOUT PLUGINS

Plugin can be used to add new test types and add new report
types. Plugin is just a Perl package which defines class with a number
of methods which if present are called by
L<HTTP::WebTest|HTTP::WebTest> at various stages of test.

Each plugin package should subclass
L<HTTP::WebTest::Plugin|HTTP::WebTest::Plugin>. Report plugins can
subclass L<HTTP::WebTest::ReportPlugin|HTTP::WebTest::ReportPlugin>
which is subclass of L<HTTP::WebTest::Plugin|HTTP::WebTest::Plugin>
instead of
it. L<HTTP::WebTest::ReportPlugin|HTTP::WebTest::ReportPlugin> defines
some helper methods useful in report plugin and handles some test
parameters common for report plugins.

=head1 REQUIRED METHODS

Each plugin package should provide following method:

=head2 param_types

=head3 Returns

A hash reference on hash which contains information about supported
test parameters and their type.

Each test type is defined by method in
L<HTTP::WebTest::Plugin|HTTP::WebTest::Plugin>. Type C<foobar> is
defined as method C<check_foobar> in this package. See its
documentation for list of all C<check_****> methods which define all
known test types.

This method is used to validate values of test parameters. If
additional checks are required they can be defined in method
C<validate_params>. See below.

=head3 Example

    sub param_types {
        return { qw(ignore_case   yesno
                    text_forbid   list
                    text_require  list
                    regex_forbid  list
                    regex_require list) };
    }

This is from
L<HTTP::WebTest::Plugin::TextMatchTest|HTTP::WebTest::Plugin::TextMatchTest>.
It defines following test parameters: C<ignore_case>, C<text_forbid>,
C<text_require>, C<regex_forbid>, C<regex_require>. C<yesno> and
C<list> are test parameter types.

=head1 OPTIONAL METHODS

Each plugin package can provide following methods:

=head2 validate_params ($params)

This method can be defined in plugin packages to add additional checks
for test parameters which are not covered by test parameter types
specification defined by C<param_types>. If you define this method in
plugin package be sure to call C<$self->SUPER::validate_params($test)>.

=head3 Parameters

=over 4

=item * $params

A reference on hash which contains test parameters.

=back

=head3 Returns

This test should return hash with test parameter names as keys and
L<HTTP::WebTest::TestResult|HTTP::WebTest::TestResult> objects as
values.

=head3 Example

This example adds check for test parameter C<my_test_param>. It must
be equal to 'BlaBla' if this test parameter is specified.

    sub validate_params {
        my $self = shift;
        my $params = shift;

        # run default checks
        my %checks = $self->SUPER::validate_params($params);

        if($checks{my_test_param}) {
            my $ok = $params->{my_test_param} eq 'BlaBla';
            $checks{my_test_param} =
                $self->test_result($ok, 'Parameter my_test_param is not ' .
                                        'equal to BlaBla');
        }

	return %checks;
    }

=head2 start_tests ()

Called before runing test sequence. You can put here some
initalization. Report plugins can use this hook to create header of
report.

=head2 end_tests ()

Called when test sequence is finished. You can put here some
finialization code. Report plugins can use this hook to finish
creation of report.

=head2 prepare_request ()

Called before L<HTTP::WebTest|HTTP::WebTest> does HTTP
request. Various properties of request here can be set here.

=head2 check_response ()

Called once L<HTTP::WebTest|HTTP::WebTest> did HTTP request and have
got HTTP response. Test checks should be placed here.

=head2 report_test ()

Called when L<HTTP::WebTest|HTTP::WebTest> got HTTP response after
<check_response> hooks. Normally used by report plugins to generate
piece of report about test step just done.

=head3 Returns

This methods should return result of test checks made in following
form:

    [ [ TEST_GROUP1_NAME, TEST_RESULT1, TEST_RESULT2, ... ],
      [ TEST_GROUP2_NAME, TEST_RESULT1, TEST_RESULT2, ... ],
      ...
    ];

C<TEST_GROUP_NAME> is a string which describes a group of test checks
and their results. It is used during generation of test report.

C<TEST_RESULT> is an
L<HTTP::WebTest::TestResult|HTTP::WebTest::TestResult> object.

=head1 EXAMPLES

Well, why anybody need examples when source code of internal
L<HTTP::WebTest|HTTP::WebTest> plugins is available.

Some good examples are:

=over 4

=item L<HTTP::WebTest::Plugin::Cookies|HTTP::WebTest::Plugin::Cookies>

Plugin which uses both C<prepare_request> and C<check_response> hooks.

=item L<HTTP::WebTest::Plugin::StatusTest|HTTP::WebTest::Plugin::StatusTest>

Very simple plugin which defines only C<check_response> hook.

=item L<HTTP::WebTest::Plugin::DefaultReport|HTTP::WebTest::Plugin::DefaultReport>

Example of report plugin. Uses C<start_tests>, C<report_test> and
C<end_tests> hooks.

=back

=head1 COPYRIGHT

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.

=head1 SEE ALSO

L<HTTP::WebTest|HTTP::WebTest>

L<HTTP::WebTest::API|HTTP::WebTest::API>

L<HTTP::WebTest::Plugin|HTTP::WebTest::Plugin>

L<HTTP::WebTest::ReportPlugin|HTTP::WebTest::ReportPlugin>

=cut
