NAME

Log::Shiras::Test2 - Test2 for traffic in the ::Switchboard

SYNOPSIS

	use Test2::Bundle::Extended qw( !meta );
	use Test2::Plugin::UTF8;
	use Test::Log::Shiras;
	plan( 3 );
	
	~~ Set up the Log::Shiras::Switchboard operator here ($ella_peterson) ~~
	
	my $test_class;
	ok( lives{	$test_class = Log::Shiras::Test2->new },
											"Build a test class for reading messages from the bat phone" ) or note($@);;
	ok( lives{
				$ella_peterson->master_talk({ # Use Ella Petersons bat phone
					name_space => 'main', report => 'report1', level => 'eleven', 
					message =>[ 'Hello World' ], });
	},										"Test making a call (with Ella Petersons bat phone)" ) or note($@);
	$test_class->match_message( 'report1', "Hello World",
											"... and check the output" );

DESCRIPTION

This is a class used for testing. It inherits directly from Test2::API without going through Test::Builder. This will feed back to any Test2 rooted test with the understanding that even Test::More now uses Test2 Under the hood. The tests are object oriented methods rather than functions. That was a conscious choice in order to auto link to the singleton once without re-connecting over and over. The goal is to be able to set up messages to the switchboard with minimum wiring to the reports and still be able to see if the messages are working as expected. Log::Shiras::Switchboard will actually check if this module is active and store messages to a test buffer right before sending them to the reports. This allows the reports to exist in name only and to still test permissions levels and caller actions without using Capture::Tiny or reading output files for test results.

Attributes

These are things that can be passed to the ->new argument in order to change the general behavior of the test instance.

keep_matches

Description: This determines whether a match is deleted from the test buffer when it is matched by the test match_message.

Range: accepts a boolean value

Default: 1 = yes, matches are deleted when found

attribute methods:

set_match_retention( $bool )

Description: Changes the keep_matches attribute setting to the passed $bool

test_buffer_size

Description: This attribute attempts to mirror $Test::Log::Shiras::last_buffer_position . If you set it upon instantiation of an instance of this class then it will change the global variable too.

Range: accepts a positive integer

Default: 11 this starts at eleven

attribute methods:

change_test_buffer_size( $int )

Definition: This will change the maximum test buffer size. If the target buffer size is reduced greater than the current buffer contents the size will not be resolved until the next message is sent to the buffer.

Methods

These are not tests!

get_buffer( $report )

Definition: This will return the full test buffer for a given report. It should be noted that messages are stored with metadata. Active buffers are not an ArrayRef of strings.

Accepts: The target $report name

Returns: An ArrayRef of HashRefs

Tests

All tests here are written as methods on an object not exportable functions. As such they are implemented in the following fashion.

my $tester = Test::Log::Shiras->new;
$tester->match_message( $report, $wanted, $message );

clear_buffer( $report, $message )

Definition: This test will clear the buffer. It always passes.

Accepts: The target $report name string to clear and the $message to append to the test report.

Returns: The cleared test name_space

has_buffer( $report, $expected, $message )

Definition: This test checks to see if there is a test buffer for the $report name. It allows for testing a buffer existence whether the buffer is $expected to exist or not.

Accepts: The target $report name string to check and whether you $expected to find the buffer or not. It also accepts the $message used for test result reporting.

Returns: The tested report buffer name

buffer_count( $report, $expected, $message )

Definition: This test checks a known buffer to see how many records it contains. It will compare that to how many records are $expected. The buffer count will mostly never exceed the mandated max buffer size.

Accepts: The target $report name string to check and how many records were $expected in the buffer. It also accepts the $message used for test result reporting.

Returns: The tested report buffer name

match_message( $report, $test_line, $message )

Definition: This test checks if a $test_line exists in any of the message elements in the test buffer. The message elements take the following relevant format.

$message->{message} =>[ $compare_line1, $compare_line2, etc. ]

$compare_line1 and $compare_line2 are the elements tested. If $test_line is a RegexpRef then it will do a regex compare otherwise it does an exact string 'eq' compare. If there is a match the test will splice out the message from the buffer so It won't show up again unless you re-send it to the buffer. This behavior can be changed with the attribute keep_matches.

Accepts: The target $report name string a $test_line [or regex] to check with. It also accepts the $message used for test result reporting.

Returns: The tested report buffer name

cant_match_message( $report, $test_line, $message )

Definition: This test checks all messages in a buffer to see if a $test_line exists in any of the message elements. The message elements take the following relevant format.

$message->{message} =>[ $compare_line1, $compare_line2, etc. ]

$compare_line1 and $compare_line2 are the elements tested. If $test_line is a RegexpRef then it will do a regex compare otherwise it does an exact string 'eq' compare. Even if there is a match the buffer remains un-edited but the test fails.

Accepts: The target $report name string a $test_line [or regex] to check with. It also accepts the $message used for test result reporting.

Returns: The tested report buffer name

GLOBAL VARIABLES

$Test::Log::Shiras::last_buffer_position

In order to not have memory issues with long running tests that accumulate buffers without flushing there is a global variable for the max items in the test buffer. The actual test buffer is not stored here but rather in the Switchboard in order to leverage the Singleton there. The default value is 11 (Store to 11). So if you want to do a lot of work and then check if a message was processed early on then you need to increase this value (equivalent to max buffer size). Internal to the instance it is best to change the max buffer using the attribute test_buffer_size and it's method.