Test::Class::Moose::Runner(3)

NAME
Test::Class::Moose::Runner - Runner for Test::Class::Moose tests

VERSION
version 0.69

SYNOPSIS
 use Test::Class::Moose::Load 't/lib';
 use Test::Class::Moose::Runner;
 Test::Class::Moose::Runner->new->runtests;

DESCRIPTION
This class is responsible for running tests. Internally, most of the work is done by either a "Test::Class::Moose::Executor::Sequential" or "Test::Class::Moose::Executor::Parallel" object.

LOADING TESTS
We strongly recommend using the Test::Class::Moose::Load driver for your test suite. Simply point it at the directory or directories containing your test classes:

 use Test::Class::Moose::Load 't/lib';
 use Test::Class::Moose::Runner;
 Test::Class::Moose::Runner->new->runtests;

By running your "Test::Class::Moose" tests with a single driver script like this, all classes are loaded once and this can be a significant performance boost. This does mean a global state will be shared, so keep this in mind.

CONSTRUCTOR ATTRIBUTES

•   "show_timing"

    Boolean. Will display verbose information on the amount of time it takes each test class/test method to run. Defaults to false, but see "use_environment".

•   "statistics"

    Boolean. Will display number of classes, test methods and tests run. Defaults to false, but see "use_environment".

•   "use_environment"

    If this is true, then the default value for show_timing and statistics will be true if the "HARNESS_IS_VERBOSE" environment variable is true. This is set when running "prove -v ...", for example.

•   "jobs"

    This defaults to 1. If you set this to a larger number than test instances will be run in parallel. See the "PARALLEL RUNNING" section below for more details.

•   "randomize"

    Boolean. Will run test methods in a random order.

•   "randomize_classes"

    Boolean. Will run test classes in a random order. Note that if you specify an explicit list of classes in "test_classes", these classes will be run in the order you specify.

•   "builder"

    Defaults to "Test::Builder->new". You can supply your own builder if you want, but it must conform to the Test::Builder interface. We make no guarantees about which part of the interface it needs.

•   "test_classes"

    Takes a class name or an array reference of class names. If it is present, only these test classes will be run. This is very useful if you wish to run an individual class as a test:

        My::Base::Class->new(
            test_classes => $ENV{TEST_CLASS}, # ignored if undef
        )->runtests;

    You can also achieve this effect by writing a subclass and overriding the "test_classes" method, but this makes it trivial to do this:

        TEST_CLASS=TestsFor::Our::Company::Invoice prove -lv t/test_classes.t

    Alternatively:

        My::Base::Class->new(
            test_classes => \@ARGV, # ignored if empty
        )->runtests;

    That lets you use the arisdottle to provide arguments to your test driver script:

        prove -lv t/test_classes.t :: TestsFor::Our::Company::Invoice TestsFor::Something::Else

•   "include"

    Regex. If present, only test methods whose name matches "include" will be included. However, they must still start with "test_".

    For example:

     my $test_suite = Test::Class::Moose->new({
         include => qr/customer/,
     });

    The above constructor will let you match test methods named "test_customer" and "test_customer_account", but will not suddenly match a method named "default_customer".

    By enforcing the leading "test_" behavior, we don't surprise developers who are trying to figure out why "default_customer" is being run as a test. This means an "include" such as "/^customer.*/" will never run any tests.

•   "exclude"

    Regex. If present, only test methods whose names don't match "exclude" will be included. However, they must still start with "test_". See "include".

•   "include_tags"

    Array ref of strings matching method tags (a single string is also ok). If present, only test methods whose tags match "include_tags" or whose tags don't match "exclude_tags" will be included. However, they must still start with "test_".

    For example:

     my $test_suite = Test::Class::Moose->new({
         include_tags => [qw/api database/],
     });

    The above constructor will only run tests tagged with "api" or "database".

•   "exclude_tags"

    The same as "include_tags", but will exclude the tests rather than include them. For example, if your network is down:

     my $test_suite = Test::Class::Moose->new({
         exclude_tags => [ 'network' ],
     });

     # or
     my $test_suite = Test::Class::Moose->new({
         exclude_tags => 'network',
     });

METHODS
In addition to the "new" method, this class provides several additional public methods

  "$runner->runtests"
This method runs your tests. It accepts no arguments.

  "$runner->test_configuration"
This returns a Test::Class::Moose::Config for the runner.

Most of the attributes passed to the runner are actually available in a Test::Class::Moose::Config rather than the runner itself. This may change in a future release, in which case this method will simply return the runner itself for backwards compatibility.

PARALLEL RUNNING
Running tests in parallel requires you to have Parallel::ForkManager installed. This is not a prereq of this distro so you will need to install manually.

To run tests in parallel, simply pass a value greater than 1 for the "jobs" parameter when creating a runner object:

  Test::Class::Moose::Runner->new( jobs => 4 )->runtests;

Your test classes will be run in parallel in separate child processes. Test classes are parallelized on a per instance basis. This means that each child process constructs a single instance of a test class and runs all of the methods belonging to that class.

If you are using parameterized test instances (see the Test::Class::Moose docs for details) then the same class may have instances running in different child processes.

If any of the methods in a class are marked with the "noparallel" tag, then that class will be not be run in a child process. All test classes which can't be run in parallel are run sequentially after all parallelizable classes have run.

SUPPORT
bugs may be submitted through <https://github.com/test-class-moose/test-class-moose/issues>.

I am also usually active on IRC as 'drolsky' on "irc://irc.perl.org".

AUTHORS

•   Curtis "Ovid" Poe <ovid@cpan.org>

•   Dave Rolsky <autarch@urth.org>

COPYRIGHT AND LICENCE
This software is copyright (c) 2012 - 2016 by Curtis "Ovid" Poe.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.