NAME

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

VERSION

version 0.99

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.

• set_process_name

  Boolean. If this is true, then $0 will be updated to include the test instance name for each test instance as it is run, and then further updated as each test control method and test method are run, This can be helpful when debugging hanging tests. Defaults to false.

• 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.

• show_parallel_progress

  This defaults to 1. This only impacts the output when running tests in parallel. If this is true then when running tests in parallel the runner will output one dot per class being executed. This makes it clear that the test suite is not stuck.

  However, this output can cause issues with things like the TAP::Harness::Archive module, so you can disable it if needed.

• color_output

  This defaults to 1. This only impacts the output when running tests in parallel. If this is true then parallel test progress output will use ANSI coloring to indicate each class's pass/fail status.

• 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.

• 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',
   });

• executor_roles

  An array reference containing one or more roles to be applied to the executor object. This allows you to apply plugins on top of the normal TCM behavior.

  See the Test::Class::Moose::Role::Executor docs for details of what methods you can modify as part of such roles.

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.

$runner->test_report

This returns a Test::Class::Moose::Report for the runner. After running tests you can use this object to get information about the test run.

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 at https://github.com/houseabsolute/test-class-moose/issues.

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

SOURCE

The source code repository for Test-Class-Moose can be found at https://github.com/houseabsolute/test-class-moose.

AUTHORS

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

• Dave Rolsky <autarch@urth.org>

COPYRIGHT AND LICENSE

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

The full text of the license can be found in the LICENSE file included with this distribution.

cpanm Test::Class::Moose

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