/ 
Agent-TCLI-0.032
River stage one • 1 direct dependent • 1 total dependent
/ Agent::TCLI::Transport::Test

NAME

Agent::TCLI::Transport::Test - transport for testing commands

SYNOPSIS

use Test::More qw(no_plan);
ues Agent::TCLI::Transport::Test;
use Agent::TCLI::Package::Tail;

# set the list of packages
my @packages = (
	Agent::TCLI::Package::Tail->new({
		'verbose'		=> \$verbose,
		'do_verbose'	=> sub { diag( @_ ) },
	}),
);


my $test_master = Agent::TCLI::Transport::Test->new({
    'verbose'   	=> \$verbose,        # Verbose sets level

    # change verbose output to Test::More::diag
	'do_verbose'	=> sub { diag( @_ ) },

	# load up the packages to support testing
    'control_options'	=> {
	    'packages' 		=> \@packages,
    },
});

# need at least one testee

# Set up the local test
my $target = Agent::TCLI::Testee->new(
	'test_master'	=> $test_master,
	'addressee'		=> 'self',
);

DESCRIPTION

The Agent::TCLI::Transport::Test module is a bridge between the rest of the TCLI system and Perl's TAP based testing system. This module uses Test::Builder underneath and should be compatible with all other Test modules that use Test::Builder.

The one cautionary note is that Agent::TCLI::Transport::Test runs on top of POE which is an asynchronous, event based system. Typically, tests will not complete in the order that they are written. There are various means to establish control over the completion of prior tests which should be sufficient for most cases. However, one should not write a test script without some thought to the ordering needs of the tests and whether extra tests need to be in place to ensure those needs are met.

GETTING STARTED

If you are unfamiliar with Perl's Test:: modules, then please see Test::Tutorial for background information.

One may look at some of the test scripts with the TCLI source for examples, but they are limited to a single agent. The TCLI core does not come with modules that are useful for multi-agent test scripts. This is to reduce the dependencies for the Core. Please see example scripts provided with other TCLI packages for better multi agent examples.

Currently, Agent::TCLI::Transport::Test offers only an object interface, so we're using Test::More to set the plan and import diag() into the test script. This might change at some point, but this kludge will always work.

As in the Synopsis, one will most often want to define the necesary packages outside of the transport(s) used. Typically one will want the same packages loaded in all the transports. By same, we mean the same package object instantiations.

One then needs to create the Agent::TCLI::Transport::Test object. The Synoposis covers the typical parameters set on creation. All of the Agent::TCLI::Transport::Test class mutator methods are available within new, but generally should not be used. There may be other inherited mutator methods from Agent::TCLI::Transport::Base that could be useful.

Unlike other Transports, users do not have to be defined for Transport::Test, as it will load a default user. Local tests are executed with a Control created for the first user in the stack. Currently, running with users other than the default has not been tested.

Then one needs to create at least one Agent::TCLI::Testee. The testee object will be used for the actual tests. See Agent::TCLI::Testee for the tests available.

Within the actual tests, the Agent::TCLI::Transport::Test (as test_master) offers two flow/control commands. run is necesary at the end of the tests to start POE completely and finish the tests. done may be used within the script to force check for completion of all prior tests. done is a test itself and will report a success or failure.

ATTRIBUTES

Unless otherwise indicated, these attrbiute methods are for internal use. They are not yet restricted because the author does not beleive his imagination is better than the rest of collective world's. If there are use cases for accessing the internals, please make the author aware. In the future, they may be restricted to reduce the need for error checking and for security.

testees

An array of the testees that the test transport will be working with.

requests

An internal array acting as a queue of the requests to send. Requests are not retained in the queue, but are only held until dispatched.

test_count

A running count of all the tests. Some requests may contain multiple tests. test_count will only contain numeric values.

request_count

A counter for making request ids request_count will only contain numeric values.

default_request

Normally a Agent::TCLI::Request object must be created for each test. This is the default Request to use in making requests for each test. This may be set by the user if the default is not approprate. default_request will only accept Agent::TCLI::Request type values.

requests_sent

Number of requests sent out. requests_sent will only accept Numeric type values.

requests_complete

Number of requests_completed requests_complete will only accept Numeric type values.

request_tests

A hash keyed by request ID of arrays of tests to perform on the responses request_tests will only contain hash values.

responses

A hash keyed on request_id to hold responses when multiple responses per request are expected. responses will only contain hash values.

responses_max_contiguous

This field hold a numeric value corellating to the response ID of the maximum response received that had at least one response received for all previous requests. responses_max contiguous will only contain numeric values.

dispatch_counter

A running counter of Dispatch attempts to prevent stalling. dispatch_counter will only contain numeric values.

dispatch_retries

The number of times to retry the dispatching of queued requests. Increments are in 5 second blocks. Default is 6 or 30 seconds. This is a user adjustable setting. When the count is reached, the next test is dispatched without regard to the state of the previous test. The timeout will not start until dispatching is done or exceeded its retries. This allows for other requests to complete. dispatch_retries will only contain numeric values.

timeout_counter

A running counter for timing out all requests. timeout_counter will only contain numeric values.

timeout_retries

The number of times to retry the timeout. Increments are in 5 second blocks. Default is 6 or 30 seconds. Timeout checks periodically to make sure we're still running requests. It begins the countdown when all requests have been dispatched, so that we don't wait forever for something to complete. This is user adjustable. timeout_retries will only contain numeric values.

timeout_id

The id of the timeout event so that it can be rescheduled if necessary.

running

A flag to indicate if we've started the POE kernel fully, rather than just running slices. This is set when run is called. running should only contain boolean values.

last_testee

Internally used when building a new test to check what the last testee was. last_testee will only contain scalar values.

