Zonemaster/Engine/Test.pm untested

filter: Statementstmt 0.0% 0 / 150 Branchbran 0.0% 0 / 32 Conditioncond 0.0% 0 / 24 MC/DCmcdc 0.0% 0 / 16 Subroutinesub 0.0% 0 / 24 Podpod 0.0% 0 / 6 totaltotal 0.0% 0 / 252 CC 17 SCAR 31.5
CC
17
Cov
0%
run_one
56.0
run_all_for
42.0
run_module
42.0
CRAP 23.4
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;