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