CGI::Test::Form(3pm)

💖 CGI::Test::Form — the manual page, bestie edition 💖

Okay so this is CGI::Test::Form, from the User Contributed Perl Documentation, section 3pm. It's the girlypop who lets you talk to the widgets inside a CGI form. Let's get into it. 🎀

---

✨ NAME ✨

CGI::Test::Form — Querying interface to CGI form widgets 💅

---

🌸 SYNOPSIS 🌸

my $form = $page->forms->[0];       # first form in CGI::Test::Page

#
# Querying interface, to access form widgets
#

my @buttons = $form->button_list;   # ->buttons would give list ref
my $radio_listref = $form->radios;  # ->radios_list would give list

my $passwd_widget = $form->input_by_name("password");
my ($login, $passwd) = $form->input_by_name(qw(login password));

my @menus = $form->widgets_matching(sub { $_[0]->is_menu });
my @menus = $form->menu_list;       # same as line above

my $rg = $form->radio_groups;       # a CGI::Test::Form::Group or undef

#
# <FORM> attributes, as defined by HTML 4.0
#

my $encoding = $form->enctype;
my $action = $form->action;
my $method = $form->method;
my $name = $form->name;
my $accept = $form->accept;
my $accept_charset = $form->accept_charset;

#
# Miscellaneous
#

# Low-level, direct calls normally not needed
$form->reset;
my $new_page = $form->submit;

# Very low-level access
my $html_tree = $form->tree;        # HTML::Element form tree
my $page = $form->page;             # Page containing this form

#
# Garbage collection -- needed to break circular references
#

$form->delete;

---

🦋 DESCRIPTION 🦋

The CGI::Test::Form class is your little bestie for poking at the content of CGI forms. You don't even have to build these yourself — instances get created automatically by CGI::Test when it's out here analyzing the HTML output of a GET/POST request and bumps into one of these creatures. automatic. iconic. no notes. ✨

This class is genuinely the basis of everything CGI::Test can do, like the way it's the whole backbone of the testing abilities: it hands you the routines you need to query the CGI widgets hanging out in the form — buttons, input areas, menus, etc... 💖 You can query them by type, you can query them by name. And there's also a whole interface specifically for getting at the grouped widgets, like checkboxes and radio buttons. 🎀

Every single widget the queries hand back is a polymorphic object, an heir of CGI::Test::Form::Widget. Here's the vibe check: if the querying interface is basically the human eye — letting you spot a particular graphical item on the browser screen — then the widget interface is basically the mouse and keyboard, letting you actually interact with the graphical components you just located. 🖱️✨ If you want the deets on interacting, go see CGI::Test::Form::Widget. Periodt.

Okay and beyond the widget-querying situation, this class also offers a few services to other CGI::Test components — like handling reset and submit actions — which, ngl, you don't really need to use directly in practice. 💅

Finally, it gives you inspection of the <FORM> tag attributes (encoding type, action, etc...) and — if you really need it — access to the HTML tree of all the <FORM> content. 🌈 This interface is based on the HTML::Element class, which represents a tree node. And heads up: the tree is shared with other CGI::Test components, it is not a private copy, bestie. If you're not already familiar with it, go read HTML::Element.

🫶 MEMORY WARNING, this one's important: if memory is a problem, you must be aware that circular references are used almost everywhere within CGI::Test. Because Perl's garbage collector literally cannot reclaim objects that are part of such a reference loop, you have to explicitely call the delete method on CGI::Test::Form. Simply forgetting about the reference to that object is not enough. Don't bother with any of this if your regression test scripts die quickly. 💀

---

more coming in part 2, don't you dare close the tab 🌸

💅 INTERFACE 💅

okay so bestie, this is mostly a querying interface. most routines hand you widget objects back, via lists or list refs. for the tea on what widget objects actually do and how they're classified, go read CGI::Test::Form::Widget. ✨

The order of the widgets in the returned lists? literally the same order they show up in the HTML. no cap. 💖

---

✨ Type Querying Interface ✨

two groups of routines here: one gives you expanded lists, the other gives list references. table time but make it cute.

The Item Polymorphic Type column is about the polymorphic dynamic type of the items inside the list: every item is guaranteed to be at least that type, but it can be a descendant. types are abridged, so you gotta prepend CGI::Test::Form:: to get the real type. 💅

• button_list (expanded) / buttons (list ref) — items are at least Widget::Button
• checkbox_list / checkboxes — items are at least Widget::Box::Check
• hidden_list / hidden — items are at least Widget::Hidden
• input_list / inputs — items are at least Widget::Input
• menu_list / menus — items are at least Widget::Menu
• radio_list / radios — items are at least Widget::Box::Radio
• submit_list / submits — items are at least Widget::Button::Submit
• widget_list / widgets — items are at least Widget

For instance:

my @widgets = @{$form->widgets};     # heavy style
my @widgets = $form->widget_list;    # light style

A given widget can show up in several lists, i.e. the above do not form a partition over the widget set. for example, a submit button would appear in widget_list (which lists all widgets), in button_list, and in submit_list. 🔥

---

🌸 Name Querying Interface 🌸

These routines take a name or a list of names, and return the widgets whose parameter name is exactly the given name (string comparison). You can query all widgets, or a particular class — like all buttons, or all input fields.

