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