CGI::Test(3pm)

CGI::Test(3pm) — User Contributed Perl Documentation

✨ NAME ✨

CGI::Test — CGI regression test framework 🧪💖

🌸 SYNOPSIS 🌸

Ok bestie, here's the whole vibe in code, copy-paste exact:

# 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";

💖 DESCRIPTION 💖

The CGI::Test module is literally your CGI regression test framework, and it lets you run your CGI programs offline — like, outside a web server — and interact with them programmatically. No typing data, no clicking around in a browser. It's giving automation, periodt. ✨

If you're using the CGI module, you might already know its offline testing mode. But bestie, that mode is for simple things, and there's no support for a full session with a stateful script. CGI::Test fills that gap: it gives you the infrastructure to run CGI scripts, parse the output into objects you can query, interact with the script's control widgets to "play" with them, and finally submit data back. And so on... 🔁💅

Note that the CGI scripts you test with CGI::Test do not need to be implemented in Perl at all. As far as this framework cares, CGI scripts are executables that run in a CGI-like environment and produce an output. 💯

To use the CGI::Test framework, you configure a CGI::Test object to act like a web server. You give it the URL base where CGI scripts live on this pseudo-server, and which physical directory maps to that URL base. 🖥️🫶

From then on, you can issue GET and POST requests with a URL, and the pseudo-server returns a CGI::Test::Page object representing the outcome. That page could be an error, plain text, some binary data, or an HTML page (see CGI::Test::Page for details). 📄

