NPTest.pm

   1 package NPTest;
   2
   3 #
   4 # Helper Functions for testing Nagios Plugins
   5 #
   6
   7 require Exporter;
   8 @ISA       = qw(Exporter);
   9 @EXPORT    = qw(getTestParameter checkCmd skipMissingCmd);
  10 @EXPORT_OK = qw(DetermineTestHarnessDirectory TestsFrom SetCacheFilename);
  11
  12 use strict;
  13 use warnings;
  14
  15 use Cwd;
  16 use File::Basename;
  17
  18 use IO::File;
  19 use Data::Dumper;
  20
  21 use Test;
  22
  23 use vars qw($VERSION);
  24 $VERSION = do { my @r = (q$Revision$ =~ /\d+/g); sprintf "%d."."%02d" x $#r, @r }; # must be all one line, for MakeMaker
  25
  26 =head1 NAME
  27
  28 NPTest - Simplify the testing of Nagios Plugins
  29
  30 =head1 DESCRIPTION
  31
  32 This modules provides convenience functions to assist in the testing
  33 of Nagios Plugins, making the testing code easier to read and write;
  34 hopefully encouraging the development of a more complete test suite for
  35 the Nagios Plugins. It is based on the patterns of testing seen in the
  36 1.4.0 release, and continues to use the L<Test> module as the basis of
  37 testing.
  38
  39 =head1 FUNCTIONS
  40
  41 This module defines three public functions, C<getTestParameter(...)>,
  42 C<checkCmd(...)> and C<skipMissingCmd(...)>.  These are exported by
  43 default via the C<use NPTest;> statement.
  44
  45 =over
  46
  47 =item getTestParameter( "ENV_VARIABLE", $brief_description, $default )
  48
  49 $default is optional.
  50
  51 This function allows the test harness
  52 developer to interactively request test parameter information from the
  53 user. The user can accept the developer's default value or reply "none"
  54 which will then be returned as "" for the test to skip if appropriate.
  55
  56 If a parameter needs to be entered and the test is run without a tty
  57 attached (such as a cronjob), this routine will die causing the test to
  58 fail.
  59
  60 Responses are stored in an external, file-based
  61 cache so subsequent test runs will use these values. The user is able
  62 to change the values by amending the values in the file /var/tmp/NPTest.pm,
  63 or by setting the appropriate environment variable before running the test.
  64
  65 The option exists to store parameters in a scoped means, allowing a
  66 test harness to a localise a parameter should the need arise. This
  67 allows a parameter of the same name to exist in a test harness
  68 specific scope, while not affecting the globally scoped parameter. The
  69 scoping identifier is the name of the test harness sans the trailing
  70 ".t".  All cache searches first look to a scoped parameter before
  71 looking for the parameter at global scope. Thus for a test harness
  72 called "check_disk.t" requesting the parameter "mountpoint_valid", the
  73 cache is first searched for "check_disk"/"mountpoint_valid", if this
  74 fails, then a search is conducted for "mountpoint_valid".
  75
  76 To facilitate quick testing setup, it is possible to accept all the
  77 developer provided defaults by setting the environment variable
  78 "NPTEST_ACCEPTDEFAULT" to "1" (or any other perl truth value). Note
  79 that, such defaults are not stored in the cache, as there is currently
  80 no mechanism to edit existing cache entries, save the use of text
  81 editor or removing the cache file completely.
  82
  83 =item C<testCmd($command)>
  84
  85 Call with NPTest->testCmd("./check_disk ...."). This returns a NPTest object
  86 which you can then run $object->return_code or $object->output against.
  87
  88 Testing of results would be done in your test script, not in this module.
  89
  90 =item C<checkCmd(...)>
  91
  92 This function is obsolete. Use C<testCmd()> instead.
  93
  94 This function attempts to encompass the majority of test styles used
  95 in testing Nagios Plugins. As each plug-in is a separate command, the
  96 typical tests we wish to perform are against the exit status of the
  97 command and the output (if any) it generated. Simplifying these tests
  98 into a single function call, makes the test harness easier to read and
  99 maintain and allows additional functionality (such as debugging) to be
 100 provided without additional effort on the part of the test harness
 101 developer.
 102
 103 It is possible to enable debugging via the environment variable
 104 C<NPTEST_DEBUG>. If this environment variable exists and its value in PERL's
 105 boolean context evaluates to true, debugging is enabled.
 106
 107 The function prototype can be expressed as follows:
 108
 109   Parameter 1 : command => DEFINED SCALAR(string)
 110   Parameter 2 : desiredExitStatus => ONE OF
 111                   SCALAR(integer)
 112                   ARRAYREF(integer)
 113                   HASHREF(integer,string)
 114                   UNDEFINED
 115   Parameter 3 : desiredOutput => SCALAR(string) OR UNDEFINED
 116   Parameter 4 : exceptions => HASH(integer,string) OR UNDEFINED
 117   Returns     : SCALAR(integer) as defined by Test::ok(...)
 118
 119 The function treats the first parameter C<$command> as a command line
 120 to execute as part of the test, it is executed only once and its exit
 121 status (C<$?E<gt>E<gt>8>) and output are captured.
 122
 123 At this point if debugging is enabled the command, its exit status and
 124 output are displayed to the tester.
 125
 126 C<checkCmd(...)> allows the testing of either the exit status or the
 127 generated output or both, not testing either will result in neither
 128 the C<Test::ok(...)> or C<Test::skip(...)> functions being called,
 129 something you probably don't want. Note that each defined test
 130 (C<$desiredExitStatus> and C<$desiredOutput>) results in a invocation
 131 of either C<Test::ok(...)> or C<Test::skip(...)>, so remember this
 132 when counting the number of tests to place in the C<Test::plan(...)>
 133 call.
 134
 135 Many Nagios Plugins test network services, some of which may not be
 136 present on all systems. To cater for this, C<checkCmd(...)> allows the
 137 tester to define exceptions based on the command's exit status. These
 138 exceptions are provided to skip tests if the test case developer
 139 believes the service is not being provided. For example, if a site
 140 does not have a POP3 server, the test harness could map the
 141 appropriate exit status to a useful message the person running the
 142 tests, telling the reason the test is being skipped.
 143
 144 Example:
 145
 146 my %exceptions = ( 2 =E<gt> "No POP Server present?" );
 147
 148 $t += checkCmd( "./check_pop I<some args>", 0, undef, %exceptions );
 149
 150 Thus, in the above example, an exit status of 2 does not result in a
 151 failed test case (as the exit status is not the desired value of 0),
 152 but a skipped test case with the message "No POP Server present?"
 153 given as the reason.
 154
 155 Sometimes the exit status of a command should be tested against a set
 156 of possible values, rather than a single value, this could especially
 157 be the case in failure testing. C<checkCmd(...)> support two methods
 158 of testing against a set of desired exit status values.
 159
 160 =over
 161
 162 =item *
 163
 164 Firstly, if C<$desiredExitStatus> is a reference to an array of exit
 165 stati, if the actual exit status of the command is present in the
 166 array, it is used in the call to C<Test::ok(...)> when testing the
 167 exit status.
 168
 169 =item *
 170
 171 Alternatively, if C<$desiredExitStatus> is a reference to a hash of
 172 exit stati (mapped to the strings "continue" or "skip"), similar
 173 processing to the above occurs with the side affect of determining if
 174 any generated output testing should proceed. Note: only the string
 175 "skip" will result in generated output testing being skipped.
 176
 177 =back
 178
 179 =item C<skipMissingCmd(...)>
 180
 181 If a command is missing and the test harness must C<Test::skip()> some
 182 or all of the tests in a given test harness this function provides a
 183 simple iterator to issue an appropriate message the requested number
 184 of times.
 185
 186 =back
 187
 188 =head1 SEE ALSO
 189
 190 L<Test>
 191
 192 The rest of the code, as I have only commented on the major public
 193 functions that test harness writers will use, not all the code present
 194 in this helper module.
 195
 196 =head1 AUTHOR
 197
 198 Copyright (c) 2005 Peter Bray.  All rights reserved.
 199
 200 This package is free software and is provided "as is" without express
 201 or implied warranty.  It may be used, redistributed and/or modified
 202 under the same terms as the Nagios Plugins release.
 203
 204 =cut
 205
 206 #
 207 # Package Scope Variables
 208 #
 209
 210 my( %CACHE ) = ();
 211
 212 # I'm not really sure wether to house a site-specific cache inside
 213 # or outside of the extracted source / build tree - lets default to outside
 214 my( $CACHEFILENAME ) = ( exists( $ENV{'NPTEST_CACHE'} ) && $ENV{'NPTEST_CACHE'} )
 215                        ? $ENV{'NPTEST_CACHE'} : "/var/tmp/NPTest.cache"; # "../Cache.pdd";
 216
 217 #
 218 # Testing Functions
 219 #
 220
 221 sub checkCmd
 222 {
 223   my( $command, $desiredExitStatus, $desiredOutput, %exceptions ) = @_;
 224
 225   my $result = NPTest->testCmd($command);
 226
 227   my $output     = $result->output;
 228   my $exitStatus = $result->return_code;
 229
 230   $output = "" unless defined( $output );
 231   chomp( $output );
 232
 233   my $testStatus;
 234
 235   my $testOutput = "continue";
 236
 237   if ( defined( $desiredExitStatus ) )
 238   {
 239     if ( ref $desiredExitStatus eq "ARRAY" )
 240     {
 241       if ( scalar( grep { $_ == $exitStatus } @{$desiredExitStatus} ) )
 242       {
 243         $desiredExitStatus = $exitStatus;
 244       }
 245       else
 246       {
 247         $desiredExitStatus = -1;
 248       }
 249     }
 250     elsif ( ref $desiredExitStatus eq "HASH" )
 251     {
 252       if ( exists( ${$desiredExitStatus}{$exitStatus} ) )
 253       {
 254         if ( defined( ${$desiredExitStatus}{$exitStatus} ) )
 255         {
 256           $testOutput = ${$desiredExitStatus}{$exitStatus};
 257         }
 258         $desiredExitStatus = $exitStatus;
 259       }
 260       else
 261       {
 262         $desiredExitStatus = -1;
 263       }
 264     }
 265
 266     if ( %exceptions && exists( $exceptions{$exitStatus} ) )
 267     {
 268       $testStatus += skip( $exceptions{$exitStatus}, $exitStatus, $desiredExitStatus );
 269       $testOutput = "skip";
 270     }
 271     else
 272     {
 273       $testStatus += ok( $exitStatus, $desiredExitStatus );
 274     }
 275   }
 276
 277   if ( defined( $desiredOutput ) )
 278   {
 279     if ( $testOutput ne "skip" )
 280     {
 281       $testStatus += ok( $output, $desiredOutput );
 282     }
 283     else
 284     {
 285       $testStatus += skip( "Skipping output test as requested", $output, $desiredOutput );
 286     }
 287   }
 288
 289   return $testStatus;
 290 }
 291
 292
 293 sub skipMissingCmd
 294 {
 295   my( $command, $count ) = @_;
 296
 297   my $testStatus;
 298
 299   for ( 1 .. $count )
 300   {
 301     $testStatus += skip( "Missing ${command} - tests skipped", 1 );
 302   }
 303
 304   return $testStatus;
 305 }
 306
 307 sub getTestParameter
 308 {
 309   my( $param, $envvar, $default, $brief, $scoped );
 310   my $new_style;
 311   if (scalar @_ <= 3) {
 312         ($param, $brief, $default) = @_;
 313         $envvar = $param;
 314         $new_style = 1;
 315   } else {
 316         ( $param, $envvar, $default, $brief, $scoped ) = @_;
 317         $new_style = 0;
 318   }
 319
 320   # Apply default values for optional arguments
 321   $scoped = ( defined( $scoped ) && $scoped );
 322
 323   my $testharness = basename( (caller(0))[1], ".t" ); # used for scoping
 324
 325   if ( defined( $envvar ) &&  exists( $ENV{$envvar} ) && $ENV{$envvar} )
 326   {
 327     return $ENV{$envvar};
 328   }
 329
 330   my $cachedValue = SearchCache( $param, $testharness );
 331   if ( defined( $cachedValue ) )
 332   {
 333     # This save required to convert to new style because the key required is
 334     # changing to the environment variable
 335     if ($new_style == 0) {
 336       SetCacheParameter( $envvar, undef, $cachedValue );
 337     }
 338     return $cachedValue;
 339   }
 340
 341   my $defaultValid      = ( defined( $default ) && $default );
 342   my $autoAcceptDefault = ( exists( $ENV{'NPTEST_ACCEPTDEFAULT'} ) && $ENV{'NPTEST_ACCEPTDEFAULT'} );
 343
 344   if ( $autoAcceptDefault && $defaultValid )
 345   {
 346     return $default;
 347   }
 348
 349   die "Need to manually enter test parameter $param" unless (-t STDERR);
 350
 351   my $userResponse = "";
 352
 353   while ( $userResponse eq "" )
 354   {
 355     print STDERR "\n";
 356     print STDERR "Test Harness         : $testharness\n";
 357     print STDERR "Test Parameter       : $param\n";
 358     print STDERR "Environment Variable : $envvar\n" if ($param ne $envvar);
 359     print STDERR "Brief Description    : $brief\n";
 360     print STDERR "Enter value (or 'none') ", ($defaultValid ? "[${default}]" : "[]"), " => ";
 361     $userResponse = <STDIN>;
 362     $userResponse = "" if ! defined( $userResponse ); # Handle EOF
 363     chomp( $userResponse );
 364     if ( $defaultValid && $userResponse eq "" )
 365     {
 366       $userResponse = $default;
 367     }
 368   }
 369
 370   print STDERR "\n";
 371
 372   if ($userResponse =~ /^(na|none)$/) {
 373         $userResponse = "";
 374   }
 375
 376   # define all user responses at global scope
 377   SetCacheParameter( $param, ( $scoped ? $testharness : undef ), $userResponse );
 378
 379   return $userResponse;
 380 }
 381
 382 #
 383 # Internal Cache Management Functions
 384 #
 385
 386 sub SearchCache
 387 {
 388   my( $param, $scope ) = @_;
 389
 390   LoadCache();
 391
 392   if ( exists( $CACHE{$scope} ) && exists( $CACHE{$scope}{$param} ) )
 393   {
 394     return $CACHE{$scope}{$param};
 395   }
 396
 397   if ( exists( $CACHE{$param} ) )
 398   {
 399     return $CACHE{$param};
 400   }
 401   return undef; # Need this to say "nothing found"
 402 }
 403
 404 sub SetCacheParameter
 405 {
 406   my( $param, $scope, $value ) = @_;
 407
 408   if ( defined( $scope ) )
 409   {
 410     $CACHE{$scope}{$param} = $value;
 411   }
 412   else
 413   {
 414     $CACHE{$param} = $value;
 415   }
 416
 417   SaveCache();
 418 }
 419
 420 sub LoadCache
 421 {
 422   return if exists( $CACHE{'_cache_loaded_'} );
 423
 424   if ( -f $CACHEFILENAME )
 425   {
 426     my( $fileHandle ) = new IO::File;
 427
 428     if ( ! $fileHandle->open( "< ${CACHEFILENAME}" ) )
 429     {
 430       print STDERR "NPTest::LoadCache() : Problem opening ${CACHEFILENAME} : $!\n";
 431       return;
 432     }
 433
 434     my( $fileContents ) = join( "\n", <$fileHandle> );
 435
 436     $fileHandle->close();
 437
 438     my( $contentsRef ) = eval $fileContents;
 439     %CACHE = %{$contentsRef};
 440
 441   }
 442
 443   $CACHE{'_cache_loaded_'} = 1;
 444 }
 445
 446
 447 sub SaveCache
 448 {
 449   delete $CACHE{'_cache_loaded_'};
 450
 451   my( $fileHandle ) = new IO::File;
 452
 453   if ( ! $fileHandle->open( "> ${CACHEFILENAME}" ) )
 454   {
 455     print STDERR "NPTest::LoadCache() : Problem saving ${CACHEFILENAME} : $!\n";
 456     return;
 457   }
 458
 459   my( $dataDumper ) = new Data::Dumper( [ \%CACHE ] );
 460
 461   $dataDumper->Terse(1);
 462
 463   print $fileHandle $dataDumper->Dump();
 464
 465   $fileHandle->close();
 466
 467   $CACHE{'_cache_loaded_'} = 1;
 468 }
 469
 470 #
 471 # (Questionable) Public Cache Management Functions
 472 #
 473
 474 sub SetCacheFilename
 475 {
 476   my( $filename ) = @_;
 477
 478   # Unfortunately we can not validate the filename
 479   # in any meaningful way, as it may not yet exist
 480   $CACHEFILENAME = $filename;
 481 }
 482
 483
 484 #
 485 # Test Harness Wrapper Functions
 486 #
 487
 488 sub DetermineTestHarnessDirectory
 489 {
 490   my( $userSupplied ) = @_;
 491
 492   # User Supplied
 493   if ( defined( $userSupplied ) && $userSupplied )
 494   {
 495     if ( -d $userSupplied )
 496     {
 497       return $userSupplied;
 498     }
 499     else
 500     {
 501       return undef; # userSupplied is invalid -> FAIL
 502     }
 503   }
 504
 505   # Simple Case : "t" is a subdirectory of the current directory
 506   if ( -d "./t" )
 507   {
 508     return "./t";
 509   }
 510
 511   # To be honest I don't understand which case satisfies the
 512   # original code in test.pl : when $tstdir == `pwd` w.r.t.
 513   # $tstdir =~ s|^(.*)/([^/]+)/?$|$1/$2|; and if (-d "../../$2/t")
 514   # Assuming pwd is "/a/b/c/d/e" then we are testing for "/a/b/c/e/t"
 515   # if I understand the code correctly (a big assumption)
 516
 517   # Simple Case : the current directory is "t"
 518   my $pwd = cwd();
 519
 520   if ( $pwd =~ m|/t$| )
 521   {
 522     return $pwd;
 523
 524     # The alternate that might work better is
 525     # chdir( ".." );
 526     # return "./t";
 527     # As the current test harnesses assume the application
 528     # to be tested is in the current directory (ie "./check_disk ....")
 529   }
 530
 531   return undef;
 532 }
 533
 534 sub TestsFrom
 535 {
 536   my( $directory, $excludeIfAppMissing ) = @_;
 537
 538   $excludeIfAppMissing = 0 unless defined( $excludeIfAppMissing );
 539
 540   if ( ! opendir( DIR, $directory ) )
 541   {
 542     print STDERR "NPTest::TestsFrom() - Failed to open ${directory} : $!\n";
 543     return ();
 544   }
 545
 546   my( @tests ) = ();
 547
 548   my $filename;
 549   my $application;
 550
 551   while ( $filename = readdir( DIR ) )
 552   {
 553     if ( $filename =~ m/\.t$/ )
 554     {
 555       if ( $excludeIfAppMissing )
 556       {
 557         $application = basename( $filename, ".t" );
 558         if ( ! -e $application )
 559         {
 560           print STDERR "No application (${application}) found for test harness (${filename})\n";
 561           next;
 562         }
 563       }
 564       push @tests, "${directory}/${filename}";
 565     }
 566   }
 567
 568   closedir( DIR );
 569
 570   return sort @tests;
 571 }
 572
 573 # All the new object oriented stuff below
 574
 575 sub new {
 576         my $type = shift;
 577         my $self = {};
 578         return bless $self, $type;
 579 }
 580
 581 # Accessors
 582 sub return_code {
 583         my $self = shift;
 584         if (@_) {
 585                 return $self->{return_code} = shift;
 586         } else {
 587                 return $self->{return_code};
 588         }
 589 }
 590 sub output {
 591         my $self = shift;
 592         if (@_) {
 593                 return $self->{output} = shift;
 594         } else {
 595                 return $self->{output};
 596         }
 597 }
 598
 599 sub perf_output {
 600         my $self = shift;
 601         $_ = $self->{output};
 602         /\|(.*)$/;
 603         return $1 || "";
 604 }
 605
 606 sub testCmd {
 607         my $class = shift;
 608         my $command = shift or die "No command passed to testCmd";
 609         my $object = $class->new;
 610
 611         my $output = `$command`;
 612         $object->return_code($? >> 8);
 613         $_ = $? & 127;
 614         if ($_) {
 615                 die "Got signal $_ for command $command";
 616         }
 617         chomp $output;
 618         $object->output($output);
 619
 620         if ($ENV{'NPTEST_DEBUG'}) {
 621                 my ($pkg, $file, $line) = caller(0);
 622                 print "testCmd: Called from line $line in $file", $/;
 623                 print "Testing: $command", $/;
 624                 print "Output:  ", $object->output, $/;
 625                 print "Return code: ", $object->return_code, $/;
 626         }
 627
 628         return $object;
 629 }
 630
 631 1;
 632 #
 633 # End of File
 634 #