diff options
Diffstat (limited to 'tests/tap/perl')
| -rw-r--r-- | tests/tap/perl/Test/RRA.pm | 104 | ||||
| -rw-r--r-- | tests/tap/perl/Test/RRA/Automake.pm | 166 | ||||
| -rw-r--r-- | tests/tap/perl/Test/RRA/Config.pm | 138 | ||||
| -rw-r--r-- | tests/tap/perl/Test/RRA/ModuleVersion.pm | 295 |
4 files changed, 477 insertions, 226 deletions
diff --git a/tests/tap/perl/Test/RRA.pm b/tests/tap/perl/Test/RRA.pm index bb7de7d..8608e31 100644 --- a/tests/tap/perl/Test/RRA.pm +++ b/tests/tap/perl/Test/RRA.pm @@ -5,31 +5,6 @@ # by both C packages with Automake and by stand-alone Perl modules. See # Test::RRA::Automake for additional functions specifically for C Automake # distributions. -# -# The canonical version of this file is maintained in the rra-c-util package, -# which can be found at <http://www.eyrie.org/~eagle/software/rra-c-util/>. -# -# Written by Russ Allbery <eagle@eyrie.org> -# Copyright 2013, 2014 -# The Board of Trustees of the Leland Stanford Junior University -# -# Permission is hereby granted, free of charge, to any person obtaining a -# copy of this software and associated documentation files (the "Software"), -# to deal in the Software without restriction, including without limitation -# the rights to use, copy, modify, merge, publish, distribute, sublicense, -# and/or sell copies of the Software, and to permit persons to whom the -# Software is furnished to do so, subject to the following conditions: -# -# The above copyright notice and this permission notice shall be included in -# all copies or substantial portions of the Software. -# -# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR -# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, -# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL -# THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER -# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING -# FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER -# DEALINGS IN THE SOFTWARE. package Test::RRA; @@ -56,7 +31,7 @@ BEGIN { # This version should match the corresponding rra-c-util release, but with # two digits for the minor version, including a leading zero if necessary, # so that it will sort properly. - $VERSION = '5.05'; + $VERSION = '5.10'; } # Skip this test unless author tests are requested. Takes a short description @@ -153,7 +128,7 @@ __END__ =for stopwords Allbery Allbery's DESC bareword sublicense MERCHANTABILITY NONINFRINGEMENT -rra-c-util +rra-c-util CPAN =head1 NAME @@ -176,46 +151,45 @@ Test::RRA - Support functions for Perl tests =head1 DESCRIPTION -This module collects utility functions that are useful for Perl test -scripts. It assumes Russ Allbery's Perl module layout and test -conventions and will only be useful for other people if they use the -same conventions. +This module collects utility functions that are useful for Perl test scripts. +It assumes Russ Allbery's Perl module layout and test conventions and will +only be useful for other people if they use the same conventions. =head1 FUNCTIONS -None of these functions are imported by default. The ones used by a -script should be explicitly imported. +None of these functions are imported by default. The ones used by a script +should be explicitly imported. =over 4 =item skip_unless_author(DESC) -Checks whether AUTHOR_TESTING is set in the environment and skips the -whole test (by calling C<plan skip_all> from Test::More) if it is not. -DESC is a description of the tests being skipped. A space and C<only run -for author> will be appended to it and used as the skip reason. +Checks whether AUTHOR_TESTING is set in the environment and skips the whole +test (by calling C<plan skip_all> from Test::More) if it is not. DESC is a +description of the tests being skipped. A space and C<only run for author> +will be appended to it and used as the skip reason. =item skip_unless_automated(DESC) -Checks whether AUTHOR_TESTING, AUTOMATED_TESTING, or RELEASE_TESTING are -set in the environment and skips the whole test (by calling C<plan -skip_all> from Test::More) if they are not. This should be used by tests -that should not run during end-user installs of the module, but which -should run as part of CPAN smoke testing and release testing. +Checks whether AUTHOR_TESTING, AUTOMATED_TESTING, or RELEASE_TESTING are set +in the environment and skips the whole test (by calling C<plan skip_all> from +Test::More) if they are not. This should be used by tests that should not run +during end-user installs of the module, but which should run as part of CPAN +smoke testing and release testing. DESC is a description of the tests being skipped. A space and C<normally skipped> will be appended to it and used as the skip reason. =item use_prereq(MODULE[, VERSION][, IMPORT ...]) -Attempts to load MODULE with the given VERSION and import arguments. If -this fails for any reason, the test will be skipped (by calling C<plan -skip_all> from Test::More) with a skip reason saying that MODULE is -required for the test. +Attempts to load MODULE with the given VERSION and import arguments. If this +fails for any reason, the test will be skipped (by calling C<plan skip_all> +from Test::More) with a skip reason saying that MODULE is required for the +test. VERSION will be passed to C<use> as a version bareword if it looks like a -version number. The remaining IMPORT arguments will be passed as the -value of an array. +version number. The remaining IMPORT arguments will be passed as the value of +an array. =back @@ -228,33 +202,33 @@ Russ Allbery <eagle@eyrie.org> Copyright 2013, 2014 The Board of Trustees of the Leland Stanford Junior University -Permission is hereby granted, free of charge, to any person obtaining a -copy of this software and associated documentation files (the "Software"), -to deal in the Software without restriction, including without limitation -the rights to use, copy, modify, merge, publish, distribute, sublicense, -and/or sell copies of the Software, and to permit persons to whom the -Software is furnished to do so, subject to the following conditions: +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: -The above copyright notice and this permission notice shall be included in -all copies or substantial portions of the Software. +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, -FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL -THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER -LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING -FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER -DEALINGS IN THE SOFTWARE. +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. =head1 SEE ALSO Test::More(3), Test::RRA::Automake(3), Test::RRA::Config(3) -This module is maintained in the rra-c-util package. The current version -is available from L<http://www.eyrie.org/~eagle/software/rra-c-util/>. +This module is maintained in the rra-c-util package. The current version is +available from L<http://www.eyrie.org/~eagle/software/rra-c-util/>. -The functions to control when tests are run use environment variables -defined by the L<Lancaster +The functions to control when tests are run use environment variables defined +by the L<Lancaster Consensus|https://github.com/Perl-Toolchain-Gang/toolchain-site/blob/master/lancaster-consensus.md>. =cut diff --git a/tests/tap/perl/Test/RRA/Automake.pm b/tests/tap/perl/Test/RRA/Automake.pm index a064ed9..c6399ec 100644 --- a/tests/tap/perl/Test/RRA/Automake.pm +++ b/tests/tap/perl/Test/RRA/Automake.pm @@ -9,31 +9,6 @@ # # All the functions here assume that BUILD and SOURCE are set in the # environment. This is normally done via the C TAP Harness runtests wrapper. -# -# The canonical version of this file is maintained in the rra-c-util package, -# which can be found at <http://www.eyrie.org/~eagle/software/rra-c-util/>. -# -# Written by Russ Allbery <eagle@eyrie.org> -# Copyright 2013 -# The Board of Trustees of the Leland Stanford Junior University -# -# Permission is hereby granted, free of charge, to any person obtaining a -# copy of this software and associated documentation files (the "Software"), -# to deal in the Software without restriction, including without limitation -# the rights to use, copy, modify, merge, publish, distribute, sublicense, -# and/or sell copies of the Software, and to permit persons to whom the -# Software is furnished to do so, subject to the following conditions: -# -# The above copyright notice and this permission notice shall be included in -# all copies or substantial portions of the Software. -# -# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR -# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, -# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL -# THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER -# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING -# FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER -# DEALINGS IN THE SOFTWARE. package Test::RRA::Automake; @@ -87,13 +62,13 @@ BEGIN { # This version should match the corresponding rra-c-util release, but with # two digits for the minor version, including a leading zero if necessary, # so that it will sort properly. - $VERSION = '5.05'; + $VERSION = '5.10'; } # Perl directories to skip globally for perl_dirs. We ignore the perl # directory if it exists since, in my packages, it is treated as a Perl module # distribution and has its own standalone test suite. -my @GLOBAL_SKIP = qw(.git perl); +my @GLOBAL_SKIP = qw(.git _build perl); # The temporary directory created by test_tmpdir, if any. If this is set, # attempt to remove the directory stored here on program exit (but ignore @@ -126,7 +101,15 @@ sub automake_setup { my ($vol, $dirs) = File::Spec->splitpath($start, 1); my @dirs = File::Spec->splitdir($dirs); pop(@dirs); - if ($dirs[-1] eq File::Spec->updir) { + + # Simplify relative paths at the end of the directory. + my $ups = 0; + my $i = $#dirs; + while ($i > 2 && $dirs[$i] eq File::Spec->updir) { + $ups++; + $i--; + } + for (1 .. $ups) { pop(@dirs); pop(@dirs); } @@ -196,7 +179,7 @@ sub perl_dirs { # Build the list of top-level directories to test. opendir(my $rootdir, q{.}) or BAIL_OUT("cannot open .: $!"); - my @dirs = grep { -d $_ && !$skip{$_} } readdir($rootdir); + my @dirs = grep { -d && !$skip{$_} } readdir($rootdir); closedir($rootdir); @dirs = File::Spec->no_upwards(@dirs); @@ -288,8 +271,8 @@ END { __END__ =for stopwords -Allbery Automake Automake-aware Automake-based rra-c-util ARGS -subdirectories sublicense MERCHANTABILITY NONINFRINGEMENT umask +Allbery Automake Automake-aware Automake-based rra-c-util ARGS subdirectories +sublicense MERCHANTABILITY NONINFRINGEMENT umask =head1 NAME @@ -309,75 +292,71 @@ Test::RRA::Automake - Automake-aware support functions for Perl tests =head1 DESCRIPTION This module collects utility functions that are useful for test scripts -written in Perl and included in a C Automake-based package. They assume -the layout of a package that uses rra-c-util and C TAP Harness for the -test structure. +written in Perl and included in a C Automake-based package. They assume the +layout of a package that uses rra-c-util and C TAP Harness for the test +structure. Loading this module will also add the directories C<perl/blib/arch> and -C<perl/blib/lib> to the Perl library search path, relative to BUILD if -that environment variable is set. This is harmless for C Automake -projects that don't contain an embedded Perl module, and for those -projects that do, this will allow subsequent C<use> calls to find modules -that are built as part of the package build process. +C<perl/blib/lib> to the Perl library search path, relative to BUILD if that +environment variable is set. This is harmless for C Automake projects that +don't contain an embedded Perl module, and for those projects that do, this +will allow subsequent C<use> calls to find modules that are built as part of +the package build process. The automake_setup() function should be called before calling any other functions provided by this module. =head1 FUNCTIONS -None of these functions are imported by default. The ones used by a -script should be explicitly imported. On failure, all of these functions -call BAIL_OUT (from Test::More). +None of these functions are imported by default. The ones used by a script +should be explicitly imported. On failure, all of these functions call +BAIL_OUT (from Test::More). =over 4 =item automake_setup([ARGS]) -Verifies that the BUILD and SOURCE environment variables are set and -then changes directory to the top of the source tree (which is one -directory up from the SOURCE path, since SOURCE points to the top of -the tests directory). +Verifies that the BUILD and SOURCE environment variables are set and then +changes directory to the top of the source tree (which is one directory up +from the SOURCE path, since SOURCE points to the top of the tests directory). -If ARGS is given, it should be a reference to a hash of configuration -options. Only one option is supported: C<chdir_build>. If it is set -to a true value, automake_setup() changes directories to the top of -the build tree instead. +If ARGS is given, it should be a reference to a hash of configuration options. +Only one option is supported: C<chdir_build>. If it is set to a true value, +automake_setup() changes directories to the top of the build tree instead. =item perl_dirs([ARGS]) Returns a list of directories that may contain Perl scripts that should be -tested by test scripts that test all Perl in the source tree (such as -syntax or coding style checks). The paths will be simple directory names -relative to the current directory or two-part directory names under the -F<tests> directory. (Directories under F<tests> are broken out separately -since it's common to want to apply different policies to different -subdirectories of F<tests>.) - -If ARGS is given, it should be a reference to a hash of configuration -options. Only one option is supported: C<skip>, whose value should be a -reference to an array of additional top-level directories or directories -starting with C<tests/> that should be skipped. +tested by test scripts that test all Perl in the source tree (such as syntax +or coding style checks). The paths will be simple directory names relative to +the current directory or two-part directory names under the F<tests> +directory. (Directories under F<tests> are broken out separately since it's +common to want to apply different policies to different subdirectories of +F<tests>.) + +If ARGS is given, it should be a reference to a hash of configuration options. +Only one option is supported: C<skip>, whose value should be a reference to an +array of additional top-level directories or directories starting with +C<tests/> that should be skipped. =item test_file_path(FILE) -Given FILE, which should be a relative path, locates that file relative to -the test directory in either the source or build tree. FILE will be -checked for relative to the environment variable BUILD first, and then -relative to SOURCE. test_file_path() returns the full path to FILE or -calls BAIL_OUT if FILE could not be found. +Given FILE, which should be a relative path, locates that file relative to the +test directory in either the source or build tree. FILE will be checked for +relative to the environment variable BUILD first, and then relative to SOURCE. +test_file_path() returns the full path to FILE or calls BAIL_OUT if FILE could +not be found. =item test_tmpdir() -Create a temporary directory for tests to use for transient files and -return the path to that directory. The directory is created relative to -the BUILD environment variable, which must be set. Permissions on the -directory are set using the current umask. test_tmpdir() returns the full -path to the temporary directory or calls BAIL_OUT if it could not be -created. +Create a temporary directory for tests to use for transient files and return +the path to that directory. The directory is created relative to the BUILD +environment variable, which must be set. Permissions on the directory are set +using the current umask. test_tmpdir() returns the full path to the temporary +directory or calls BAIL_OUT if it could not be created. -The directory is automatically removed if possible on program exit. -Failure to remove the directory on exit is reported with diag() and -otherwise ignored. +The directory is automatically removed if possible on program exit. Failure +to remove the directory on exit is reported with diag() and otherwise ignored. =back @@ -387,35 +366,36 @@ Russ Allbery <eagle@eyrie.org> =head1 COPYRIGHT AND LICENSE -Copyright 2013 The Board of Trustees of the Leland Stanford Junior -University +Copyright 2014, 2015 Russ Allbery <eagle@eyrie.org> + +Copyright 2013 The Board of Trustees of the Leland Stanford Junior University -Permission is hereby granted, free of charge, to any person obtaining a -copy of this software and associated documentation files (the "Software"), -to deal in the Software without restriction, including without limitation -the rights to use, copy, modify, merge, publish, distribute, sublicense, -and/or sell copies of the Software, and to permit persons to whom the -Software is furnished to do so, subject to the following conditions: +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: -The above copyright notice and this permission notice shall be included in -all copies or substantial portions of the Software. +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, -FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL -THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER -LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING -FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER -DEALINGS IN THE SOFTWARE. +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. =head1 SEE ALSO Test::More(3), Test::RRA(3), Test::RRA::Config(3) +This module is maintained in the rra-c-util package. The current version is +available from L<http://www.eyrie.org/~eagle/software/rra-c-util/>. + The C TAP Harness test driver and libraries for TAP-based C testing are available from L<http://www.eyrie.org/~eagle/software/c-tap-harness/>. -This module is maintained in the rra-c-util package. The current version -is available from L<http://www.eyrie.org/~eagle/software/rra-c-util/>. - =cut diff --git a/tests/tap/perl/Test/RRA/Config.pm b/tests/tap/perl/Test/RRA/Config.pm index 3e77650..a5b0d0d 100644 --- a/tests/tap/perl/Test/RRA/Config.pm +++ b/tests/tap/perl/Test/RRA/Config.pm @@ -4,9 +4,6 @@ # configuration file to store some package-specific data. This module loads # that configuration and provides the namespace for the configuration # settings. -# -# The canonical version of this file is maintained in the rra-c-util package, -# which can be found at <http://www.eyrie.org/~eagle/software/rra-c-util/>. package Test::RRA::Config; @@ -30,22 +27,23 @@ BEGIN { @ISA = qw(Exporter); @EXPORT_OK = qw( $COVERAGE_LEVEL @COVERAGE_SKIP_TESTS @CRITIC_IGNORE $LIBRARY_PATH - $MINIMUM_VERSION %MINIMUM_VERSION @POD_COVERAGE_EXCLUDE @STRICT_IGNORE - @STRICT_PREREQ + $MINIMUM_VERSION %MINIMUM_VERSION @MODULE_VERSION_IGNORE + @POD_COVERAGE_EXCLUDE @STRICT_IGNORE @STRICT_PREREQ ); # This version should match the corresponding rra-c-util release, but with # two digits for the minor version, including a leading zero if necessary, # so that it will sort properly. - $VERSION = '5.05'; + $VERSION = '5.10'; } # If BUILD or SOURCE are set in the environment, look for data/perl.conf under # those paths for a C Automake package. Otherwise, look in t/data/perl.conf -# for a standalone Perl module. Don't use Test::RRA::Automake since it may -# not exist. +# for a standalone Perl module or tests/data/perl.conf for Perl tests embedded +# in a larger distribution. Don't use Test::RRA::Automake since it may not +# exist. our $PATH; -for my $base ($ENV{BUILD}, $ENV{SOURCE}, 't') { +for my $base ($ENV{BUILD}, $ENV{SOURCE}, 't', 'tests') { next if !defined($base); my $path = "$base/data/perl.conf"; if (-r $path) { @@ -64,6 +62,7 @@ our @CRITIC_IGNORE; our $LIBRARY_PATH; our $MINIMUM_VERSION = '5.008'; our %MINIMUM_VERSION; +our @MODULE_VERSION_IGNORE; our @POD_COVERAGE_EXCLUDE; our @STRICT_IGNORE; our @STRICT_PREREQ; @@ -78,8 +77,8 @@ if (!do($PATH)) { __END__ =for stopwords -Allbery rra-c-util Automake perlcritic .libs namespace subdirectory -sublicense MERCHANTABILITY NONINFRINGEMENT +Allbery rra-c-util Automake perlcritic .libs namespace subdirectory sublicense +MERCHANTABILITY NONINFRINGEMENT regexes =head1 NAME @@ -92,19 +91,17 @@ Test::RRA::Config - Perl test configuration =head1 DESCRIPTION -Test::RRA::Config encapsulates per-package configuration for generic Perl -test programs that are shared between multiple packages using the -rra-c-util infrastructure. It handles locating and loading the test -configuration file for both C Automake packages and stand-alone Perl -modules. +Test::RRA::Config encapsulates per-package configuration for generic Perl test +programs that are shared between multiple packages using the rra-c-util +infrastructure. It handles locating and loading the test configuration file +for both C Automake packages and stand-alone Perl modules. Test::RRA::Config looks for a file named F<data/perl.conf> relative to the -root of the test directory. That root is taken from the environment -variables BUILD or SOURCE (in that order) if set, which will be the case -for C Automake packages using C TAP Harness. If neither is set, it -expects the root of the test directory to be a directory named F<t> -relative to the current directory, which will be the case for stand-alone -Perl modules. +root of the test directory. That root is taken from the environment variables +BUILD or SOURCE (in that order) if set, which will be the case for C Automake +packages using C TAP Harness. If neither is set, it expects the root of the +test directory to be a directory named F<t> relative to the current directory, +which will be the case for stand-alone Perl modules. The following variables are supported: @@ -112,70 +109,75 @@ The following variables are supported: =item $COVERAGE_LEVEL -The coverage level achieved by the test suite for Perl test coverage -testing using Test::Strict, as a percentage. The test will fail if test -coverage less than this percentage is achieved. If not given, defaults -to 100. +The coverage level achieved by the test suite for Perl test coverage testing +using Test::Strict, as a percentage. The test will fail if test coverage less +than this percentage is achieved. If not given, defaults to 100. =item @COVERAGE_SKIP_TESTS Directories under F<t> whose tests should be skipped when doing coverage -testing. This can be tests that won't contribute to coverage or tests -that don't run properly under Devel::Cover for some reason (such as ones -that use taint checking). F<docs> and F<style> will always be skipped -regardless of this setting. +testing. This can be tests that won't contribute to coverage or tests that +don't run properly under Devel::Cover for some reason (such as ones that use +taint checking). F<docs> and F<style> will always be skipped regardless of +this setting. =item @CRITIC_IGNORE -Additional directories to ignore when doing recursive perlcritic testing. -The contents of this directory must be either top-level directory names or +Additional directories to ignore when doing recursive perlcritic testing. The +contents of this directory must be either top-level directory names or directory names starting with F<tests/>. =item $LIBRARY_PATH Add this directory (or a F<.libs> subdirectory) relative to the top of the -source tree to LD_LIBRARY_PATH when checking the syntax of Perl modules. -This may be required to pick up libraries that are used by in-tree Perl -modules so that Perl scripts can pass a syntax check. +source tree to LD_LIBRARY_PATH when checking the syntax of Perl modules. This +may be required to pick up libraries that are used by in-tree Perl modules so +that Perl scripts can pass a syntax check. =item $MINIMUM_VERSION -Default minimum version requirement for included Perl scripts. If not -given, defaults to 5.008. +Default minimum version requirement for included Perl scripts. If not given, +defaults to 5.008. =item %MINIMUM_VERSION Minimum version exceptions for specific directories. The keys should be minimum versions of Perl to enforce. The value for each key should be a -reference to an array of either top-level directory names or directory -names starting with F<tests/>. All files in those directories will have -that minimum Perl version constraint imposed instead of $MINIMUM_VERSION. +reference to an array of either top-level directory names or directory names +starting with F<tests/>. All files in those directories will have that +minimum Perl version constraint imposed instead of $MINIMUM_VERSION. + +=item @MODULE_VERSION_IGNORE + +File names to ignore when checking that all modules in a distribution have the +same version. Sometimes, some specific modules need separate, special version +handling, such as modules defining database schemata for DBIx::Class, and +can't follow the version of the larger package. =item @POD_COVERAGE_EXCLUDE Regexes that match method names that should be excluded from POD coverage -testing. Normally, all methods have to be documented in the POD for a -Perl module, but methods matching any of these regexes will be considered -private and won't require documentation. +testing. Normally, all methods have to be documented in the POD for a Perl +module, but methods matching any of these regexes will be considered private +and won't require documentation. =item @STRICT_IGNORE -Additional directories to ignore when doing recursive Test::Strict testing -for C<use strict> and C<use warnings>. The contents of this directory -must be either top-level directory names or directory names starting with -F<tests/>. +Additional directories to ignore when doing recursive Test::Strict testing for +C<use strict> and C<use warnings>. The contents of this directory must be +either top-level directory names or directory names starting with F<tests/>. =item @STRICT_PREREQ A list of Perl modules that have to be available in order to do meaningful Test::Strict testing. If any of the modules cannot be loaded via C<use>, -Test::Strict checking will be skipped. There is currently no way to -require specific versions of the modules. +Test::Strict checking will be skipped. There is currently no way to require +specific versions of the modules. =back -No variables are exported by default, but the variables can be imported -into the local namespace to avoid long variable names. +No variables are exported by default, but the variables can be imported into +the local namespace to avoid long variable names. =head1 AUTHOR @@ -186,31 +188,31 @@ Russ Allbery <eagle@eyrie.org> Copyright 2013, 2014 The Board of Trustees of the Leland Stanford Junior University -Permission is hereby granted, free of charge, to any person obtaining a -copy of this software and associated documentation files (the "Software"), -to deal in the Software without restriction, including without limitation -the rights to use, copy, modify, merge, publish, distribute, sublicense, -and/or sell copies of the Software, and to permit persons to whom the -Software is furnished to do so, subject to the following conditions: +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: -The above copyright notice and this permission notice shall be included in -all copies or substantial portions of the Software. +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, -FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL -THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER -LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING -FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER -DEALINGS IN THE SOFTWARE. +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. =head1 SEE ALSO -perlcritic(1), Test::MinimumVersion(3), Test::RRA(3), -Test::RRA::Automake(3), Test::Strict(3) +perlcritic(1), Test::MinimumVersion(3), Test::RRA(3), Test::RRA::Automake(3), +Test::Strict(3) -This module is maintained in the rra-c-util package. The current version -is available from L<http://www.eyrie.org/~eagle/software/rra-c-util/>. +This module is maintained in the rra-c-util package. The current version is +available from L<http://www.eyrie.org/~eagle/software/rra-c-util/>. The C TAP Harness test driver and libraries for TAP-based C testing are available from L<http://www.eyrie.org/~eagle/software/c-tap-harness/>. diff --git a/tests/tap/perl/Test/RRA/ModuleVersion.pm b/tests/tap/perl/Test/RRA/ModuleVersion.pm new file mode 100644 index 0000000..f02877a --- /dev/null +++ b/tests/tap/perl/Test/RRA/ModuleVersion.pm @@ -0,0 +1,295 @@ +# Check Perl module versions for consistency. +# +# This module contains the common code for testing and updating Perl module +# versions for consistency within a Perl module distribution and within a +# larger package that contains both Perl modules and other code. + +package Test::RRA::ModuleVersion; + +use 5.006; +use strict; +use warnings; + +use Exporter; +use File::Find qw(find); +use Test::More; +use Test::RRA::Config qw(@MODULE_VERSION_IGNORE); + +# For Perl 5.006 compatibility. +## no critic (ClassHierarchies::ProhibitExplicitISA) + +# Declare variables that should be set in BEGIN for robustness. +our (@EXPORT_OK, @ISA, $VERSION); + +# Set $VERSION and everything export-related in a BEGIN block for robustness +# against circular module loading (not that we load any modules, but +# consistency is good). +BEGIN { + @ISA = qw(Exporter); + @EXPORT_OK = qw(test_module_versions update_module_versions); + + # This version should match the corresponding rra-c-util release, but with + # two digits for the minor version, including a leading zero if necessary, + # so that it will sort properly. + $VERSION = '5.10'; +} + +# A regular expression matching the version string for a module using the +# package syntax from Perl 5.12 and later. $1 will contain all of the line +# contents prior to the actual version string, $2 will contain the version +# itself, and $3 will contain the rest of the line. +our $REGEX_VERSION_PACKAGE = qr{ + ( # prefix ($1) + \A \s* # whitespace + package \s+ # package keyword + [\w\:\']+ \s+ # package name + ) + ( v? [\d._]+ ) # the version number itself ($2) + ( # suffix ($3) + \s* ; + ) +}xms; + +# A regular expression matching a $VERSION string in a module. $1 will +# contain all of the line contents prior to the actual version string, $2 will +# contain the version itself, and $3 will contain the rest of the line. +our $REGEX_VERSION_OLD = qr{ + ( # prefix ($1) + \A .* # any prefix, such as "our" + [\$*] # scalar or typeglob + [\w\:\']*\b # optional package name + VERSION\b # version variable + \s* = \s* # assignment + ) + [\"\']? # optional leading quote + ( v? [\d._]+ ) # the version number itself ($2) + [\"\']? # optional trailing quote + ( # suffix ($3) + \s* + ; + ) +}xms; + +# Find all the Perl modules shipped in this package, if any, and returns the +# list of file names. +# +# $dir - The root directory to search +# +# Returns: List of file names +sub _module_files { + my ($dir) = @_; + return if !-d $dir; + my @files; + my %ignore = map { $_ => 1 } @MODULE_VERSION_IGNORE; + my $wanted = sub { + if ($_ eq 'blib') { + $File::Find::prune = 1; + return; + } + if (m{ [.] pm \z }xms && !$ignore{$File::Find::name}) { + push(@files, $File::Find::name); + } + return; + }; + find($wanted, $dir); + return @files; +} + +# Given a module file, read it for the version value and return the value. +# +# $file - File to check, which should be a Perl module +# +# Returns: The version of the module +# Throws: Text exception on I/O failure or inability to find version +sub _module_version { + my ($file) = @_; + open(my $data, q{<}, $file) or die "$0: cannot open $file: $!\n"; + while (defined(my $line = <$data>)) { + if ( $line =~ $REGEX_VERSION_PACKAGE + || $line =~ $REGEX_VERSION_OLD) + { + my ($prefix, $version, $suffix) = ($1, $2, $3); + close($data) or die "$0: error reading from $file: $!\n"; + return $version; + } + } + close($data) or die "$0: error reading from $file: $!\n"; + die "$0: cannot find version number in $file\n"; +} + +# Given a module file and the new version for that module, update the version +# in that module to the new one. +# +# $file - Perl module file whose version should be updated +# $version - The new version number +# +# Returns: undef +# Throws: Text exception on I/O failure or inability to find version +sub _update_module_version { + my ($file, $version) = @_; + open(my $in, q{<}, $file) or die "$0: cannot open $file: $!\n"; + open(my $out, q{>}, "$file.new") + or die "$0: cannot create $file.new: $!\n"; + + # If the version starts with v, use it without quotes. Otherwise, quote + # it to prevent removal of trailing zeroes. + if ($version !~ m{ \A v }xms) { + $version = "'$version'"; + } + + # Scan for the version and replace it. + SCAN: + while (defined(my $line = <$in>)) { + if ( $line =~ s{ $REGEX_VERSION_PACKAGE }{$1$version$3}xms + || $line =~ s{ $REGEX_VERSION_OLD }{$1$version$3}xms) + { + print {$out} $line or die "$0: cannot write to $file.new: $!\n"; + last SCAN; + } + print {$out} $line or die "$0: cannot write to $file.new: $!\n"; + } + + # Copy the rest of the input file to the output file. + print {$out} <$in> or die "$0: cannot write to $file.new: $!\n"; + close($out) or die "$0: cannot flush $file.new: $!\n"; + close($in) or die "$0: error reading from $file: $!\n"; + + # All done. Rename the new file over top of the old file. + rename("$file.new", $file) + or die "$0: cannot rename $file.new to $file: $!\n"; + return; +} + +# Act as a test suite. Find all of the Perl modules under the provided root, +# if any, and check that the version for each module matches the version. +# Reports results with Test::More and sets up a plan based on the number of +# modules found. +# +# $root - Directory under which to look for Perl modules +# $version - The version all those modules should have +# +# Returns: undef +# Throws: Text exception on fatal errors +sub test_module_versions { + my ($root, $version) = @_; + my @modules = _module_files($root); + + # Output the plan. Skip the test if there were no modules found. + if (@modules) { + plan tests => scalar(@modules); + } else { + plan skip_all => 'No Perl modules found'; + return; + } + + # For each module, get the module version and compare. + for my $module (@modules) { + my $module_version = _module_version($module); + is($module_version, $version, "Version for $module"); + } + return; +} + +# Update the versions of all modules to the current distribution version. +# +# $root - Directory under which to look for Perl modules +# $version - The version all those modules should have +# +# Returns: undef +# Throws: Text exception on fatal errors +sub update_module_versions { + my ($root, $version) = @_; + my @modules = _module_files($root); + for my $module (@modules) { + _update_module_version($module, $version); + } + return; +} + +1; +__END__ + +=for stopwords +Allbery sublicense MERCHANTABILITY NONINFRINGEMENT rra-c-util versioning + +=head1 NAME + +Test::RRA::ModuleVersion - Check Perl module versions for consistency + +=head1 SYNOPSIS + + use Test::RRA::ModuleVersion + qw(test_module_versions update_module_versions); + + # Ensure all modules under perl/lib have a version of 3.12. + test_module_versions('perl/lib', '3.12'); + + # Update the version of those modules to 3.12. + update_module_versions('perl/lib', 3.12'); + +=head1 DESCRIPTION + +This module provides functions to test and update the versions of Perl +modules. It helps with enforcing consistency of versioning across all modules +in a Perl distribution or embedded in a larger project containing non-Perl +code. The calling script provides the version with which to be consistent +and the root directory under which modules are found. + +=head1 FUNCTIONS + +None of these functions are imported by default. The ones used by a script +should be explicitly imported. + +=over 4 + +=item test_module_versions(ROOT, VERSION) + +Tests the version of all Perl modules under ROOT to ensure they match VERSION, +reporting the results with Test::More. If the test configuration loaded by +Test::RRA::Config contains a @MODULE_VERSION_EXCLUDE variable, the module +files listed there will be ignored for this test. This function also sets up +a plan based on the number of modules, so should be the only testing function +called in a test script. + +=item update_module_versions(ROOT, VERSION) + +Update the version of all Perl modules found under ROOT to VERSION, except for +any listed in a @MODULE_VERSION_EXCLUDE variable set in the test configuration +loaded by Test::RRA::Config. + +=back + +=head1 AUTHOR + +Russ Allbery <eagle@eyrie.org> + +=head1 COPYRIGHT AND LICENSE + +Copyright 2016 Russ Allbery <eagle@eyrie.org> + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. + +=head1 SEE ALSO + +Test::More(3), Test::RRA::Config(3) + +This module is maintained in the rra-c-util package. The current version +is available from L<http://www.eyrie.org/~eagle/software/rra-c-util/>. + +=cut |