CGI::Test 0.104

CGI::Test is a CGI regression test framework.

SYNOPSIS

# In some t/script.t regression test, for instance
use CGI::Test; # exports ok()

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");
ok 1, $page->content_type =~ m|text/htmlb|;

my $form = $page->forms->[0];
ok 2, $form->action eq "/cgi-bin/some_target";

my $menu = $form->menu_by_name("months");
ok 3, $menu->is_selected("January");
ok 4, !$menu->is_selected("March");
ok 5, $menu->multiple;

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

#
# Now interact with the CGI
#

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

The 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 youre using the 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. 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 scripts control widgets, finally submitting data back. And so on...
Note that the CGI scripts you can test with 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 CGI::Test framework, you need to configure a 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 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 CGI::Test::Page for details).

The latter (an HTML page) can contain one or more CGI forms (identified by

tags), which are described by instances of CGI::Test::Form objects (see 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 (thats 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 CGI::Test::Form::Widget type. The specific interaction that is offered depends on the dynamic type of the object (see 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 CGI::Test framework, and the CGI script is ran through a proper call to one of the GET/POST method on the CGI::Test object.

Finally, since CGI::Test is meant to be used from regression test scripts, it exports a single ok() routine which merely prints the messages expected by Test::Harness. This is the only functional routine in this module, all other accesses being made through a CGI::Test object.