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