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

NAME

Test::MonitorSites - Monitor availability and function of a list of websites

VERSION

This document describes Test::MonitorSites version 0.0.5

SYNOPSIS

    use Test::MonitorSites;
    my $tester = Test::MonitorSites->new({
            'config_file' => '/file/system/path/to/monitorsites.ini',
         });

    my $results = $tester->test_sites();
    $tester->email($results);
    if(defined($results->{'critical_failures'})){
        $tester->sms($results->{'critical_failures'});
    }

In addition to any global variables which may apply to an entire test suite, the configuration file ought to include an ini formatted section for each website the test suite defined by the configuration file ought to test or exercise. For full details on the permitted format, read perldoc Config::Simple. In this first example, we'll test the cpan.org site for accessible html markup and to ensure that the links all work. With the perlmonks site, we'll simply confirm that the site resolves and that its expected content can be found on the page.

        [site_www.cpan.org]
        ip='66.39.76.93'
        url='http://www.cpan.org'
        expected_content='Welcome to CPAN! Here you will find All Things Perl.'
        test_valid_html = 1
        test_links = 1
        
        [site_www.perlmonks.com]
        ip='66.39.54.27'
        url='http://www.perlmonks.com'
        expected_content='The Monastery Gates'

In the long run, as this develops, it is anticipated that the site definitions could take on the following structure, imagining the ability to test the functionality of a specific web application, and powered by an application specific module of the form Test::MonitorSites::MyWebApplication.

        [site_www.example.com]
        ip='192.168.1.1'
        url='http://www.example.com/myapp.cgi'
        expected_content='Welcome to MyApp!'
        user_field_name='login'
        password_field_name='password'
        user='mylogin'
        password='secret'
        
        [site_civicrm.example.com]
        url='http://civicrm.example.com/index.php'
        expected_content='Welcome to MyApp!'
        application=civicrm
        
        [site_drupal.example.com]
        url='http://drupal.example.com/index.php'
        expected_content='Welcome to MyApp!'
        application=drupal
        modules='excerpt,events,local_module'

DESCRIPTION

SUBROUTINES/METHODS

my $tester = Test::MonitorSites->new( 'config_file' => $config_file_path,);

Create a $tester object, giving access to other module methods. Constructor takes a hash with a single key, 'config_file' with a path (from root or relative) to an ini formatted configuration file.

$results = $tester->test_sites();

This method will permit a battery of tests to be run on each site defined in the configurations file. It returns a hash of results, which can then be examined and tested, or used to make reports.

$tester->email($results);

or

$tester->email($results,$recipients);

This method will email a report of test results to a recipients defined either in the configuration file or in the method call.

$tester->sms($results->{'critical_failures'});

or

$tester->sms($results->{'critical_failures'},$recipients);

This method will permit a notice of Critical Failures to be delivered by SMS messaging to a cell phone or pager device. The message is delivered to recipients defined in the configuration file or in the method call. If the global.report_by_ip configuration parameter is assigned to '1', then a single sms message per IP address with test failures will be sent. Otherwise, an sms message will be sent for each individual test failure, even for multiple failures on a single server.

INTERFACE

DIAGNOSTICS

No configuration data is available.

A configuration file was provided, but it contains no configuration data in a valid format. See the SYNOPSIS for details on valid variables which ought to be defined in your config file. See perldoc Config::Simple for details on its valid format.

The config_file was not found, or was empty.

The config file defined in the constructor is missing from the filesystem, or if it does exist, it is empty.

The config_file was not set in the constructor.

The module's constructor, the ->new() method, was invoked without a configuration file defined in the call.

No sites have been identified for testing. Please add sites to: (your config file)

An otherwise valid configuration file has been found, but it does not seem to have defined any sites to be tested.

CONFIGURATION AND ENVIRONMENT

The Test::MonitorSites constructor requires a configuration file using the ini Config::Simple format which defines global variables and contains an .ini section for each website to be monitored by this module.

DEPENDENCIES

This module uses the following modules, available on CPAN: Carp, Config::Simple, WWW::Mechanize, Test::WWW::Mechanize, Test::HTML::Tidy, HTTP::Request::Common, Test::More, Data::Dumper, Test::Builder.

INCOMPATIBILITIES

None reported.

BUGS AND LIMITATIONS

No bugs have been reported.

I welcome bug reports and feature requests at both: <http://www.campaignfoundations.com/project/issues> as well as through the cpan hosted channels at: "bug-test-monitorsites@rt.cpan.org", or through the web interface at <http://rt.cpan.org>.

AUTHOR

Hugh Esco <hesco@campaignfoundations.com>

LICENCE AND COPYRIGHT

Copyright (c) 2007, Hugh Esco <hesco@campaignfoundations.com>. All rights reserved.

This module is free software; you can redistribute it and/or modify it under the terms of the Gnu Public License. See gpl.

CREDITS

Initial development of this module done with th kind support of the Green Party of Canada. http://www.greenparty.ca/.

DISCLAIMER OF WARRANTY

BECAUSE THIS SOFTWARE IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY FOR THE SOFTWARE, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES PROVIDE THE SOFTWARE "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE SOFTWARE IS WITH YOU. SHOULD THE SOFTWARE PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR, OR CORRECTION.

IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR REDISTRIBUTE THE SOFTWARE AS PERMITTED BY THE ABOVE LICENCE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE SOFTWARE (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE SOFTWARE TO OPERATE WITH ANY OTHER SOFTWARE), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.