NAME

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

VERSION

version 0.67

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.

AUTHORS

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

• Dave Rolsky <autarch@urth.org>

COPYRIGHT AND LICENSE

This software is copyright (c) 2012 - 2015 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.

cpanm Test::Class::Moose

perl -MCPAN -e shell
install Test::Class::Moose