# $Id: Plugins.pod,v 1.7 2003/03/02 11:52:10 m_ilya Exp $

=head1 NAME

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

=head1 SYNOPSIS

Not applicable.

=head1 DESCRIPTION

This document is the 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.  A plugin is just a Perl package that 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 a subclass of L<HTTP::WebTest::Plugin|HTTP::WebTest::Plugin>.
L<HTTP::WebTest::ReportPlugin|HTTP::WebTest::ReportPlugin> defines
some helper methods useful in report plugins and handles some test
parameters common for report plugins.

=head1 REQUIRED METHODS

Each plugin package must provide following method:

=head2 param_types

=head3 Returns

A string that contains information about supported test parameters and
their types.

String has following format:

    PARAM1 TYPE1 PARAM2 TYPE2 PARAM3 TYPE3 ... PARAMN TYPEN

PARAM is the name of a test parameter and TYPE is it's type
specification.  They should be separated by a whitespace character.

Each test parameter type is defined by a 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 - these methods
define all known test types.

=head3 Example

    sub param_types {
        return q(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 the test parameters C<ignore_case>, C<text_forbid>,
C<text_require>, C<regex_forbid> and C<regex_require>.  C<yesno> and
C<list> are test parameter types.

=head1 OPTIONAL METHODS

Each plugin package may provide following methods:

=head2 start_tests ()

Called before runing test sequence.  Initializations can be done
in this method.  Report plugins can use this hook to create the report header.

=head2 end_tests ()

Called when test sequence is finished.  Clean-up and finalization can be
done in this method.  Report plugins can use this hook to finish
the report.

=head2 prepare_request ()

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

=head2 check_response ()

Called after L<HTTP::WebTest|HTTP::WebTest> gets the
HTTP response.  Web page tests should be placed here.

=head2 report_test ()

Called after all L<HTTP::WebTest|HTTP::WebTest> 
<check_response> hooks are called.  Normally used by report plugins to generate
report about test just done.

=head3 Returns

These methods should return results of tests made in the following
form:

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

C<TEST_GROUP_NAME> is a string that describes a group of web tests
and their results.  It is used during the generation of the test report.

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

=head1 EXAMPLES

Some examples of plugins are:

=over 4

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

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

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

Simple plugin that defines only the C<check_response> hook.

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

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

=back

=head1 COPYRIGHT

Copyright (c) 2001-2003 Ilya Martynov.  All rights reserved.

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

=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