process results from the CPAN

Agent-TCLI
	$eliza->is_body( 'eliza','Context now: eliza', 'Start up eliza');
	$eliza->like_body( 'hello', qr(problem), 'eliza chat begins');
	$eliza->is_code( 'You are not really a therapist.',200, 'chat');
	$eliza->is_code( 'Do you have malpractice insurance?',200, 'chat');
	$eliza->like_body( '/exit',qr(Context now: ), "Exit ok");

=head1 DESCRIPTION

The Testee is the critical interface for writing test scripts in the TCLI
system. It allows one to write tests in the standard Test::Tutorial way
that makes a request of a TCLI agent (the testee) and expects a response. The tests
are coordinated by a test master who interfaces with other transports
to deliver the commands to one or more testee agents.

=head1 WRITING TESTS

Each test is written following the same basic pattern and is a method call
on a testee object. The see below for the test typess currently available.

There are currently two things in the response that can be tested, the B<body>
and the B<code>. The body is the textual response that a human receives from
the agent. The code is a HTTP::Status value that indicates the success or
failure of the request. Often is is simpler to test for a response code equal to
200 (OK) than to write a regex. Though sometimes a regex is required to know
that the response was actually what was desired.

The parameters for mosts tests are:

=over 4

=item * request - the text command to send to the testee

=item * expected - the response desired

=item * name - a name to identify the test in the output

=back

Thus the complete test looks like:

	$testee->is_code("status", 200,"status ok");

The ok and not_ok tests check if the response code falls within a range of
values indicating success or failure, repsectively. One does not need to supply
an expected response code value with these tests.

	$testee->ok("status","status ok");

There are times when a single request may elicit multiple responses. One can use
a blank request to add tests for additional responses to the prior request. One cannot
test both the code and the body on the same response. One can test the code of
the first response and the body of the second. All additional tests must
immediately follow the original populated request.

A request is not actually sent until a new request is made or a test_master
command like run or done is called.

When there are multiple responses per request, the tests will be executed
on the responses in the order that they are written in the script. However, the
test script is usually running asnchronously, and other responses to later
requests may be processed before all responses to earlier requests have arrived.

Currently each test requires a response. There is no mechanism that allows one
to write a test that pass if three to five responses with code 200 are
revceived. That is a desired future feature.

=head3 Greedy Tests

B<is_*> and B<like_*> tests are greedy by default. That is they use up and expect
a response for every test. Other tests (not yet available), such as
B<response_time> (coming soon) are not greedy and act on the next response
received while still allowing other tests to execute on the same response. It
might be useful to have no greedy versions of B<is_*> and B<like_*> but the
exact syntax to do so has not been worked out yet.

=head3 Response Codes

The response codes that come back in a response are modeled after HTTP Status
codes. For most cases, the ok / is_success and not_ok / is_error codes will
suffice for testing.

There are some existing packages, most notably
Agent::TCLI::Package::Tail, which have commands that may take a while to return
results after the command is accepted. These packages will return a 100
(Continue, or in SIP, Trying) to indicate that the request was received and
acted upon, but the result is not yet determined. One may explictly test for
a 100 response, but if one does not, it is silently ignored.

TCLI response codes will maintain compatibility
with HTTP::Status codes for the forseeable future. One may use HTTP::Status to
import its constants to provide clarity in test scripts, but that will not be
automatically done by Testee.

=head3 Request Id

Each request and the corresponding responses are tagged with an id that is
unique. Each of the tests below return the id for the request, though normally
one does not need to capture the id. The id is necessary to get parameters
from a response or get the full set of responses.

=head1 INTERFACE

=head2 ATTRIBUTES

These attrbiutes are used to set up the testee with new. Changing them
afterwords is allowed, but unsupported, and may be restricted in the future.

=cut

use warnings;
use strict;

use vars qw($VERSION @EXPORT %EXPORT_TAGS );

use Carp;

use POE;
use Agent::TCLI::User;
require Agent::TCLI::Request;
use Test::Builder::Module;
( run in 1.990 second using v1.01-cache-2.11-cpan-39bf76dae61 )