dispatch_id

Holds the POE event ID for the Dispatch so it can be rescheduled. dispatch_id should only contain scalar values.

METHODS

Most of these methods are for internal use within the TCLI system and may be of interest only to developers trying to enhance TCLI.

The first three are the exception.

done( <timeout>, <name> )

When done is called, it will attempt to complete all previous requests before continuing. If done is provided a name parameter, it will report its results as a test. That is, it will pass if all previous tests are completed before the timeout. In either case, it will return true if all tests are complete and false otherwise.

It takes an optional timeout parameter, an integer in seconds. The default timeout is 31 seconds if none is supplied.

It takes an option parameter of a test name.

done_id(<id>, <timeout>, <name> )

done_id works similarly to done except that it waits only for the results from one request, as specified by the id. If a request id is not supplied, it will default to the last request made.

It takes an optional timeout parameter, an integer in seconds. The default timeout is 31 seconds if none is supplied.

It takes an option parameter of a test name.

load_testee ( <testee> )

The preferred way to load a testee is to set 'test_master' when the testee is created. Testee will then call this function on initializtion. A testee is an Agent::TCLI::Testee object.

run

run is called at the end of the test script. It will call POE::Kernel->run to finish off all of the requests. Other POE event handlers will ensure that all queued requests are dispatched and all requests dispatched are completed.

Running does not take any parameters and does not return anything.

preinit

This private Object::InsideOut (OIO) method is used for object initialization.

_init

This private OIO method is used for object initialization.

build_test

This object method is used to build the test, as a Agent::TCLI::Request, and put it on the queue. It is called by the Testee. Some of this functionality may be pushed to the Testee soon, so expect this API to change.

dispatch

This internal object method is used to dispatch requests and run POE timeslices during the test script. An understanding of POE may be necessary to grok the need for this function.

do_test

This is an internal method to process responses. do_test actually executes the test and send the output to the TAP processor. It takes an ARRAYREF for the test and the Agent::TCLI::Response to be checked as parameters.

get_param ( <param>, [ <id>, <timeout> ] )

get_param is an internal method that supports the Testee get_param command. It requires a param argument that is the parameter to try and obtain a value for. It takes an optional request id from a prior request. If not supplied, it will use the last request made. It also takes an optional timeout value, which will be passed to done_id to wait for all responses to that request to come in.

get_param attempts to parse the text in the responses to find the value for the parameter being requested. It expects that the response is formatted appropriately to extract the parameter. Valid formats to receive the parameter are: param=something param something param="a quoted string with something" param "a quoted string with something" param: a string yaml-ish style, no comments, to the end of the line param: "a quoted string, just what's in quotes" It returns the value of the parameter requested, or undefined if it cannot be found.

get_responses ( [ <id>, <timeout> ] )

get_responses is an internal method that supports the Testee get_responses command. It takes an optional request id from a prior request. If not supplied, it will use the last request made. It also takes an optional timeout value, which will be passed to done to wait for all responses to come in. It returns the text from all available responses, separated by a pair of newlines.

make_id

make_id is used to create a request ID for new requests. It is a separate method to ease mainenance in case it needs to change in the future. It takes an optional integer as a parameter, or will default to the current request_count.

post_it

This internal method controls whether to dispatch the next test. It supports different styles of running tests, though currently the style is not user configurable and manipulation of the style is not tested.

For future reference and to encourage assistance in creating a user interface to style, they are:

default or syncsend - This allows a test to be dispacthed when the acknoledgement is received that the previous test has been received OK. This does not wait for the previous test to complete.

syncresp or done - This will not dispatch any test until the previous test has completed. There are many testing scenarios where this makes no sense. There may be scenarios where it does make sense, and htat is why it is here. A similar effect can be had with the done test.

asynch - This dispatches a test as soon as it is ready to go. Sometimes this may allow a local test to complete before a prior remote test has been acknowledged, so it is not the default.

responses_contiguous ( )

Sets responses_max_contiguous correctly by starting at the last value and incrementing until a response has not been recived. Return responses_max_contiguous.

Dispatch

This POE event handler takes care of dispatching once POE is running fully. It maintains a counter to ensure that the test queue does not become stuck. If the counter is exceeded (the queue is stuck), it will send a test without regard to the response from post_it.

PostRequest

PostReuqest is a required POE event handler for all Transports. Well, all transports except this one. It currently does nothing.

PostResponse

PostResponse is a required POE event handler for all Transports. It takes a TCLI Response as an argument. Typically it is called by another Transport to deliver the Response.

It will queue the Reponses in an array in the responses hash keyed by response->id. It will call do_test to complete the tests as appropriate.

SendChangeContext

SendChangeContext is a POE event handler required for all Transports. Well, all other Transports, as this one still thinks it is special enough not to need to do anything here.

SendRequest

SendRequest is a POE event handler that is required for all Transports. It takes a Agent::TCLI::Request as an argument

Timeout

Timeout is a POE event handler that makes sure that a test script completes and no requests leave the system waiting too long for a response. It takes an argument of the delay, in seconds, that it will wait until checking again.

GetControl ( id )

Inherited from Agent::TCLI::Trasnport::Base

_shutdown

Shutdown begins the shutdown of all child processes.

_stop

This POE event handler is called when POE stops a Transport.

AUTHOR

Eric Hacker hacker can be emailed at cpan.org

BUGS

There is no separation between users running tests, which means it could be very ugly to have multiple users try to run tests on one TCLI Agent.

Test scripts not thorough enough.

Probably many others.

LICENSE

Copyright (c) 2007, Alcatel Lucent, All rights resevred.

This package is free software; you may redistribute it and/or modify it under the same terms as Perl itself.