=for comment Documentation generated by YARD v0.6.0 and yard-pod-plugin v0.1.

=head1 NAME

Test::Mini::Runner - Default Test Runner

=head1 DESCRIPTION

The Test::Mini::Runner is responsible for finding and running the
appropriate tests, setting up output logging, and returning an
appropriate status code.  For those looking to write tests with this
framework, the points of note are as follows:



=over

=item *

Tests are run automatically at process exit.


=item *

All test cases (subclasses of L<<<< S<<<<< Test::Mini::TestCase
>>>>>|Test::Mini::TestCase >>>>) that have been loaded at that time will
be considered.  This includes indirect subclasses.


=item *

Within each test case, all methods defined with a name matching C<<<<
/^test.+/ >>>> will be run.


=over

=item *

Each test will run in its own test case instance.


=back



=over

=item *

Tests will be run in random order.


=back



=over

=item *

#setup will be called before each test is run.


=back



=over

=item *

#teardown will be called after each test is run.


=back



=over

=item *

Inherited tests are B<<<< not >>>> run.


=back



=item *

Tests may be run via C<<<< `prove` >>>>, by loading (via C<<<< use >>>>,
C<<<< do >>>> or C<<<< require >>>>) the files into another script, or
by simply executing a file containing a test case in the Perl
interpreter.


=over

=item *

If you want to use a non-TAP output logger, C<<<< `prove` >>>> is not an
option.


=back



=item *

Options may be passed in either as command line options, or as
environment variables.


=over

=item *

Environment variable names are prefixed with 'TEST_MINI_'.


=back



=over

=item *

Valid options are:


=over

=item *

C<<<< verbose >>>> - Specifies the logger's verbosity.


=back



=over

=item *

C<<<< filter >>>> - Only tests with names matching this pattern should
be run.


=back



=over

=item *

C<<<< logger >>>> - Specifies an alternate output logger class.


=back



=over

=item *

C<<<< seed >>>> - Specifies a random number seed; used to specify
repeatable test orderings.


=back



=back



=back

=head1 METHODS

=head2 Attribute Accessors

=over

=item B<<<< exit_code >>>>

    exit_code($self) 


Exit code, representing the status of the test run.




Returns:

=over

=item *

Exit code, representing the status of the test run.


=back

=item B<<<< filter >>>>

    filter($self) 


Test name filter.




Returns:

=over

=item *

Test name filter.


=back

=item B<<<< logger >>>>

    logger($self) 


Logger instance.




Returns:

=over

=item *

Logger instance.


=back

=item B<<<< seed >>>>

    seed($self) 


Randomness seed.




Returns:

=over

=item *

Randomness seed.


=back

=item B<<<< verbose >>>>

    verbose($self) 


Logger verbosity.




Returns:

=over

=item *

Logger verbosity.


=back

=back

=head2 Test Run Hooks

=over

=item B<<<< run >>>>

    run($self) 


Begins the test run. Loads and instantiates the test output logger, then
dispatches to L<<<< S<<<<< #run_test_suite
>>>>>|Test::Mini::Runner/run_test_suite >>>> (passing the L<<<< S<<<<<
#filter >>>>>|Test::Mini::Runner/filter >>>> and L<<<< S<<<<< #seed
>>>>>|Test::Mini::Runner/seed >>>>, as appropriate).




Returns:

=over

=item *

The result of the L<<<< S<<<<< #run_test_suite
>>>>>|Test::Mini::Runner/run_test_suite >>>> call.


=back

=item B<<<< run_test >>>>

    run_test($self, $tc, $test) # => Integer 


Runs a specific test.



Parameters:

=over

=item *

(I<<<< Class >>>>) B<<<<< C<<<< $tc >>>> >>>>> -- The test case
owning the test method.


=item *

(I<<<< String >>>>) B<<<<< C<<<< $test >>>> >>>>> -- The name of the
test method to be run.


=back


Returns:

=over

=item *

(I<<<< Integer >>>>) -- The number of assertions called by the test.


=back

=item B<<<< run_test_case >>>>

    run_test_case($self, $tc, @tests) 


Runs tests in a test case.



Parameters:

=over

=item *

(I<<<< Class >>>>) B<<<<< C<<<< $tc >>>> >>>>> -- The test case to
run.


=item *

