tests/tap/perl/Test/RRA/Config.pm

   1 # Configuration for Perl test cases.
   2 #
   3 # In order to reuse the same Perl test cases in multiple packages, I use a
   4 # configuration file to store some package-specific data.  This module loads
   5 # that configuration and provides the namespace for the configuration
   6 # settings.
   7 #
   8 # The canonical version of this file is maintained in the rra-c-util package,
   9 # which can be found at <http://www.eyrie.org/~eagle/software/rra-c-util/>.
  10
  11 package Test::RRA::Config;
  12
  13 use 5.006;
  14 use strict;
  15 use warnings;
  16
  17 # For Perl 5.006 compatibility.
  18 ## no critic (ClassHierarchies::ProhibitExplicitISA)
  19
  20 use Exporter;
  21 use Test::More;
  22
  23 # Declare variables that should be set in BEGIN for robustness.
  24 our (@EXPORT_OK, @ISA, $VERSION);
  25
  26 # Set $VERSION and everything export-related in a BEGIN block for robustness
  27 # against circular module loading (not that we load any modules, but
  28 # consistency is good).
  29 BEGIN {
  30     @ISA       = qw(Exporter);
  31     @EXPORT_OK = qw(
  32       $COVERAGE_LEVEL @COVERAGE_SKIP_TESTS @CRITIC_IGNORE $LIBRARY_PATH
  33       $MINIMUM_VERSION %MINIMUM_VERSION @POD_COVERAGE_EXCLUDE
  34     );
  35
  36     # This version should match the corresponding rra-c-util release, but with
  37     # two digits for the minor version, including a leading zero if necessary,
  38     # so that it will sort properly.
  39     $VERSION = '4.09';
  40 }
  41
  42 # If BUILD or SOURCE are set in the environment, look for data/perl.conf under
  43 # those paths for a C Automake package.  Otherwise, look in t/data/perl.conf
  44 # for a standalone Perl module.  Don't use Test::RRA::Automake since it may
  45 # not exist.
  46 our $PATH;
  47 for my $base ($ENV{BUILD}, $ENV{SOURCE}, 't') {
  48     next if !defined($base);
  49     my $path = "$base/data/perl.conf";
  50     if (-r $path) {
  51         $PATH = $path;
  52         last;
  53     }
  54 }
  55 if (!defined($PATH)) {
  56     BAIL_OUT('cannot find data/perl.conf');
  57 }
  58
  59 # Pre-declare all of our variables and set any defaults.
  60 our $COVERAGE_LEVEL = 100;
  61 our @COVERAGE_SKIP_TESTS;
  62 our @CRITIC_IGNORE;
  63 our $LIBRARY_PATH;
  64 our $MINIMUM_VERSION = '5.008';
  65 our %MINIMUM_VERSION;
  66 our @POD_COVERAGE_EXCLUDE;
  67
  68 # Load the configuration.
  69 if (!do($PATH)) {
  70     my $error = $@ || $! || 'loading file did not return true';
  71     BAIL_OUT("cannot load data/perl.conf: $error");
  72 }
  73
  74 1;
  75 __END__
  76
  77 =for stopwords
  78 Allbery rra-c-util Automake perlcritic .libs namespace subdirectory
  79 sublicense MERCHANTABILITY NONINFRINGEMENT
  80
  81 =head1 NAME
  82
  83 Test::RRA::Config - Perl test configuration
  84
  85 =head1 SYNOPSIS
  86
  87     use Test::RRA::Config qw($MINIMUM_VERSION);
  88     print "Required Perl version is $MINIMUM_VERSION\n";
  89
  90 =head1 DESCRIPTION
  91
  92 Test::RRA::Config encapsulates per-package configuration for generic Perl
  93 test programs that are shared between multiple packages using the
  94 rra-c-util infrastructure.  It handles locating and loading the test
  95 configuration file for both C Automake packages and stand-alone Perl
  96 modules.
  97
  98 Test::RRA::Config looks for a file named F<data/perl.conf> relative to the
  99 root of the test directory.  That root is taken from the environment
 100 variables BUILD or SOURCE (in that order) if set, which will be the case
 101 for C Automake packages using C TAP Harness.  If neither is set, it
 102 expects the root of the test directory to be a directory named F<t>
 103 relative to the current directory, which will be the case for stand-alone
 104 Perl modules.
 105
 106 The following variables are supported:
 107
 108 =over 4
 109
 110 =item $COVERAGE_LEVEL
 111
 112 The coverage level achieved by the test suite for Perl test coverage
 113 testing using Test::Strict, as a percentage.  The test will fail if test
 114 coverage less than this percentage is achieved.  If not given, defaults
 115 to 100.
 116
 117 =item @COVERAGE_SKIP_TESTS
 118
 119 Directories under F<t> whose tests should be skipped when doing coverage
 120 testing.  This can be tests that won't contribute to coverage or tests
 121 that don't run properly under Devel::Cover for some reason (such as ones
 122 that use taint checking).  F<docs> and F<style> will always be skipped
 123 regardless of this setting.
 124
 125 =item @CRITIC_IGNORE
 126
 127 Additional directories to ignore when doing recursive perlcritic testing.
 128 The contents of this directory must be either top-level directory names or
 129 directory names starting with F<tests/>.
 130
 131 =item $LIBRARY_PATH
 132
 133 Add this directory (or a .libs subdirectory) relative to the top of the
 134 source tree to LD_LIBRARY_PATH when checking the syntax of Perl modules.
 135 This may be required to pick up libraries that are used by in-tree Perl
 136 modules so that Perl scripts can pass a syntax check.
 137
 138 =item $MINIMUM_VERSION
 139
 140 Default minimum version requirement for included Perl scripts.  If not
 141 given, defaults to 5.008.
 142
 143 =item %MINIMUM_VERSION
 144
 145 Minimum version exceptions for specific directories.  The keys should be
 146 minimum versions of Perl to enforce.  The value for each key should be a
 147 reference to an array of either top-level directory names or directory
 148 names starting with F<tests/>.  All files in those directories will have
 149 that minimum Perl version constraint imposed instead of $MINIMUM_VERSION.
 150
 151 =item @POD_COVERAGE_EXCLUDE
 152
 153 Regexes that match method names that should be excluded from POD coverage
 154 testing.  Normally, all methods have to be documented in the POD for a
 155 Perl module, but methods matching any of these regexes will be considered
 156 private and won't require documentation.
 157
 158 =back
 159
 160 No variables are exported by default, but the variables can be imported
 161 into the local namespace to avoid long variable names.
 162
 163 =head1 AUTHOR
 164
 165 Russ Allbery <rra@stanford.edu>
 166
 167 =head1 COPYRIGHT AND LICENSE
 168
 169 Copyright 2013 The Board of Trustees of the Leland Stanford Junior
 170 University
 171
 172 Permission is hereby granted, free of charge, to any person obtaining a
 173 copy of this software and associated documentation files (the "Software"),
 174 to deal in the Software without restriction, including without limitation
 175 the rights to use, copy, modify, merge, publish, distribute, sublicense,
 176 and/or sell copies of the Software, and to permit persons to whom the
 177 Software is furnished to do so, subject to the following conditions:
 178
 179 The above copyright notice and this permission notice shall be included in
 180 all copies or substantial portions of the Software.
 181
 182 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
 183 IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
 184 FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.  IN NO EVENT SHALL
 185 THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 186 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
 187 FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
 188 DEALINGS IN THE SOFTWARE.
 189
 190 =head1 SEE ALSO
 191
 192 Test::RRA(3), Test::RRA::Automake(3)
 193
 194 This module is maintained in the rra-c-util package.  The current version
 195 is available from L<http://www.eyrie.org/~eagle/software/rra-c-util/>.
 196
 197 The C TAP Harness test driver and libraries for TAP-based C testing are
 198 available from L<http://www.eyrie.org/~eagle/software/c-tap-harness/>.
 199
 200 =cut