Two groups of routines:

• One group allows for multiple name queries, and returns a list of widgets, one entry for each listed name. Some widgets like radio buttons may have multiple instances bearing the same name, and in that case only one is returned. When querying for one name, you're allowed to use scalar context:

my  @hidden   = $form->hidden_by_name("foo", "bar");
my ($context) = $form->hidden_by_name("context");
my  $context  = $form->hidden_by_name("context");

When no widget (of that particular type) bearing the requested name is found, undef is returned for that particular slot, so don't blindly make method calls on each returned value. 😭

We shall call that group of query routines the by-name group.

• The other group allows for a single name query, but returns a list of all the widgets (of some particular type when not querying the whole widget list) bearing that name.

my @hidden = $form->hidden_named("foo");

Don't assume that only radios and checkboxes can have multiple instances bearing the same name. 🙈

We shall call that group of query routines the all-named group.

The available routines are listed below. Note that by-name queries are singular, because there is at most one returned widget per name asked, whereas all-named queries are plural, where possible.

The Item Polymorphic Type column refers to the polymorphic dynamic type of items held within the list: each defined item is guaranteed to at least be of that type, but can be a descendant. Types are listed in the abridged form, and you have to prepend the string CGI::Test::Form:: in front of them to get the real type. 💖

• button_by_name (by-name) / buttons_named (all-named) — items are at least Widget::Button
• checkbox_by_name / checkboxes_named — items are at least Widget::Box::Check
• hidden_by_name / hidden_named — items are at least Widget::Hidden
• input_by_name / inputs_named — items are at least Widget::Input
• menu_by_name / menus_named — items are at least Widget::Menu
• radio_by_name / radios_named — items are at least Widget::Box::Radio
• submit_by_name / submits_named — items are at least Widget::Button::Submit
• widget_by_name / widgets_named — items are at least Widget

---

🦋 Match Querying Interface 🦋

This is a general interface, which invokes a matching callback on each widget of a particular category. The signature of the matching routines is:

my @matching = $form->widgets_matching(sub {code}, $arg);

and the callback is invoked as:

callback($widget, $arg);

A widget is kept if, and only if, the callback returns true. Be sure to write your callback so that it only uses calls that apply to the particular widget. When you know you're matching on menu widgets, you can call menu-specific features, but should you use that same callback for buttons, you would get a runtime error. 💀

Each matching routine returns a list of matching widgets. Using the $arg parameter is optional, and should be avoided unless you have no other choice, so as to be as stateless as possible.

The following routines are available, along with the polymorphic widget type to be expected in the callback. As usual, you must prepend the string CGI::Test::Form:: to get the real type. ✨

• buttons_matching — items are at least Widget::Button
• checkboxes_matching — items are at least Widget::Box::Check
• hidden_matching — items are at least Widget::Hidden
• inputs_matching — items are at least Widget::Input
• menus_matching — items are at least Widget::Menu
• radios_matching — items are at least Widget::Box::Radio
• submits_matching — items are at least Widget::Button::Submit
• widgets_matching — items are at least Widget

For instance:

my @menus = $form->widgets_matching(sub { $_[0]->is_menu });
my @color = $form->widgets_matching(
    sub { $_[0]->is_menu && $_[0]->name eq "color" }
);

is an inefficient way of saying:

my @menus = $form->menu_list;
my @color = $form->menus_matching(sub { $_[0]->name eq "color" });

and the latter can further be rewritten as:

my @color = $form->menus_named("color");

---

👑 Form Interface 👑

This gives you an interface to get at the attributes of the <FORM> tag. For instance:

my $enctype = $form->enctype;

to get at the encoding type of that particular form. The following attributes are available:

accept
accept_charset
action
enctype
method
name

as defined by HTML 4.0. 💅

---

🎀 Group Querying Interface 🎀

There are two kinds of widgets that are architecturally groupped (yes, that's the word, meaning more than one instance of that widget can bear the same name): radio buttons and checkboxes (although you may have a single standalone checkbox).

All radio buttons and checkboxes defined in a form are automatically inserted into a group of their own, which is an instance of the CGI::Test::Form::Group class. This class contains all the defined groups for a particular kind. The routines:

checkbox_groups
radio_groups

give you access to the CGI::Test::Form::Group container. Both routines may return undef when there is no checkbox or radio button in the form. See CGI::Test::Form::Group for its querying interface. 🌈

---

🧚 Memory Cleanup 🧚

You must call the delete method to break the circular references if you wish to dispose of the object. periodt. 💖

---

⭐ Internal Interface ⭐

The following routines are available internally:

• reset — Reset the form state, restoring all the controls to the value they had upon entry.
• submit — Submit the form, returning a CGI::Test::Page reply.

---

💜 AUTHORS 💜

The original author is Raphael Manfredi.

Steven Hilton was long time maintainer of this module.

Current maintainer is Alexander Tokarev <tokarev@cpan.org>.

---

🌟 SEE ALSO 🌟

• CGI::Test(3)
• CGI::Test::Form::Widget(3)
• CGI::Test::Form::Group(3)
• CGI::Test::Page(3)
• HTML::Element(3)

---

okay bestie, that's the whole vibe. this page came from perl v5.34.0, dated 2022-06-10, and it's literally CGI::Test::Form(3pm). go slay some forms 💅✨