(I<<<< Array<String> >>>>) B<<<<< C<<<< @tests >>>> >>>>> -- A list
of tests to be run.


=back

=item B<<<< run_test_suite >>>>

    run_test_suite($self, %args) 


Runs the test suite. Finds subclasses of L<<<< S<<<<<
Test::Mini::TestCase >>>>>|Test::Mini::TestCase >>>>, and dispatches to
L<<<< S<<<<< #run_test_case >>>>>|Test::Mini::Runner/run_test_case >>>>
with the name of each test case and a list test methods to be run.



Parameters:

=over

=item *

(I<<<< Hash >>>>) B<<<<< C<<<< %args >>>> >>>>> 


=back







Valid Options for C<%args>:

=over

=item *

(I<<<< String >>>>) B<<<<< filter >>>>> -- Test name filter.


=item *

(I<<<< String >>>>) B<<<<< seed >>>>> -- Randomness seed.


=back


Returns:

=over

=item *

The value of L<<<< S<<<<< #exit_code
>>>>>|Test::Mini::Runner/exit_code >>>>.


=back

=back

=head2 Callbacks

=over

=item B<<<< error >>>>

    error($self, $tc, $test, $e) 


Callback for dying tests.



Parameters:

=over

=item *

(I<<<< Class >>>>) B<<<<< C<<<< $tc >>>> >>>>> -- The test case
owning the test method.


=item *

(I<<<< String >>>>) B<<<<< C<<<< $test >>>> >>>>> -- The name of the
test with an error.


=item *

(I<<<< Test::Mini::Exception >>>>) B<<<<< C<<<< $e >>>> >>>>> -- The
exception object.


=back

=item B<<<< fail >>>>

    fail($self, $tc, $test, $e) 


Callback for failing tests.



Parameters:

=over

=item *

(I<<<< Class >>>>) B<<<<< C<<<< $tc >>>> >>>>> -- The test case
owning the test method.


=item *

(I<<<< String >>>>) B<<<<< C<<<< $test >>>> >>>>> -- The name of the
failed test.


=item *

(I<<<< Test::Mini::Exception::Assert >>>>) B<<<<< C<<<< $e >>>>
>>>>> -- The exception object.


=back

=item B<<<< pass >>>>

    pass($self, $tc, $test) 


Callback for passing tests.



Parameters:

=over

=item *

(I<<<< Class >>>>) B<<<<< C<<<< $tc >>>> >>>>> -- The test case
owning the test method.


=item *

(I<<<< String >>>>) B<<<<< C<<<< $test >>>> >>>>> -- The name of the
passing test.


=back

=item B<<<< skip >>>>

    skip($self, $tc, $test, $e) 


Callback for skipped tests.



Parameters:

=over

=item *

(I<<<< Class >>>>) B<<<<< C<<<< $tc >>>> >>>>> -- The test case
owning the test method.


=item *

(I<<<< String >>>>) B<<<<< C<<<< $test >>>> >>>>> -- The name of the
skipped test.


=item *

(I<<<< Test::Mini::Exception::Skip >>>>) B<<<<< C<<<< $e >>>> >>>>>
-- The exception object.


=back

=back

=head2 Class Methods

=over

=item B<<<< new >>>>

    new($class, %args) 


Constructor. Arguments may be provided explicitly to the constructor or
implicitly via either @ARGV (parsed by L<<<< S<<<<< Getopt::Long
>>>>>|Getopt::Long >>>>) or environment variables ("TEST_MINI_$option").



Parameters:

=over

=item *

(I<<<< Hash >>>>) B<<<<< C<<<< %args >>>> >>>>> -- Initial state for
the new instance.


=back







Valid Options for C<%args>:

=over

=item *

B<<<<< verbose >>>>> -- Logger verbosity.  Defaults to C<<<<< 0
>>>>>.


=item *

(I<<<< String >>>>) B<<<<< filter >>>>> -- Test name filter. 
Defaults to C<<<<< '' >>>>>.


=item *

(I<<<< Class >>>>) B<<<<< logger >>>>> -- Logger class name. 
Defaults to C<<<<< Test::Mini::Logger::TAP >>>>>.


=item *

(I<<<< Integer >>>>) B<<<<< seed >>>>> -- Randomness seed.  Defaults
to a random number C<<<< < 64_000_000 >>>>
.


=back

=back

