The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.

NAME

Test::Nightly - Run all your tests and produce a report on the results.

DESCRIPTION

The idea behind this module is to have one script, most probably a cron job, to run all your tests once a night (or once a week). This module will then produce a report on the whether those tests passed or failed. From this report you can see at a glance what tests are failing. This is alpha software! Please try it out, email me bugs suggestions etc.

SYNOPSIS

 # SCENARIO ONE #

  Pass in all the options direct into the constructor.

  use Test::Nightly;

  my $nightly = Test::Nightly->new({
    base_directories => ['/base/dir/from/which/to/search/for/modules/'],
    run_tests     => {},
    generate_report => {
        email_report => {
            to      => 'kirstinbettiol@gmail.com',
        },
        report_output => '/report/output/dir/test_report.html',
    },
    debug           => 1,
  });

 # SCENARIO TWO #

  Call each method individually.

  use Test::Nightly;

  my $nightly = Test::Nightly->new({
    base_directories => ['/base/dir/from/which/to/search/for/modules/'],
  });

  $nightly->run_tests();

  $nightly->generate_report({
    email_report => {
          to      => 'kirstinbettiol@gmail.com',
    },
    report_output => '/report/output/dir/test_report.html',
  });

  # SCENARIO THREE

  Use build instead of make.

  use Test::Nightly;

  my $nightly = Test::Nightly->new({
    base_directories   => ['/base/dir/from/which/to/search/for/modules/'],
    build_script       => 'Build.PL',
    run_tests          => {
      build_type  => 'build',
    },
  });

new()

  my $nightly = Test::Nightly->new({
    base_directories => \@directories,           # Required. Array of base directories to search in.
    build_script     => 'Build.PL',              # Defaults to 'Makefile.PL'.
    run_tests        => {
          test_directory_format => ['t/', 'tests/'], # Optional, defaults to 't/'.
          test_file_format      => ['.t', '.pl'],    # Optional, defaults to '.t'.
      build_type            => 'make',           # || 'build'. Defaults to 'make'.
      install_module        => 'all',            # || 'passed'. 'all' is default.
      skip_tests            => 1,                # skips the tests.
      test_order            => 'ordered',        # || 'random'. 'ordered' is default.
    },
    generate_report => {
          email_report    => \%email_config,                # Emails the report. See L<Test::Nightly::Email> for config.
          report_template => '/dir/somewhere/template.txt', # Defaults to internal template.
          report_output   => '/dir/somewhere/output.txt',   # File to output the report to.
          test_report     => 'all',                         # 'failed' || 'passed'. Defaults to all.
    },
  });

This is the constructor used to create the main object.

Does a search for all modules on your system, matching the build script description (build_script). You can choose to run all your tests and generate your report directly from this module, by supplying run_tests and generate_report. Or you can simply supply base_directories and it call the other methods separately.

run_tests()

  $nightly->run_tests({
    build_type            => 'make'            # || 'build'. 'make' is default.
    install_module        => 'all',            # || 'passed'. 'all' is default.
    skip_tests            => 1,                # skips the tests.
    test_directory_format => ['t/', 'tests/'], # Optional, defaults to ['t/'].
    test_file_format      => ['.t', '.pl'],    # Optional, defaults to ['.t'].
    test_order            => 'ordered',        # || 'random'. 'ordered' is default.
  });

Runs all the tests on the directories that are stored in the object.

Results are stored back in the object so they can be reported on.

generate_report()

  $nightly->generate_report({
    email_report    => \%email_config,                # Emails the report. See L<Test::Nightly::Email> for config options.
    report_template => '/dir/somewhere/template.txt', # Defaults to internal template.
    report_output   => '/dir/somewhere/output.txt',   # File to output the report to.
    test_report     => 'all',                         # 'failed' || 'passed'. Defaults to all.
  });

Based on the methods that have been run, produces a report on these.

Depending on what you pass in, defines what report is generated. If you pass in an email address to email_report then the report will be emailed. If you specify an output file to report_output then the report will be outputted to that file. If you specify both, then both will be done.

Default behavior is to use the internal template that is in Test::Nightly::Report::Template, however you can overwrite this with your own template (report_template). Uses Template Toolkit logic.

List of methods:

base_directories

Required. Array ref of base directories to search in.

build_script

Searches for the specified build_script names. Defaults to Makefile.PL

build_type

Pass this in so we know how you build your modules. There are two options: 'build' and 'make'. Defaults to 'make'.

debug

Turns debugging messages on or off.

email_report

If set will email the report. Takes a hash ref of \%email_config, refer to Test::Nightly::Email for the options.

install_module

Pass this in if you wish to have the module installed.

modules

List of modules that have been found, returns an array ref of undef.

skip_tests

Pass this in if you wish to skip running the tests.

report_output

Set this to a file somewhere and the report will be outputted here.

report_template

Pass this in if you wish to use your own customised report template. Otherwise uses the default template is in Test::Nightly::Report::Template

test

Holds the Test::Nightly::Test object.

test_directory_format

An array of what format the test directories can be. By default it searches for the tests in 't/'

test_file_format

An array of the test file formats you have.

test_report

This is where you specify what you wish to report on after the outcome of the test. Specifying 'passed' will only report on tests that passed, specifying 'failed' will only report on tests that failed and specifying 'all' will report on both.

test_order

Pass this in if you wish to influence the way the tests are run. Either 'ordered' or 'random'. Detauls to 'ordered'.

DISCLAIMERS

This module assumes that you only need installed modules to test your module. So if the module you're testing requires the changes you've made to another module in the tree that you haven't installed, testing will fail.

If your module asks interactive questions in the build script or test scripts then this won't work.

TODO

Soon I would like to implement a module that will handle version control, so you are able to checkout and update your modules for testing. As well as this it would be nice to incorporate in a wrapper for Devel::Cover.

Test::Nightly::Version, Test::Nightly::Coverage.

AUTHOR

Kirstin Bettiol <kirstinbettiol@gmail.com>

SEE ALSO

Test::Nightly, Test::Nightly::Test, Test::Nightly::Report, Test::Nightly::Email, perl.

COPYRIGHT

(c) 2005 Kirstin Bettiol This library is free software, you can use it under the same terms as perl itself.

THANKS

Thanks to Leo Lapworth <LLAP@cuckoo.org> for helping me with this and Foxtons for letting me develop this on their time.