Test::MonitorSites - Monitor availability and function of a list of websites
This document describes Test::MonitorSites version 0.14
use Test::MonitorSites; my $tester = Test::MonitorSites->new({ 'config_file' => '/file/system/path/to/monitorsites.ini', }); my $results = $tester->test_sites(); print $tester->{'errors'}; |--- now go check your email and sms pager. The ->test_sites() method will invoke the ->email() and ->sms() methods as appropriate given the settings in the configuration file used in the constructor. However, these methods are documented as public, and if it serves your needs to use them directly, feel free. $tester->{'config'}->param('global.results_recipients','metoo@example.com'); $tester->email($results); $tester->{'config'}->param('global.sms_recipients','12345559823@txt.example.com'); if(defined($results->{'critical_failures'})){ $tester->sms($results->{'critical_failures'}); }
A complete list of supported base configuration options includes the following listed in the global and critical_failure stanza's. Tests turned on in the critical_failure stanza determine which tests are sufficiently critical to warrant an sms message to a cell phone. All tests enabled are run and reported in the email summary report.
[global] sms_recipients = '7705552398@txt.example.net' results_recipients = 'admin@example.com' MonitorSites_subject = 'Critical Failures' MonitorSites_all_ok_subject = 'Servers A-OK' result_log = '/tmp/test_sites_output' send_summary = 1 send_diagnostics = 1 report_by_ip = 1 report_success = 1 test_links = 0 test_valid_html = 0 [critical_failure] linked_to = 1 expected_content = 1 all_links = 0 valid = 0
To run this module in quiet mode, set the following to '0' or leave undefined in the configuration: report_success, send_summary, send_diagnostics. If configured this way, sms messages will be sent to report critical failures, but no email summary reports will be sent.
It is possible to test the same set of sites hourly in quiet mode, and then using the $tester->{'config'}->param() method (documented as the ->param() method in perldoc Config::Simple), or an alternate ini file to run a sinle test each day with report_success set to '1', to get a daily reminder that the server from which these tests are run is itself up and running and that this module is still working as expected.
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.
For a full set of examples, take a look at the .t and .ini files in the t/ directory.
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.
Anyone interested in this functionality is urged to jump right in and help deliver it, or to contact the author about funding for this further development.
[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'
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.
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->{'errors'} can provide useful feedback on show stopping errors encountered.
or
This method will email a report of test results to the recipients defined either in the configuration file or in the method call.
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 or domain.
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 fails to define global.MonitorSites_email
Because your configuration file fails to define an email address to be used in the From: line of email generated by this module, the default From: line will be used instead.
We won't send an sms, there were no critical_failures and global.report_success is not set true.
Although this is reported to the 'error' log, it is not an error, so much as a report that the tests ran successfully and a reminder that to see a report of such success, the configuration option report_success can be set to '1'.
<We won't send an email, neither send_summary nor send_diagnostics were set to true in the configuration file
This error is thrown when the configuration is set to not send email. It serves primarily as a reminder of the configuration settings available to control the quiet mode of operation.
We won't send an email, there was no results_recipient defined in the configuration file.
This is an error. If you are going to run these tests, someone ought to get an occassional report of the results. Add your email address to the configuration file.
IP address not defined for $url.
This is a fatal error thrown by a private method used to analyze the test logs for results. After throwing this error, the module will die. The IP should be set by the constructor to a default '0.0.0.0' for any site defined in the configuration files without its own IP address. This error message was added to indicate when the constructor's failure to properly set this default was about to crash the analysis method.
Configuration file disabled email dispatch of results log.
Instead of adding the results log to the email report, the module throws this warning to the error log when the send_summary is set to false in the configuration file.
Configuration file disabled email dispatch of diagnostic log.
Instead of adding the diagnostics log to the email report, the module throws this warning to the error log when the send_diagnostics is set to false in the configuration file.
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.
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.
None reported.
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>.
Hugh Esco <hesco@campaignfoundations.com>
<hesco@campaignfoundations.com>
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.
Initial development of this module done with th kind support of the Green Party of Canada. http://www.greenparty.ca/.
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.
To install Test::MonitorSites, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Test::MonitorSites
CPAN shell
perl -MCPAN -e shell install Test::MonitorSites
For more information on module installation, please visit the detailed CPAN module installation guide.