The HTML page can contain one or more CGI forms (identified by <FORM> tags), 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 (that's the CGI parameter name). Once found, you can interact with a widget like a user would from a browser. Widgets are described by polymorphic objects that conform to the CGI::Test::Form::Widget type. The specific interaction offered depends on the dynamic type of the object (see CGI::Test::Form::Widget for details). 🎛️

An interaction with a form ends by submitting the form data to the server and getting a reply back. You do this 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 gets run through a proper call to one of the GET/POST method on the CGI::Test object. 🚀

🦋 INTERFACE 🦋

🎀 Creation Interface 🎀

The creation routine new() takes these mandatory parameters:

• -base_url — URL of the cgi-bin directory. Defines the URL domain handled by CGI::Test. This is the URL of the cgi-bin directory.

Note that you do not need anything actually running on the specified host or port, and the server name can be any host name, whether it exists or not. For instance, if you say:

-base_url => "http://foo.example.com:70/cgi-bin"

you simply declare that the CGI::Test object will know how to handle a GET request for, say:

http://foo.example.com:70/cgi-bin/script

and it will do so internally, without contacting foo.example.com on port 70... 😌

• -cgi_dir — path to the cgi-bin directory. Defines the physical path corresponding to the cgi-bin directory defined by the -base_url parameter.

For instance, given the settings:

-base_url => "http://foo.example.com:70/cgi-bin",
-cgi_dir  => "/home/ram/cgi/test"

then requesting

http://foo.example.com:70/cgi-bin/script

will actually run

/home/ram/cgi/test/script

Those things are really easier to understand via examples than via formal descriptions, aren't they? 😭💖

The following optional arguments may also be provided:

• -cgi_env — HASH ref. Defines additional environment variables that must be set, or changes hardwirted defaults. Some variables like CONTENT_TYPE really depend on the request and will be dynamically computed by CGI::Test.

For instance:

-cgi_env => {
    HTTP_USER_AGENT     => "Mozilla/4.76",
    AUTH_TYPE           => "Digest",
}

See "CGI ENVIRONMENT VARIABLES" for more details on which environment variables are defined, and which may be superseded. 🔧

• -doc_dir — path to document tree. This defines the root directory of the HTTP server, for path translation. It defaults to /var/www.

NOTE: CGI::Test only serves CGI scripts for now, so this setting is not terribly useful, unless you care about PATH_TRANSLATED.

• -tmp_dir — path to temporary directory. The temporary directory to use for internal files created while processing requests. Defaults to the value of the environment variable TMPDIR, or /tmp if it is not set.

👑 Object Interface 👑

The following methods, listed in alphabetical order, are available:

• GET url_string [, auth_user] — Issues an HTTP GET request of the specified URL, given as the string url_string. It must be in the http scheme, and must lie within the configured CGI space (i.e. under the base URL given at creation time via -base_url).

Optionally, you may specify the name of an authenticated user as the auth_user string. CGI::Test will simply setup the CGI environment variable REMOTE_USER accordingly. Since we're in a testing framework, you can pretend to be anyone you like. See "CGI ENVIRONMENT VARIABLES" for more information on environment variables, and in particular AUTH_TYPE.

GET returns a CGI::Test::Page polymorphic object, i.e. an object whose dynamic type is an heir of CGI::Test::Page. See CGI::Test::Page for more information on this class hierarchy. 🦋

• POST url_string, input_data [, auth_user] — Issues an HTTP POST request of the specified URL. See GET above for a discussion on url_string and auth_user, which applies to POST as well.

The input_data parameter must be a CGI::Test::Input object. It specifies the CGI parameters to be sent to the script. Users normally don't issue POST requests manually: they are the result of submits on forms, which are obtained via an initial GET. Nonetheless, you can create your own input easily and issue a "faked" POST request, to see how your script might react to inconsistent (and probably malicious) input for instance. See CGI::Test::Input to learn how to construct suitable input.

POST returns a CGI::Test::Page polymorphic object, like GET does. 📬

• base_path — The base path in the URL space of the base URL configured at creation time. It's the URL with the scheme, host and port information removed. 🛤️
• cgi_dir — The configured CGI root directory where scripts to be run are held. 📁
• doc_dir — The configured document root directory. 📚
• host_port — The host and port of the base URL you configured at creation time. 🌐
• split_uri URI — Splits an URI object into server (host and port), path and query components. The path is simplified using UNIX semantics, i.e. "/./" is ignored and stripped, and "/../" is resolved by forgetting the path component that immediately precedes it (no attempt is made to make sure the translated path was indeed pointing to an existing directory: simplification happens in the path space).

Returns the list (host, path, query). 🧩

• tmp_dir — The temporary directory that is being used. 🗂️
• http_headers — Returns hashref with parsed HTTP headers received from CGI script. 📨

🌸 CGI ENVIRONMENT VARIABLES 🌸

okay so the CGI protocol defines a set of environment variables which are to be set by the web server before invoking the script. The environment created by CGI::Test conforms to the CGI/1.1 specifications. no cap. 💖

Here is a list of all the known variables. Some of those are marked read-only. It means you may choose to set them via the -cgi_env switch of the new() routine, but your settings will have no effect and CGI::Test will always compute a suitable value. it's giving "the computer said no" energy. 😌

Variables are listed in alphabetical order:

AUTH_TYPE

The authentication scheme used to authenticate the user given by REMOTE_USER. This variable is not present in the environment if there was no user specified in the GET/POST requests.

By default, it is set to Basic when present. iconic. ✨

CONTENT_LENGTH

Read-only variable, giving the length of data to be read on STDIN by POST requests (as told by REQUEST_METHOD). It is not present for GET requests. fr fr. 💅

CONTENT_TYPE

Read-only variable, giving the MIME type of data to be read on STDIN by POST requests (as told by REQUEST_METHOD). It is not present for GET requests.

GATEWAY_INTERFACE

The Common Gateway Interface (CGI) version specification. Defaults to CGI/1.1. periodt. 💅

HTTP_ACCEPT

The set of Content-Type that are said to be accepted by the client issuing the HTTP request. Since there is no browser making any request here, the default is set to */*.

It is up to your script to honour the value of this variable if it wishes to be nice with the client. 🫶

HTTP_ACCEPT_CHARSET

The charset that is said to be accepted by the client issuing the HTTP request. Since there is no browser making any request here, the default is set to iso-8859-1. slay. ✨

HTTP_CONNECTION

Whether the connection should be kept alive by the server or closed after this request. Defaults to Close, but since there's no connection and no real client... 💀

HTTP_HOST

This is the host processing the HTTP request. It is a read-only variable, set to the hostname and port parts of the requested URL. 👑

HTTP_USER_AGENT

The user agent tag string. This can be used by scripts to emit code that can be understood by the client, and is also further abused to derive the OS type where the user agent runs.

In order to be as neutral as possible, it is set to CGI::Test by default. ✨

PATH_INFO

Read-only variable set to the extra path information part of the requested URL. Always present, even if empty. 💅

PATH_TRANSLATED

This read-only variable is only present when there is a non-empty PATH_INFO variable. It is simply set to the value of PATH_INFO with the document rootdir path prepended to it (the value of the -doc_dir creation argument). 🧚

QUERY_STRING

This very important read-only variable is the query string present in the requested URL. Note that it may very well be set even for a POST request. 🔥

REMOTE_ADDR

The IP address of the client making the request. Can be used to implement an access policy from within the script. Here, given that there's no real client, the default is set to 127.0.0.1, which is the IP of the local loopback interface. 🌈

REMOTE_HOST

The DNS-translated hostname of the IP address held in REMOTE_ADDR. Here, for testing purposes, it is not computed after REMOTE_ADDR but can be freely set. Defaults to localhost. 💖

REMOTE_USER

This read-only variable is only present when making an authenticated GET or POST request. Its value is the name of the user we are supposed to have successfully authenticated, using the scheme held in AUTH_TYPE. 🔐

REQUEST_METHOD

Read-only variable, whose value is either GET or POST. 💅

SCRIPT_FILENAME

Read-only variable set to the filesystem path of the CGI script being run. 🛠️

SCRIPT_NAME

Read-only variable set to the virtual path of the CGI script being run, i.e. the path given in the requested URL. 🌸

SERVER_NAME

The host name running the server, which defaults to the host name present in the base URL, provided at creation time as the -base_url argument. 🌐

SERVER_PORT

The port where the server listens, which defaults to the port present in the base URL, provided at creation time as the -base_url argument. If no port was explicitly given, 80 is assumed. 🔥

SERVER_PROTOCOL

The protocol which must be followed when replying to the client request. Set to HTTP/1.1 by default. ✨

SERVER_SOFTWARE

The name of the server software. Defaults to CGI::Test. 💻

🐛 BUGS 🐛

There are some, most probably. Please notify me about them. 😭

The following limitations (in decreasing amount of importance) are known and may be lifted one day -- patches welcome:

• There is no support for cookies. A CGI installing cookies and expecting them to be resent on further invocations to friendly scripts is bound to disappointment. 🍪
• There is no support for plain document retrieval: only CGI scripts can be fetched by an HTTP request for now. 📄

🌐 PUBLIC REPOSITORY 🌐

CGI::Test now has a publicly accessible Git server provided by Github.com: <http://github.com/nohuhu/CGI-Test> 🫶

📣 REPORTING BUGS 📣

Please use Github issue tracker to open bug reports and maintenance requests. 🐞

👑 AUTHORS 👑

The original author is Raphael Manfredi.

Steven Hilton was long time maintainer of this module.

Current maintainer is Alex Tokarev <tokarev@cpan.org>. 💖

📜 LICENSE 📜

This program is free software; you can redistribute it and/or modify it under the terms of the Artistic License, a copy of which can be found with Perl 5.6.0.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the Artistic License for more details.

🔗 SEE ALSO 🔗

• CGI(3)
• CGI::Test::Page(3)
• CGI::Test::Form(3)
• CGI::Test::Input(3)
• CGI::Test::Form::Widget(3)
• HTTP::Status(3)
• URI(3)

---

okay bestie that's the whole page!! this was CGI::Test(3pm), from perl v5.34.0, dated 2022-06-10. go slay 💅✨