view release on metacpan or  search on metacpan

lib/CGI/Test.pm  view on Meta::CPAN

    open(FILE, $file) || warn "can't open $file: $!";
    local $_;
    my $field;

    while (<FILE>)
    {
        last if /^\015?\012$/ || /^\015\012$/;
        s/\015?\012$//;
        if (s/^\s+/ /)
        {
            last if $field eq '';    # Cannot be a header
            $header{$field} .= $_ if $field ne '';
        }
        elsif (($field, my $value) = /^([\w-]+)\s*:\s*(.*)/)
        {
            $field =~ s/(\w+)/\u\L$1/g;    # Normalize spelling
            if (exists $header{$field})
            {
                warn "duplicate $field header in $file";
                $header{$field} .= " ";
            }
            $header{$field} .= $value;
        }
        else
        {
            warn "mangled header in $file";
            %header = ();                  # Discard what we read sofar
            last;
        }
    }
    close FILE;
    return \%header;
}

1;

=head1 NAME

CGI::Test - CGI regression test framework

=head1 SYNOPSIS

 # In some t/script.t regression test, for instance
 use CGI::Test;
 use Test::More tests => 7;

 my $ct = CGI::Test->new(
    -base_url   => "http://some.server:1234/cgi-bin",
    -cgi_dir    => "/path/to/cgi-bin",
 );

 my $page = $ct->GET("http://some.server:1234/cgi-bin/script?arg=1");
 like $page->content_type, qr|text/html\b|, "Content type";

 my $form = $page->forms->[0];
 is $form->action, "/cgi-bin/some_target", "Form action URI";

 my $menu = $form->menu_by_name("months");
 ok $menu->is_selected("January"), "January selected";
 ok !$menu->is_selected("March"),  "March not selected";
 ok $menu->multiple,               "Menu is multi-choice";

 my $send = $form->submit_by_name("send_form");
 ok defined $send, "Send form defined";

 #
 # Now interact with the CGI
 #

 $menu->select("March");        # "click" on the March label
 my $answer = $send->press;     # "click" on the send button
 
 # and make sure we don't get an HTTP error
 ok $answer->is_ok, "Answer response";

=head1 DESCRIPTION

The C<CGI::Test> module provides a CGI regression test framework which
allows you to run your CGI programs offline, i.e. outside a web server,
and interact with them programmatically, without the need to type data
and click from a web browser.

If you're using the C<CGI> module, you may be familiar with its offline
testing mode.  However, this mode is appropriate for simple things, and
there is no support for conducting a full session with a stateful script.
C<CGI::Test> fills this gap by providing the necessary infrastructure to
run CGI scripts, then parse the output to construct objects that can be
queried, and on which you can interact to "play" with the script's control
widgets, finally submitting data back.  And so on...

Note that the CGI scripts you can test with C<CGI::Test> need not be
implemented in Perl at all.  As far as this framework is concerned, CGI
scripts are executables that are run on a CGI-like environment and which
produce an output.

To use the C<CGI::Test> framework, you need to configure a C<CGI::Test>
object to act like a web server, by providing the URL base where
CGI scripts lie on this pseudo-server, and which physical directory
corresponds to that URL base.

From then on, you may issue GET and POST requests giving an URL, and
the pseudo-server returns a C<CGI::Test::Page> object representing the
outcome of the request.  This page may be an error, plain text, some
binary data, or an HTML page (see L<CGI::Test::Page> for details).

The latter (an HTML page) can contain one or more CGI forms (identified
by C<E<lt>FORME<gt>> tags), which are described by instances of
C<CGI::Test::Form> objects (see L<CGI::Test::Form> for details).

Forms can be queried to see whether they contain a particular type
of widget (menu, text area, button, etc...), of a particular name
(that's the CGI parameter name).  Once found, one may interact with
a widget as the user would from a browser.  Widgets are described by
polymorphic objects which conform to the C<CGI::Test::Form::Widget> type.
The specific interaction that is offered depends on the dynamic type of
the object (see L<CGI::Test::Form::Widget> for details).

An interaction with a form ends by a submission of the form data to the
server, and getting a reply back.  This is done by pressing a submit button,
and the press() routine returns a new page.  Naturally, no server is
contacted at all within the C<CGI::Test> framework, and the CGI script is