| 1 | package Zonemaster::Engine::Test; | ||
| 2 | |||
| 3 | use v5.16.0; | ||
| 4 | use warnings; | ||
| 5 | |||
| 6 | use version; our $VERSION = version->declare( "v1.1.12" ); | ||
| 7 | |||
| 8 | use Readonly; | ||
| 9 | use Module::Find; | ||
| 10 | use Net::IP::XS; | ||
| 11 | use List::MoreUtils; | ||
| 12 | use Clone; | ||
| 13 | |||
| 14 | use Zonemaster::LDNS; | ||
| 15 | use Zonemaster::Engine; | ||
| 16 | use Zonemaster::Engine::Profile; | ||
| 17 | use Zonemaster::Engine::Util; | ||
| 18 | |||
| 19 | use IO::Socket::INET6; # Lazy-loads, so make sure it's here for the version logging | ||
| 20 | |||
| 21 | use File::ShareDir qw[dist_file]; | ||
| 22 | use File::Slurp qw[read_file]; | ||
| 23 | use Scalar::Util qw[blessed]; | ||
| 24 | use POSIX qw[strftime]; | ||
| 25 | |||
| 26 | =head1 NAME | ||
| 27 | |||
| 28 | Zonemaster::Engine::Test - Module implementing methods to find, load and execute all Test modules | ||
| 29 | |||
| 30 | =head1 SYNOPSIS | ||
| 31 | |||
| 32 | my @results = Zonemaster::Engine::Test->run_all_for($zone); | ||
| 33 | my @results = Zonemaster::Engine::Test->run_module('DNSSEC', $zone); | ||
| 34 | my @results = Zonemaster::Engine::Test->run_one('DNSSEC', 'dnssec01', $zone); | ||
| 35 | |||
| 36 | =head1 TEST MODULES | ||
| 37 | |||
| 38 | Test modules are defined as modules with names starting with C<Zonemaster::Engine::Test::>. | ||
| 39 | They are expected to provide at least the following class methods: | ||
| 40 | |||
| 41 | =over | ||
| 42 | |||
| 43 | =item all() | ||
| 44 | |||
| 45 | This will be given a L<Zonemaster::Engine::Zone> object as its only argument, and, after running the | ||
| 46 | Test Cases for that Test module, is expected to return a list of L<Zonemaster::Engine::Logger::Entry> objects. | ||
| 47 | This is the entry point used by the L</run_all_for()> and L</run_module()> methods of this class. | ||
| 48 | |||
| 49 | =back | ||
| 50 | |||
| 51 | =cut | ||
| 52 | |||
| 53 | =over | ||
| 54 | |||
| 55 | =item version() | ||
| 56 | |||
| 57 | This must return the version of the Test module. | ||
| 58 | |||
| 59 | =back | ||
| 60 | |||
| 61 | =cut | ||
| 62 | |||
| 63 | =over | ||
| 64 | |||
| 65 | =item metadata() | ||
| 66 | |||
| 67 | This must return a reference to a hash, the keys of which are the names of all Test Cases in | ||
| 68 | the module, and the corresponding values are references to an array containing all the message | ||
| 69 | tags that the Test Case can use in L<log entries|Zonemaster::Engine::Logger::Entry>. | ||
| 70 | |||
| 71 | =back | ||
| 72 | |||
| 73 | =cut | ||
| 74 | |||
| 75 | =over | ||
| 76 | |||
| 77 | =item tag_descriptions() | ||
| 78 | |||
| 79 | This must return a reference to a hash, the keys of which are the message tags and the corresponding values | ||
| 80 | are strings (message IDs) corresponding to user-friendly English translations of those message tags. | ||
| 81 | Keep in mind that the message ids will be used as keys to look up translations into other languages, | ||
| 82 | so think twice before editing them. | ||
| 83 | |||
| 84 | =back | ||
| 85 | |||
| 86 | =cut | ||
| 87 | |||
| 88 | my @all_test_modules; | ||
| 89 | |||
| 90 | BEGIN { | ||
| 91 | @all_test_modules = split /\n/, read_file( dist_file( 'Zonemaster-Engine', 'modules.txt' ) ); | ||
| 92 | |||
| 93 | for my $name ( @all_test_modules ) { | ||
| 94 | require sprintf q{Zonemaster/Engine/Test/%s.pm}, $name; | ||
| 95 | "Zonemaster::Engine::Test::$name"->import(); | ||
| 96 | } | ||
| 97 | } | ||
| 98 | |||
| 99 | =head1 INTERNAL METHODS | ||
| 100 | |||
| 101 | =over | ||
| 102 | |||
| 103 | =item _log_versions() | ||
| 104 | |||
| 105 | _log_versions(); | ||
| 106 | |||
| 107 | Adds logging messages regarding the current version of some modules, specifically for L<Zonemaster::Engine> and other dependency modules (e.g. L<Zonemaster::LDNS>). | ||
| 108 | |||
| 109 | =back | ||
| 110 | |||
| 111 | =cut | ||
| 112 | |||
| 113 | sub _log_versions { | ||
| 114 | info( GLOBAL_VERSION => { version => Zonemaster::Engine->VERSION } ); | ||
| 115 | |||
| 116 | info( DEPENDENCY_VERSION => { name => 'Zonemaster::LDNS', version => $Zonemaster::LDNS::VERSION } ); | ||
| 117 | info( DEPENDENCY_VERSION => { name => 'IO::Socket::INET6', version => $IO::Socket::INET6::VERSION } ); | ||
| 118 | info( DEPENDENCY_VERSION => { name => 'Module::Find', version => $Module::Find::VERSION } ); | ||
| 119 | info( DEPENDENCY_VERSION => { name => 'File::ShareDir', version => $File::ShareDir::VERSION } ); | ||
| 120 | info( DEPENDENCY_VERSION => { name => 'File::Slurp', version => $File::Slurp::VERSION } ); | ||
| 121 | info( DEPENDENCY_VERSION => { name => 'Net::IP::XS', version => $Net::IP::XS::VERSION } ); | ||
| 122 | info( DEPENDENCY_VERSION => { name => 'List::MoreUtils', version => $List::MoreUtils::VERSION } ); | ||
| 123 | info( DEPENDENCY_VERSION => { name => 'Clone', version => $Clone::VERSION } ); | ||
| 124 | info( DEPENDENCY_VERSION => { name => 'Readonly', version => $Readonly::VERSION } ); | ||
| 125 | |||
| 126 | return; | ||
| 127 | } ## end sub _log_versions | ||
| 128 | |||
| 129 | =head1 METHODS | ||
| 130 | |||
| 131 | =over | ||
| 132 | |||
| 133 | =item modules() | ||
| 134 | |||
| 135 | my @modules_array = modules(); | ||
| 136 | |||
| 137 | Returns a list of strings containing the names of all available Test modules, | ||
| 138 | based on the content of the B<share/modules.txt> file. | ||
| 139 | |||
| 140 | =back | ||
| 141 | |||
| 142 | =cut | ||
| 143 | |||
| 144 | sub modules { | ||
| 145 | return @all_test_modules; | ||
| 146 | } | ||
| 147 | |||
| 148 | =over | ||
| 149 | |||
| 150 | =item run_all_for() | ||
| 151 | |||
| 152 | my @logentry_array = run_all_for( $zone ); | ||
| 153 | |||
| 154 | Runs the L<default set of tests|/all()> of L<all Test modules found|/modules()> for the given zone. | ||
| 155 | |||
| 156 | Test modules are L<looked up and loaded|/modules()> from the | ||
| 157 | B<share/modules.txt> file, and executed in the order in which they appear in the | ||
| 158 | file. | ||
| 159 | The default set of tests (Test Cases) is specified in the L</all()> method of each Test module. They | ||
| 160 | can be individually disabled by the L<profile|Zonemaster::Engine::Profile/test_cases>. | ||
| 161 | |||
| 162 | A test module may implement a C<can_continue()> method to indicate lack of an | ||
| 163 | extremely minimal level of function for the zone (e.g., it must have a parent | ||
| 164 | domain, and it must have at least one functional name server). | ||
| 165 | If lack of such minimal function is indicated, the testing harness is aborted. | ||
| 166 | See L<Zonemaster::Engine::Test::Basic/can_continue()> for an example. | ||
| 167 | |||
| 168 | Takes a L<Zonemaster::Engine::Zone> object. | ||
| 169 | |||
| 170 | Returns a list of L<Zonemaster::Engine::Logger::Entry> objects. | ||
| 171 | |||
| 172 | =back | ||
| 173 | |||
| 174 | =cut | ||
| 175 | |||
| 176 | sub run_all_for { | ||
| 177 | my ( $class, $zone ) = @_; | ||
| 178 | my @results; | ||
| 179 | |||
| 180 | Zonemaster::Engine->start_time_now(); | ||
| 181 | push @results, info( START_TIME => { time_t => time(), string => strftime( "%F %T %z", ( localtime() ) ) } ); | ||
| 182 | push @results, info( TEST_TARGET => { zone => $zone->name->string, module => 'all' } ); | ||
| 183 | _log_versions(); | ||
| 184 | |||
| 185 | if ( not( Zonemaster::Engine::Profile->effective->get( q{net.ipv4} ) or Zonemaster::Engine::Profile->effective->get( q{net.ipv6} ) ) ) { | ||
| 186 | return info( NO_NETWORK => {} ); | ||
| 187 | } | ||
| 188 | |||
| 189 | if ( Zonemaster::Engine->can_continue() ) { | ||
| 190 | foreach my $mod ( __PACKAGE__->modules ) { | ||
| 191 | my $module = "Zonemaster::Engine::Test::$mod"; | ||
| 192 | |||
| 193 | info( MODULE_VERSION => { module => $module, version => $module->version } ); | ||
| 194 | |||
| 195 | my @module_results = eval { $module->all( $zone ) }; | ||
| 196 | push @results, @module_results; | ||
| 197 | if ( $@ ) { | ||
| 198 | my $err = $@; | ||
| 199 | if ( blessed $err and $err->isa( 'Zonemaster::Engine::Exception' ) ) { | ||
| 200 | die $err; # Utility exception, pass it on | ||
| 201 | } | ||
| 202 | else { | ||
| 203 | push @results, info( MODULE_ERROR => { module => $module, msg => "$err" } ); | ||
| 204 | } | ||
| 205 | } | ||
| 206 | |||
| 207 | info( MODULE_END => { module => $module } ); | ||
| 208 | |||
| 209 | if ( $module->can( 'can_continue' ) && !$module->can_continue( $zone, @module_results ) ) { | ||
| 210 | push @results, info( CANNOT_CONTINUE => { domain => $zone->name->string } ); | ||
| 211 | last; | ||
| 212 | } | ||
| 213 | } | ||
| 214 | } | ||
| 215 | |||
| 216 | return @results; | ||
| 217 | } ## end sub run_all_for | ||
| 218 | |||
| 219 | =over | ||
| 220 | |||
| 221 | =item run_module() | ||
| 222 | |||
| 223 | my @logentry_array = run_module( $module, $zone ); | ||
| 224 | |||
| 225 | Runs the L<default set of tests|/all()> of the given Test module for the given zone. | ||
| 226 | |||
| 227 | The Test module must be in the list of actively loaded modules (that is, | ||
| 228 | a module defined in the B<share/modules.txt> file). | ||
| 229 | The default set of tests (Test Cases) is specified in the L</all()> method of each Test module. | ||
| 230 | They can be individually disabled by the L<profile|Zonemaster::Engine::Profile/test_cases>. | ||
| 231 | |||
| 232 | Takes a string (module name) and a L<Zonemaster::Engine::Zone> object. | ||
| 233 | |||
| 234 | Returns a list of L<Zonemaster::Engine::Logger::Entry> objects. | ||
| 235 | |||
| 236 | =back | ||
| 237 | |||
| 238 | =cut | ||
| 239 | |||
| 240 | sub run_module { | ||
| 241 | my ( $class, $requested, $zone ) = @_; | ||
| 242 | my @res; | ||
| 243 | my ( $module ) = grep { lc( $requested ) eq lc( $_ ) } $class->modules; | ||
| 244 | |||
| 245 | Zonemaster::Engine->start_time_now(); | ||
| 246 | push @res, info( START_TIME => { time_t => time(), string => strftime( "%F %T %z", ( localtime() ) ) } ); | ||
| 247 | push @res, info( TEST_TARGET => { zone => $zone->name->string, module => $requested } ); | ||
| 248 | _log_versions(); | ||
| 249 | |||
| 250 | if ( not( Zonemaster::Engine::Profile->effective->get( q{net.ipv4} ) or Zonemaster::Engine::Profile->effective->get( q{net.ipv6} ) ) ) { | ||
| 251 | return info( NO_NETWORK => {} ); | ||
| 252 | } | ||
| 253 | |||
| 254 | if ( Zonemaster::Engine->can_continue() ) { | ||
| 255 | if ( $module ) { | ||
| 256 | my $m = "Zonemaster::Engine::Test::$module"; | ||
| 257 | info( MODULE_VERSION => { module => $m, version => $m->version } ); | ||
| 258 | push @res, eval { $m->all( $zone ) }; | ||
| 259 | if ( $@ ) { | ||
| 260 | my $err = $@; | ||
| 261 | if ( blessed $err and $err->isa( 'Zonemaster::Engine::Exception' ) ) { | ||
| 262 | die $err; # Utility exception, pass it on | ||
| 263 | } | ||
| 264 | else { | ||
| 265 | push @res, info( MODULE_ERROR => { module => $module, msg => "$err" } ); | ||
| 266 | } | ||
| 267 | } | ||
| 268 | info( MODULE_END => { module => $module } ); | ||
| 269 | return @res; | ||
| 270 | } | ||
| 271 | else { | ||
| 272 | info( UNKNOWN_MODULE => { module => $requested, testcase => 'all', module_list => join( ':', sort $class->modules ) } ); | ||
| 273 | } | ||
| 274 | } | ||
| 275 | else { | ||
| 276 | info( CANNOT_CONTINUE => { domain => $zone->name->string } ); | ||
| 277 | } | ||
| 278 | |||
| 279 | return; | ||
| 280 | } ## end sub run_module | ||
| 281 | |||
| 282 | =over | ||
| 283 | |||
| 284 | =item run_one() | ||
| 285 | |||
| 286 | my @logentry_array = run_one( $module, $test_case, $zone ); | ||
| 287 | |||
| 288 | Runs the given Test Case of the given Test module for the given zone. | ||
| 289 | |||
| 290 | The Test module must be in the list of actively loaded modules (that is, | ||
| 291 | a module defined in the B<share/modules.txt> file), and the Test Case | ||
| 292 | must be listed both in the L<metadata|/metadata()> of the Test module | ||
| 293 | exports and in the L<profile|Zonemaster::Engine::Profile/test_cases>. | ||
| 294 | |||
| 295 | Takes a string (module name), a string (test case name) and an array of L<Zonemaster::Engine::Zone> objects. | ||
| 296 | |||
| 297 | Returns a list of L<Zonemaster::Engine::Logger::Entry> objects. | ||
| 298 | |||
| 299 | =back | ||
| 300 | |||
| 301 | =cut | ||
| 302 | |||
| 303 | sub run_one { | ||
| 304 | my ( $class, $requested, $test, $zone ) = @_; | ||
| 305 | my @res; | ||
| 306 | my ( $module ) = grep { lc( $requested ) eq lc( $_ ) } $class->modules; | ||
| 307 | |||
| 308 | Zonemaster::Engine->start_time_now(); | ||
| 309 | push @res, info( START_TIME => { time_t => time(), string => strftime( "%F %T %z", ( localtime() ) ) } ); | ||
| 310 | push @res, info( TEST_TARGET => { zone => $zone->name->string, module => $requested, testcase => $test } ); | ||
| 311 | _log_versions(); | ||
| 312 | |||
| 313 | if ( not( Zonemaster::Engine::Profile->effective->get( q{net.ipv4} ) or Zonemaster::Engine::Profile->effective->get( q{net.ipv6} ) ) ) { | ||
| 314 | return info( NO_NETWORK => {} ); | ||
| 315 | } | ||
| 316 | |||
| 317 | if ( Zonemaster::Engine->can_continue() ) { | ||
| 318 | if ( $module ) { | ||
| 319 | my $m = "Zonemaster::Engine::Test::$module"; | ||
| 320 | if ( $m->metadata->{$test} and Zonemaster::Engine::Util::should_run_test( $test ) ) { | ||
| 321 | info( MODULE_VERSION => { module => $m, version => $m->version } ); | ||
| 322 | push @res, eval { $m->$test( $zone ) }; | ||
| 323 | if ( $@ ) { | ||
| 324 | my $err = $@; | ||
| 325 | if ( blessed $err and $err->isa( 'Zonemaster::Engine::Exception' ) ) { | ||
| 326 | die $err; # Utility exception, pass it on | ||
| 327 | } | ||
| 328 | else { | ||
| 329 | push @res, info( MODULE_ERROR => { module => $module, msg => "$err" } ); | ||
| 330 | } | ||
| 331 | } | ||
| 332 | info( MODULE_END => { module => $module } ); | ||
| 333 | return @res; | ||
| 334 | } | ||
| 335 | else { | ||
| 336 | info( UNKNOWN_METHOD => { module => $m, testcase => $test } ); | ||
| 337 | } | ||
| 338 | } | ||
| 339 | else { | ||
| 340 | info( UNKNOWN_MODULE => { module => $requested, testcase => $test, module_list => join( ':', sort $class->modules ) } ); | ||
| 341 | } | ||
| 342 | } | ||
| 343 | else { | ||
| 344 | info( CANNOT_CONTINUE => { domain => $zone->name->string } ); | ||
| 345 | } | ||
| 346 | |||
| 347 | return; | ||
| 348 | } ## end sub run_one | ||
| 349 | |||
| 350 | 1; |