=head1 NAME

Test::Toolbox - tools for testing

=head1 SYNOPSIS

 # load module
 use Test::Toolbox;
 
 # plan tests
 rtplan 43;
 
 # or, plan tests, but die on the first failure
 rtplan 43, autodie=>1;
 
 # basic test
 rtok 'my test name', $success;

 # test for failure if you prefer
 rtok 'test name', $success, should=>0;

 # two values should equal each other
 rtcomp 'test name', $val, $other_val;
 
 # two values should not equal each other
 rtcomp 'test name', $val, $other_val, should=>0;
 
 # run some code which should succeed
 # note that the second param is undef
 rteval 'test name', undef, sub { mysub() };
 
 # run some code which should cause a specific error code
 rteval 'test name', 'file-open-failed', sub { mysub() };
 
 # check that $@ has a specific error code
 rtid 'test name', $@, 'missing-keys';
 
 # much more

=head1 OVERVIEW

Test::Toolbox provides (as you might guess) tools for automated testing.
Test::Toolbox is much like some other testing modules, such as Test::More
and Test::Simple. Test::Toolbox provides a different flavor of tests which
may or may not actually be to your preference.

The tools in Test::Toolbox have a standard format. Commands start with (the
command (of course), followed by the test name. Then there is usually the
value being tested, or values being compared, then other options. So, for
example, this command checks compares two values:

 rtcomp 'test name', $val, $other_val;

In some cases it's preferable to flip the logic of the test, so that, for
example, two values should B<not> be the same. In that case, you can add
the C<should> option:

 rtcomp 'test name', $val, $other_val, should=>0;

All test commands require a test name as the first param.

=head1 Meta commands

=head2 go_script_dir()

C<go_script_dir()> changes to the directory that the script is running in. This
can be handy of your test script needs to read files that are part of your
tests. C<go_script_dir()> takes no params:

 go_script_dir();

=head2 rtplan()

rtplan() indicates how many tests you plan on running. Like with other test
modules, failing to run exactly that many tests is itself considered on error.
So, this command plans on running exactly 43 tests.

 rtplan 43;

You might prefer that your script dies on the first failure. In that case add
the C<autodie> option:

 rtplan 43, autodie=>1;

=head2 rtcounts()

rtcounts() returns a hashref of the test counts so far. The hashref has the
following elements:

=over 4

=item * success: number of successful tests so far.

=item * fail: number of failed tests so far.

=item * sofar: total number of tests so far.

=item * planned: total number of planned tests.

=back

=head1 Test commands

=head2 rtok()

rtok() is the basic command of Test::Toolbox. It requires two params, the name
of the test, and a scalar indicating success (true) or failure (false). So,
this simple command indicates a successful test:

 rtok 'my test', 1;

You might prefer to flip the logic, so that false indicates success. For that,
use the C<should> option:

 rtok 'my test', $val, should=>0;

All other test command call rtok().

=head2 rtcomp()

rtcomp() compares the string value of two values.  It sets success if they are
the same, failure if thet are different. Its simplest use would be like this:

 rtcomp 'my test', $first, $second;

As with other commands, you can flip the logic of the command so that success
is if they are not the same:

 rtcomp 'my test', $first, $second, should=>0;

rtcomp() interprets undef as matching undef, so the following test would would
be successful.

 rtcomp 'my test', undef, undef;

rtcomp() takes several options.

=over 4

=item * collapse

If this option is true, then the strings are collapsed before they are
compared. So, for example, the following test would succeed:

 rtcomp 'my test', ' Fred ', 'Fred', collapse=>1;

=item * nospace

nospace removes all spaces before comparing strings. So this test would
succeed:

 rtcomp 'my test', 'Fr   ed', 'Fred', nospace=>1;

=item * case_insensitive

The case_insensitive option indicates to compare the values case insensitively.
So, the following test would be successful.

=back

=head2 rtelcount

Checks if an array has the correct number of elements.  The first param is an
integer 0 or greater. The second param is an array reference. So, the following
test would pass:

 rtelcount 'my test', 3, \@arr;

=head2 rtarr

rtarr compares two arrays. In its simplest use, the test passes if they are
identical:

 @first = qw{Larry Curly Moe};
 @second = qw{Larry Curly Moe};
 rtarr 'my test', \@first, \@second;

Like with rtcomp, two undefs are considered the same, so the following test
would pass.

 @first = ('Larry', 'Moe', 'Curly', undef);
 @second = ('Larry', 'Moe', 'Curly', undef);
 rtarr 'my test', \@first, \@second;

rtarr takes several options.

=over 4

=item * order_insensitive

If the order_insensitive option is true, then the arrays are considered the
same even if the elements are not in the same order. So the following test
would pass:

 @first = ('Curly', 'Larry', 'Moe');
 @second = ('Larry', 'Moe', 'Curly');
 rtarr 'my test', \@first, \@second, order_insensitive=>1;

=item * case_insensitive

If the case_insensitive option is true, then the elements are compared case
insensitively. So the following test would pass:

 @first = ('CURLY', 'LARRY', undef, 'MOE');
 @second = ('Curly', 'Larry', undef, 'Moe');
 rtarr 'my test', \@first, \@second, case_insensitive=>1;

=back

=head2 rthash

rthash checks is two hashes contain the same keys and values. The following
test would pass. Keep in mind that hashes don't have the concept of order, so
it doesn't matter that the hashes are created with differently ordered keys.

 %first = ( Curly=>'big hair', Moe=>'flat hair', Schemp=>undef);
 %second = ( Moe=>'flat hair', Schemp=>undef, Curly=>'big hair');
 rthash 'my test', \%first, \%second;

rthash doesn't currently have a case_insensitive option. That will probably
be added in future releases.

=head2 rtisa

rtisa tests if a given value is of the given class. For example, the following
test would pass.

 $val = [];
 rtisa 'my test', $val, 'ARRAY';

The second value can be either the name of the class or an example of the
class, so the following test would also pass.

 $val = [];
 rtisa 'my test', $val, [];

If the class is undef or an empty string, then rtisa returns true if the given
object is not a reference.

 $val = 'whatever';
 rtisa 'my test', $val, '';

=head2 rtbool

rtbool checks if two values have the same boolean value, that is, if they are
both true or both false. Booleans are checked in the perlish sense, so the
values don't have to be the same, they just have to have the same perlish
boolean values. Here are some examples.

 rtbool 'my test', 'whatever', 'dude'; # passes
 rtbool 'my test', 'whatever', 1;      # passes
 rtbool 'my test', 'whatever', undef;  # fails
 rtbool 'my test', 0, undef;           # passes

=head2 rtdef

rtdef tests if the given value is defined. The second param is the value being
tested, the third param is if the value should be defined or not. So, the
following tests would pass.

 rtdef 'my test', 'hello', 1;
 rtdef 'my test', undef, 0;

The third param must be defined.

=head2 rtrx

rtrx tests if the given value matches the given regular expression. The
following test would pass.

 rtrx 'my test', 'Fred', 'red';

If you want to get fancy with your regular expressions, use qr// to create the
regexes as you pass them in. The following test is an example.

 rtrx 'my test', 'Fred', qr/RED$/i;

=head2 rtfile

rtfile tests if the given file path exists. In its simplest use, rtfile takes
just the name of the file and the path:

 rtfile 'my test', '/tmp/log.txt';

You can use the C<should> option to test if the file B<doesn't> exist:

 rtfile 'my test', '/tmp/log.txt', should=>0;

=head1 Message ID tests

The following tests checking for errors that begin with an error code, followed
by a colon, followed by plain language. For example:

 croak 'error-opening-log-file: error opening log file';

Note that the error ID must be followed by a colon.

=head2 rtid()

rtid() checks if the given string starts with the given id. For example, to
test is $! starts with the id 'error-opening-log-file' you would use this command:

 rtid 'my test', $!, 'error-opening-log-file';

=head2 rteval()

rteval() allows you to test some code then check for an error id, all in one
easy command. rteval runs the given subroutine in an eval{} block, then tests
Here's an (admittedly contrived) example:

 rteval
   'my test',
   sub { die 'error-opening-log-file: whatever' },
   'error-opening-log-file';

If your subroutine is really long, you might prefer to put the id as the first
param, then the sub.  rteval() provides some forgivness in that regard: if the
second param is a sub, then the first param is assumed to be the id. So the
following example works the same as the above example:

 rteval
   'my test',
   'error-opening-log-file',
   sub { die 'error-opening-log-file: whatever' };

If the sub is supposed to work, you can put undef for the expected code:

 rteval
   'my test',
   sub { my $val = 1 },
   undef;

=head1 TERMS AND CONDITIONS

Copyright (c) 2016 by Miko O'Sullivan. All rights reserved. This program is
free software; you can redistribute it and/or modify it under the same terms as
Perl itself. This software comes with NO WARRANTY of any kind.

=head1 AUTHOR

Miko O'Sullivan
F<miko@idocs.com>

=head1 VERSION

Version: 0.04

=head1 HISTORY

=over 4

=item * Version 0.01 Aug 21, 2016

Initial release.

=item * Version 0.02 Aug 23, 2016

Fixed dependency problem. Should not have been using String::Util.

=item * Version 0.03 Aug 25, 2016

Added private sub collapse() which should have been in there all along.

=item * Version 0.04 Aug 26, 2016

Added private subs define(), rtrim(), ltrim() which should have been there
all along.

Added rtdiag().  Not sure how to test rtdiag(), so for now no tests for that.

May have fixed test for rtfile().

=back