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 @STRICT_IGNORE
  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.12';
  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 our @STRICT_IGNORE;
  68
  69 # Load the configuration.
  70 if (!do($PATH)) {
  71     my $error = $@ || $! || 'loading file did not return true';
  72     BAIL_OUT("cannot load data/perl.conf: $error");
  73 }
  74
  75 1;
  76 __END__
  77
  78 =for stopwords
  79 Allbery rra-c-util Automake perlcritic .libs namespace subdirectory
  80 sublicense MERCHANTABILITY NONINFRINGEMENT
  81
  82 =head1 NAME
  83
  84 Test::RRA::Config - Perl test configuration
  85
  86 =head1 SYNOPSIS
  87
  88     use Test::RRA::Config qw($MINIMUM_VERSION);
  89     print "Required Perl version is $MINIMUM_VERSION\n";
  90
  91 =head1 DESCRIPTION
  92
  93 Test::RRA::Config encapsulates per-package configuration for generic Perl
  94 test programs that are shared between multiple packages using the
  95 rra-c-util infrastructure.  It handles locating and loading the test
  96 configuration file for both C Automake packages and stand-alone Perl
  97 modules.
  98
  99 Test::RRA::Config looks for a file named F<data/perl.conf> relative to the
 100 root of the test directory.  That root is taken from the environment
 101 variables BUILD or SOURCE (in that order) if set, which will be the case
 102 for C Automake packages using C TAP Harness.  If neither is set, it
 103 expects the root of the test directory to be a directory named F<t>
 104 relative to the current directory, which will be the case for stand-alone
 105 Perl modules.
 106
 107 The following variables are supported:
 108
 109 =over 4
 110
 111 =item $COVERAGE_LEVEL
 112
 113 The coverage level achieved by the test suite for Perl test coverage
 114 testing using Test::Strict, as a percentage.  The test will fail if test
 115 coverage less than this percentage is achieved.  If not given, defaults
 116 to 100.
 117
 118 =item @COVERAGE_SKIP_TESTS
 119
 120 Directories under F<t> whose tests should be skipped when doing coverage
 121 testing.  This can be tests that won't contribute to coverage or tests
 122 that don't run properly under Devel::Cover for some reason (such as ones
 123 that use taint checking).  F<docs> and F<style> will always be skipped
 124 regardless of this setting.
 125
 126 =item @CRITIC_IGNORE
 127
 128 Additional directories to ignore when doing recursive perlcritic testing.
 129 The contents of this directory must be either top-level directory names or
 130 directory names starting with F<tests/>.
 131
 132 =item $LIBRARY_PATH
 133
 134 Add this directory (or a F<.libs> subdirectory) relative to the top of the
 135 source tree to LD_LIBRARY_PATH when checking the syntax of Perl modules.
 136 This may be required to pick up libraries that are used by in-tree Perl
 137 modules so that Perl scripts can pass a syntax check.
 138
 139 =item $MINIMUM_VERSION
 140
 141 Default minimum version requirement for included Perl scripts.  If not
 142 given, defaults to 5.008.
 143
 144 =item %MINIMUM_VERSION
 145
 146 Minimum version exceptions for specific directories.  The keys should be
 147 minimum versions of Perl to enforce.  The value for each key should be a
 148 reference to an array of either top-level directory names or directory
 149 names starting with F<tests/>.  All files in those directories will have
 150 that minimum Perl version constraint imposed instead of $MINIMUM_VERSION.
 151
 152 =item @POD_COVERAGE_EXCLUDE
 153
 154 Regexes that match method names that should be excluded from POD coverage
 155 testing.  Normally, all methods have to be documented in the POD for a
 156 Perl module, but methods matching any of these regexes will be considered
 157 private and won't require documentation.
 158
 159 =item @STRICT_IGNORE
 160
 161 Additional directories to ignore when doing recursive Test::Strict testing
 162 for C<use strict> and C<use warnings>.  The contents of this directory
 163 must be either top-level directory names or directory names starting with
 164 F<tests/>.
 165
 166 =back
 167
 168 No variables are exported by default, but the variables can be imported
 169 into the local namespace to avoid long variable names.
 170
 171 =head1 AUTHOR
 172
 173 Russ Allbery <eagle@eyrie.org>
 174
 175 =head1 COPYRIGHT AND LICENSE
 176
 177 Copyright 2013 The Board of Trustees of the Leland Stanford Junior
 178 University
 179
 180 Permission is hereby granted, free of charge, to any person obtaining a
 181 copy of this software and associated documentation files (the "Software"),
 182 to deal in the Software without restriction, including without limitation
 183 the rights to use, copy, modify, merge, publish, distribute, sublicense,
 184 and/or sell copies of the Software, and to permit persons to whom the
 185 Software is furnished to do so, subject to the following conditions:
 186
 187 The above copyright notice and this permission notice shall be included in
 188 all copies or substantial portions of the Software.
 189
 190 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
 191 IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
 192 FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.  IN NO EVENT SHALL
 193 THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 194 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
 195 FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
 196 DEALINGS IN THE SOFTWARE.
 197
 198 =head1 SEE ALSO
 199
 200 perlcritic(1), Test::MinimumVersion(3), Test::RRA(3),
 201 Test::RRA::Automake(3), Test::Strict(3)
 202
 203 This module is maintained in the rra-c-util package.  The current version
 204 is available from L<http://www.eyrie.org/~eagle/software/rra-c-util/>.
 205
 206 The C TAP Harness test driver and libraries for TAP-based C testing are
 207 available from L<http://www.eyrie.org/~eagle/software/c-tap-harness/>.
 208
 209 =cut