From 478b98418ef4f51461b4749674ccfba6f77760f6 Mon Sep 17 00:00:00 2001 From: "[Thomas Green]" Date: Wed, 30 Aug 2023 17:47:50 +0200 Subject: [PATCH] Update after reviews Incorporate review comments Add synopsis example for each method --- docs/Implementing_Tests.pod | 18 ++-- docs/Translation.pod | 4 - lib/Zonemaster/Engine/Constants.pm | 8 +- lib/Zonemaster/Engine/Overview.pod | 4 +- lib/Zonemaster/Engine/Profile.pm | 6 +- lib/Zonemaster/Engine/Test.pm | 59 ++++++---- lib/Zonemaster/Engine/Test/Address.pm | 36 ++++--- lib/Zonemaster/Engine/Test/Basic.pm | 54 ++++++---- lib/Zonemaster/Engine/Test/Connectivity.pm | 44 +++++--- lib/Zonemaster/Engine/Test/Consistency.pm | 56 ++++++---- lib/Zonemaster/Engine/Test/DNSSEC.pm | 120 +++++++++++---------- lib/Zonemaster/Engine/Test/Delegation.pm | 67 +++++++----- lib/Zonemaster/Engine/Test/Nameserver.pm | 106 +++++++++--------- lib/Zonemaster/Engine/Test/Syntax.pm | 83 ++++++++------ lib/Zonemaster/Engine/Test/Zone.pm | 80 ++++++++------ t/util.t | 2 +- 16 files changed, 431 insertions(+), 316 deletions(-) diff --git a/docs/Implementing_Tests.pod b/docs/Implementing_Tests.pod index 00dcdf055..e9eaf0201 100644 --- a/docs/Implementing_Tests.pod +++ b/docs/Implementing_Tests.pod @@ -15,7 +15,7 @@ to the framework. =item Make as few assumptions as possible. -When the entry method in a test module is called, it can rely on only a handful of things about the testing process so far: +When the entry method in a test module is called, it can only rely on a handful of things about the testing process so far: =over @@ -35,8 +35,8 @@ The zone object it's given has nameservers. =item Favor code clarity over performance. -Strive to make the test code as easily understood as possible. Ideally, it should be possible for a person with only a basic understanding of Perl to -read the code and verify that it correctly implements the corresponding test specification. +Strive to make the test code as easily understandable as possible. Ideally, it should be possible for a person with only a basic understanding of Perl to +read the code and verify that it correctly implements the corresponding Test Case specifications. =back @@ -58,18 +58,14 @@ message, but otherwise not used. =item C This method should return a reference to a hash. The keys of this hash should be the names of the individual test methods in the module, and the -values for each key should be a reference to an array listing all the possible messages that test method can emit. +values for each key should be a reference to an array listing all the possible messages that test methods can emit. =back =head2 Test-running method(s) -The framework expects to be able to run all tests in a module by calling a class method C with a L object as the argument. -The return value from this method is expected to be a list of L objects describing the results of the tests run. The -example test module has one possible implementation of this. - -In the case where one test module wants to use a test in another, the top-level L module has a method C to request that. -This method will call the other test, if it is available and the current profile allows its execution. It's up to the caller to know what arguments -the other test needs, and what it returns. +The framework expects to be able to run all tests in a module by calling a class method L with a +L object as the argument. +The return value from this method is expected to be a list of L objects describing the results of the tests run. =cut diff --git a/docs/Translation.pod b/docs/Translation.pod index 26c78d90b..f0b9191c7 100644 --- a/docs/Translation.pod +++ b/docs/Translation.pod @@ -45,10 +45,6 @@ The format strings themselves, the comments and the line numbers of the __x calls are used by the gettext tooling when updating the PO files with new message ids and old message strings. -Every time you add, remove or modify a tag or its message id, re-run -C as described in the next section. -Make sure the message tag comments are properly added and up to date. - =head2 For Zonemaster package maintainers In order to make a new translation usable, it must be compiled to C format diff --git a/lib/Zonemaster/Engine/Constants.pm b/lib/Zonemaster/Engine/Constants.pm index 3343f18eb..3e670279c 100644 --- a/lib/Zonemaster/Engine/Constants.pm +++ b/lib/Zonemaster/Engine/Constants.pm @@ -160,7 +160,7 @@ An integer, used to define the size of the serial number space, as defined in RF An integer, used to define the EDNS0 UDP packet size in EDNS queries. -=item * C +=item * C<$UDP_COMMON_EDNS_LIMIT> =item * C<@IPV4_SPECIAL_ADDRESSES> @@ -216,11 +216,13 @@ Readonly::Array our @IPV6_SPECIAL_ADDRESSES => _extract_iana_ip_blocks($IP_VERSI =item _extract_iana_ip_blocks() + my @array = _extract_iana_ip_blocks( $ip_version ); + Internal method that is used to extract IP blocks details from IANA files for a given IP version (i.e. 4 or 6). Takes an integer (IP version). -Returns an array of hashes - the keys of which are C (L object), C (string) and C (string). +Returns a list of hashes - the keys of which are C (L object), C (string) and C (string). =back @@ -264,4 +266,4 @@ sub _extract_iana_ip_blocks { return @list; } ## end sub _extract_iana_ip_blocks -1; \ No newline at end of file +1; diff --git a/lib/Zonemaster/Engine/Overview.pod b/lib/Zonemaster/Engine/Overview.pod index 76f758781..50ca774b8 100644 --- a/lib/Zonemaster/Engine/Overview.pod +++ b/lib/Zonemaster/Engine/Overview.pod @@ -20,7 +20,7 @@ If all you want to do is run tests, you need to care about four or five modules. There are two ways that you can get the results of a test you've requested: the simple-but-inflexible way and the flexible-but-complex way. -The simple-but-inflexible way is that all the methods in L that run tests return lists of L objects. Those lists incude all the results that the writer of the test module(s) considered important enough to return by default. The advantage of this method is that it is extremely easy to use. The following is a functional (if not very useful) way to run a full test and print the results from a command-line prompt: +The simple-but-inflexible way is that all the methods in L that run tests return lists of L objects. Those lists include all the results that the writer of the test module(s) considered important enough to return by default. The advantage of this method is that it is extremely easy to use. The following is a functional (if not very useful) way to run a full test and print the results from a command-line prompt: perl -MZonemaster::Engine -E 'say "$_" for Zonemaster::Engine->new->test_zone("example.org")' @@ -49,7 +49,7 @@ If you want to develop a test module of your own, the standard set of modules se As an entry point to the "inside" of the Zonemaster framework, you want to read L and follow references from there. Of particular interest after the L class should be the L and possibly L classes. -If you do write your own test module, I would very much appreciate feedback on which parts were tricky to figure out, because I'm honestly not sure what I need to explain here. So please, if there's something that you think really needs to be written about, make an issue at L. +If you do write your own test module, I would very much appreciate feedback on which parts were tricky to figure out, because I'm honestly not sure what I need to explain here. So please, if there's something that you think really needs to be written about, create an issue at L. =head2 For developers of the Zonemaster Test Framework diff --git a/lib/Zonemaster/Engine/Profile.pm b/lib/Zonemaster/Engine/Profile.pm index 97495b433..eeb215cdf 100644 --- a/lib/Zonemaster/Engine/Profile.pm +++ b/lib/Zonemaster/Engine/Profile.pm @@ -922,7 +922,7 @@ https://github.com/zonemaster/zonemaster/blob/master/docs/specifications/tests/Z Related to the REFRESH_MINIMUM_VALUE_LOWER message tag from this test case. Default C<14400> (4 hours in seconds). -=head2 test_cases_vars04.zone.SOA_RETRY_MINIMUM_VALUE +=head2 test_cases_vars.zone04.SOA_RETRY_MINIMUM_VALUE A positive integer value. Recommended lower bound for SOA retry values (in seconds) in test case @@ -987,8 +987,4 @@ C = true has this JSON representation: Similar to the L but uses a YAML format. -=over - -=back - =cut diff --git a/lib/Zonemaster/Engine/Test.pm b/lib/Zonemaster/Engine/Test.pm index 63c2cb853..50704e475 100644 --- a/lib/Zonemaster/Engine/Test.pm +++ b/lib/Zonemaster/Engine/Test.pm @@ -82,7 +82,7 @@ tags that the Test Case can use in L and other dependency modules (e.g. L). =back @@ -136,8 +138,11 @@ sub _log_versions { =item modules() -Returns a list with the names of all available Test modules except -L (since that one is a bit special). + my @modules_array = modules(); + +Returns a list of strings containing the names of all available Test modules, with the +exception of L (since that one is a bit special), +based on the content of the B file. =back @@ -151,17 +156,23 @@ sub modules { =item run_all_for() -Runs all Tests Cases in all Test modules found. + my @logentry_array = run_all_for( $zone ); + +Runs the L of L for the given zone. -The order in which the Test modules found will be executed is not defined, -except for L that is always executed first. -If the L fail to indicate -an extremely minimal level of function (it must have a parent domain, and it must -have at least one functional name server) for the zone, no further tests will be executed. +This method always starts with the execution of the L. +If the L fail to indicate an extremely minimal +level of function for the zone (e.g., it must have a parent domain, and it must have at least one +functional name server), the testing suite is aborted. See L +for more details. +Otherwise, other Test modules are L from the B file, +and executed in the order in which they appear in the file. +The default set of tests (Test Cases) is specified in the L method of each Test module. They +can be individually disabled by the L. Takes a L object. -Returns an array of L objects. +Returns a list of L objects. =back @@ -221,13 +232,18 @@ sub run_all_for { =item run_module() -Runs all default Test Cases of the given Test module for the given zone. -The requested Test module must be in the list of actively loaded modules -(that is, not a module disabled by the current profile) + my @logentry_array = run_module( $module, $zone ); + +Runs the L of the given Test module for the given zone. + +The Test module must be in the list of actively loaded modules (that is, +a module defined in the B file). +The default set of tests (Test Cases) is specified in the L method of each Test module. +They can be individually disabled by the L. Takes a string (module name) and a L object. -Returns an array of L objects. +Returns a list of L objects. =back @@ -279,14 +295,17 @@ sub run_module { =item run_one() -Runs the given Test method of the given Test module for the given zone. -The requested Test module must be in the list of actively loaded modules -(that is, not a module disabled by the current profile), and the Test method + my @logentry_array = run_one( $module, $test_case, $zone ); + +Runs the given Test Case of the given Test module for the given zone. + +The Test module must be in the list of actively loaded modules (that is, +a module defined in the B file), and the Test Case must be listed in the L of the Test module exports. -Takes a string (module name), a string (test method name) and an array of L objects. +Takes a string (module name), a string (test case name) and an array of L objects. -Returns an array of L objects. +Returns a list of L objects. =back @@ -347,4 +366,4 @@ sub run_one { return; } ## end sub run_one -1; \ No newline at end of file +1; diff --git a/lib/Zonemaster/Engine/Test/Address.pm b/lib/Zonemaster/Engine/Test/Address.pm index 4362bd809..5666ea9b4 100644 --- a/lib/Zonemaster/Engine/Test/Address.pm +++ b/lib/Zonemaster/Engine/Test/Address.pm @@ -23,7 +23,7 @@ Zonemaster::Engine::Test::Address - Module implementing tests focused on IP addr =head1 SYNOPSIS - my @results = Zonemaster::Engine::Test::Address->all($zone); + my @results = Zonemaster::Engine::Test::Address->all( $zone ); =head1 METHODS @@ -31,12 +31,14 @@ Zonemaster::Engine::Test::Address - Module implementing tests focused on IP addr =item all() + my @logentry_array = all( $zone ); + Runs the default set of tests for that module, i.e. between L depending on the tested zone. If L passes, L is run. Takes a L object. -Returns an array of L objects. +Returns a list of L objects. =back @@ -60,6 +62,8 @@ sub all { =item metadata() + my $hash_ref = metadata(); + Returns a reference to a hash, the keys of which are the names of all Test Cases in the module, and the corresponding values are references to an array containing all the message tags that the Test Case can use in L. @@ -158,9 +162,11 @@ Readonly my %TAG_DESCRIPTIONS => ( =item tag_descriptions() + my $hash_ref = tag_descriptions(); + Used by the L. -Returns a reference to a hash, the keys of which are the message tags and the corresponding values are strings (message ids). +Returns a reference to a hash, the keys of which are the message tags and the corresponding values are strings (message IDs). =back @@ -174,6 +180,8 @@ sub tag_descriptions { =item version() + my $version_string = version(); + Returns a string containing the version of the current module. =back @@ -188,6 +196,8 @@ sub version { =item find_special_address() + my $hash_ref = find_special_address( $ip ); + Verifies if an IP address is a special (private, reserved, ...) one. Takes a L object. @@ -224,13 +234,13 @@ sub find_special_address { =item address01() -Test Case that verifies if IP addresses are not in private networks. + my @logentry_array = address01( $zone ); -See L for more details. +Runs the L. Takes a L object. -Returns a list of an array of L objects and a L object. +Returns a list of L objects. =back @@ -277,13 +287,13 @@ sub address01 { =item address02() -Test Case that verifies if reverse DNS entries exist for each name server IP addresses. + my @logentry_array = address02( $zone ); -See L for more details. +Runs the L. Takes a L object. -Returns a list of an array of L objects and a L object. +Returns a list of L objects. =back @@ -350,13 +360,13 @@ sub address02 { =item address03() -Test Case that verifies if reverse DNS entries match name server names. + my @logentry_array = address03( $zone ); -See L for more details. +Runs the L. Takes a L object. -Returns a list of an array of L objects and a L object. +Returns a list of L objects. =back @@ -430,4 +440,4 @@ sub address03 { return ( @results, info( TEST_CASE_END => { testcase => (split /::/, (caller(0))[3])[-1] } ) ); } ## end sub address03 -1; \ No newline at end of file +1; diff --git a/lib/Zonemaster/Engine/Test/Basic.pm b/lib/Zonemaster/Engine/Test/Basic.pm index b9c53d182..ce8534163 100644 --- a/lib/Zonemaster/Engine/Test/Basic.pm +++ b/lib/Zonemaster/Engine/Test/Basic.pm @@ -25,7 +25,7 @@ Zonemaster::Engine::Test::Basic - Module implementing tests focused on basic zon =head1 SYNOPSIS - my @results = Zonemaster::Engine::Test::Basic->all($zone); + my @results = Zonemaster::Engine::Test::Basic->all( $zone ); =head1 METHODS @@ -33,13 +33,15 @@ Zonemaster::Engine::Test::Basic - Module implementing tests focused on basic zon =item all() + my @logentry_array = all( $zone ); + Runs the default set of tests for that module, i.e. between L depending on the tested zone. If L passes, L is run. If L passes, L is run. If L fails, L is run. Takes a L object. -Returns an array of L objects. +Returns a list of L objects. =back @@ -88,7 +90,9 @@ sub all { =item can_continue() -Looks at the provided log entries and determines if further evaluation of the tested zone is possible. + my $bool = can_continue( $zone, @logentry_array ); + +Determines if further evaluation of the given zone is possible based on the results from the Basic Test Cases. Takes a L object and an array of L objects. @@ -115,6 +119,8 @@ sub can_continue { =item metadata() + my $hash_ref = metadata(); + Returns a reference to a hash, the keys of which are the names of all Test Cases in the module, and the corresponding values are references to an array containing all the message tags that the Test Case can use in L. @@ -330,9 +336,11 @@ Readonly my %TAG_DESCRIPTIONS => ( =item tag_descriptions() + my $hash_ref = tag_descriptions(); + Used by the L. -Returns a reference to a hash, the keys of which are the message tags and the corresponding values are strings (message ids). +Returns a reference to a hash, the keys of which are the message tags and the corresponding values are strings (message IDs). =back @@ -346,6 +354,8 @@ sub tag_descriptions { =item version() + my $version_string = version(); + Returns a string containing the version of the current module. =back @@ -362,6 +372,8 @@ sub version { =item _ip_disabled_message() + my $bool = _ip_disabled_message( $logentry_array_ref, $ns, @query_type_array ); + Checks if the IP version of a given name server is allowed to be queried. If not, it adds a logging message and returns true. Else, it returns false. Used in Test Cases in combination with L<_ip_enabled_message()>. @@ -406,12 +418,12 @@ sub _ip_disabled_message { =item _ip_enabled_message() + _ip_enabled_message( $array_ref, $ns, @query_type_array ); + Adds a logging message if the IP version of a given name server is allowed to be queried. Used in Test Cases in combination with L<_ip_disabled_message()>. -Takes a reference to an array of L objects, a L object and an array of strings. - -Returns nothing. +Takes a reference to an array of L objects, a L object and an array of strings (query type). =back @@ -449,13 +461,13 @@ sub _ip_enabled_message { =item basic00() -Test Case that checks if the domain name to be tested is valid. Not all syntax tests are done here, it "just" checks domain name total length and labels length. + my @logentry_array = basic00( $zone ); -See L for more details. +Runs the L. Takes a L object. -Returns a list of an array of L objects and a L object. +Returns a list of L objects. =back @@ -508,13 +520,13 @@ sub basic00 { =item basic01() -Test Case that checks if we can find the zone we are testing and its parent zone. + my @logentry_array = basic01( $zone ); -See L for more details. +Runs the L. Takes a L object. -Returns a list of an array of L objects and a L object. +Returns a list of L objects. =back @@ -896,14 +908,13 @@ sub basic01 { =item basic02() -Test Case that checks if the nameservers of the parent zone return NS records for the tested zone, and that at least one of -those nameservers respond sensibly to an NS query for the tested zone. + my @logentry_array = basic02( $zone ); -See L for more details. +Runs the L. Takes a L object. -Returns a list of an array of L objects and a L object. +Returns a list of L objects. =back @@ -1063,14 +1074,13 @@ sub basic02 { =item basic03() -Test Case that checks if at least one of the nameservers of the parent zone gives an useful response when sent an A query for the C label in the -tested zone (that is, if we're testing C this test will ask for A records for C). + my @logentry_array = basic03( $zone ); -See L for more details. +Runs the L. Takes a L object. -Returns a list of an array of L objects and a L object. +Returns a list of L objects. =back @@ -1119,4 +1129,4 @@ sub basic03 { return ( @results, info( TEST_CASE_END => { testcase => (split /::/, (caller(0))[3])[-1] } ) ); } ## end sub basic03 -1; \ No newline at end of file +1; diff --git a/lib/Zonemaster/Engine/Test/Connectivity.pm b/lib/Zonemaster/Engine/Test/Connectivity.pm index ce9162f83..3893e3e17 100644 --- a/lib/Zonemaster/Engine/Test/Connectivity.pm +++ b/lib/Zonemaster/Engine/Test/Connectivity.pm @@ -24,7 +24,7 @@ Zonemaster::Engine::Test::Connectivity - Module implementing tests focused on na =head1 SYNOPSIS - my @results = Zonemaster::Engine::Test::Connectivity->all($zone); + my @results = Zonemaster::Engine::Test::Connectivity->all( $zone ); =head1 METHODS @@ -32,11 +32,13 @@ Zonemaster::Engine::Test::Connectivity - Module implementing tests focused on na =item all() + my @array = all( $zone ); + Runs the default set of tests for that module, i.e. L. Takes a L object. -Returns an array of L objects. +Returns a list of L objects. =back @@ -66,6 +68,8 @@ sub all { =item metadata() + my $hash_ref = metadata(); + Returns a reference to a hash, the keys of which are the names of all Test Cases in the module, and the corresponding values are references to an array containing all the message tags that the Test Case can use in L. @@ -372,6 +376,8 @@ Readonly my %TAG_DESCRIPTIONS => ( =item tag_descriptions() + my $hash_ref = tag_descriptions(); + Used by the L. Returns a reference to a hash, the keys of which are the message tags and the corresponding values are strings (message ids). @@ -388,6 +394,8 @@ sub tag_descriptions { =item version() + my $string = version(); + Returns a string containing the version of the current module. =back @@ -404,6 +412,8 @@ sub version { =item _ip_disabled_message() + my $bool = _ip_disabled_message( $logentry_array_ref, $ns, @query_type_array ); + Checks if the IP version of a given name server is allowed to be queried. If not, it adds a logging message and returns true. Else, it returns false. Takes a reference to an array of L objects, a L object and an array of strings (query type). @@ -447,14 +457,14 @@ sub _ip_disabled_message { =item _connectivity_loop() + _connectivity_loop( $testcase_string, $zone_name, $ns_array_ref, $logentry_array_ref ); + Verifies name servers reachability. Used as an helper function for Test Cases L and L. Takes a string (test case identifier), a L object, a reference to an array of L objects and a reference to an array of L objects. -Returns nothing. - =back =cut @@ -524,13 +534,13 @@ sub _connectivity_loop { =item connectivity01() -Test Case that verifies name servers UDP port 53 reachability. + my @logentry_array = connectivity01( $zone ); -See L for more details. +Runs the L. Takes a L object. -Returns a list of an array of L objects and a L object. +Returns a list of L objects. =back @@ -568,13 +578,13 @@ sub connectivity01 { =item connectivity02() -Test Case that verifies name servers TCP port 53 reachability. + my @logentry_array = connectivity02( $zone ); -See L for more details. +Runs the L. Takes a L object. -Returns a list of an array of L objects and a L object. +Returns a list of L objects. =back @@ -595,13 +605,13 @@ sub connectivity02 { =item connectivity03() -Test Case that verifies if all name servers do not belong to the same AS. + my @logentry_array = connectivity03( $zone ); -See L for more details. +Runs the L. Takes a L object. -Returns a list of an array of L objects and a L object. +Returns a list of L objects. =back @@ -739,13 +749,13 @@ sub connectivity03 { =item connectivity04() -Test Case that verifies if name servers are not announced in the same IP prefix. + my @logentry_array = connectivity04( $zone ); -See L for more details. +Runs the L. Takes a L object. -Returns a list of an array of L objects and a L object. +Returns a list of L objects. =back @@ -839,4 +849,4 @@ sub connectivity04 { return ( @results, info( TEST_CASE_END => { testcase => (split /::/, (caller(0))[3])[-1] } ) ); } ## end sub connectivity04 -1; \ No newline at end of file +1; diff --git a/lib/Zonemaster/Engine/Test/Consistency.pm b/lib/Zonemaster/Engine/Test/Consistency.pm index 5d60077b3..8592f4e8e 100644 --- a/lib/Zonemaster/Engine/Test/Consistency.pm +++ b/lib/Zonemaster/Engine/Test/Consistency.pm @@ -24,7 +24,7 @@ Zonemaster::Engine::Test::Consistency - Module implementing tests focused on nam =head1 SYNOPSIS - my @results = Zonemaster::Engine::Test::Consistency->all($zone); + my @results = Zonemaster::Engine::Test::Consistency->all( $zone ); =head1 METHODS @@ -32,11 +32,13 @@ Zonemaster::Engine::Test::Consistency - Module implementing tests focused on nam =item all() + my @logentry_array = all( $zone ); + Runs the default set of tests for that module, i.e. L. Takes a L object. -Returns an array of L objects. +Returns a list of L objects. =back @@ -72,6 +74,8 @@ sub all { =item metadata() + my $hash_ref = metadata(); + Returns a reference to a hash, the keys of which are the names of all Test Cases in the module, and the corresponding values are references to an array containing all the message tags that the Test Case can use in L. @@ -313,6 +317,8 @@ Readonly my %TAG_DESCRIPTIONS => ( =item tag_descriptions() + my $hash_ref = tag_descriptions(); + Used by the L. Returns a reference to a hash, the keys of which are the message tags and the corresponding values are strings (message ids). @@ -329,6 +335,8 @@ sub tag_descriptions { =item version() + my $version_string = version(); + Returns a string containing the version of the current module. =back @@ -345,6 +353,8 @@ sub version { =item _ip_disabled_message() + my $bool = _ip_disabled_message( $logentry_array_ref, $ns, @query_type_array ); + Checks if the IP version of a given name server is allowed to be queried. If not, it adds a logging message and returns true. Else, it returns false. Takes a reference to an array of L objects, a L object and an array of strings (query type). @@ -388,11 +398,13 @@ sub _ip_disabled_message { =item _get_addr_rrs() + my ( $logentry, @rrs_array ) = _get_addr_rrs( $ns, $zone_name, $query_type_string ); + Queries a given name server for resource records of the given type. Used as an helper function for Test Case L. Takes a L object, a L object and a string (query type). -Returns either a L object, a list containing C, or a list containing C and an array of L objects. +Returns a L object (which could be C) and an optional list of L objects. =back @@ -427,13 +439,13 @@ sub _get_addr_rrs { =item consistency01() -Test Case that checks for consistent SOA SERIAL number across name servers. + my @logentry_array = consistency01( $zone ); -See L for more details. +Runs the L. Takes a L object. -Returns a list of an array of L objects and a L object. +Returns a list of L objects. =back @@ -521,13 +533,13 @@ sub consistency01 { =item consistency02() -Test Case that checks for consistent SOA RNAME across name servers. + my @logentry_array = consistency02( $zone ); -See L for more details. +Runs the L. Takes a L object. -Returns a list of an array of L objects and a L object. +Returns a list of L objects. =back @@ -602,13 +614,13 @@ sub consistency02 { =item consistency03() -Test Case that checks for consistent SOA time parameters (REFRESH/RETRY/EXPIRE/MINIMUM) across name servers. + my @logentry_array = consistency03( $zone ); -See L for more details. +Runs the L. Takes a L object. -Returns a list of an array of L objects and a L object. +Returns a list of L objects. =back @@ -694,13 +706,13 @@ sub consistency03 { =item consistency04() -Test Case that checks for consistent NS set across name servers. + my @logentry_array = consistency04( $zone ); -See L for more details. +Runs the L. Takes a L object. -Returns a list of an array of L objects and a L object. +Returns a list of L objects. =back @@ -770,13 +782,13 @@ sub consistency04 { =item consistency05() -Test Case that checks for consistent glue records between glue and authoritative data. + my @logentry_array = consistency05( $zone ); -See L for more details. +Runs the L. Takes a L object. -Returns a list of an array of L objects and a L object. +Returns a list of L objects. =back @@ -924,13 +936,13 @@ sub consistency05 { =item consistency06() -Test Case that checks for consistent SOA MNAME across name servers. + my @logentry_array = consistency06( $zone ); -See L for more details. +Runs the L. Takes a L object. -Returns a list of an array of L objects and a L object. +Returns a list of L objects. =back @@ -1001,4 +1013,4 @@ sub consistency06 { return ( @results, info( TEST_CASE_END => { testcase => (split /::/, (caller(0))[3])[-1] } ) ); } ## end sub consistency06 -1; \ No newline at end of file +1; diff --git a/lib/Zonemaster/Engine/Test/DNSSEC.pm b/lib/Zonemaster/Engine/Test/DNSSEC.pm index 9ecea4b3f..49c47c96d 100644 --- a/lib/Zonemaster/Engine/Test/DNSSEC.pm +++ b/lib/Zonemaster/Engine/Test/DNSSEC.pm @@ -25,7 +25,7 @@ Zonemaster::Engine::Test::DNSSEC - Module implementing tests focused on DNSSEC =head1 SYNOPSIS - my @results = Zonemaster::Engine::Test::DNSSEC->all($zone); + my @results = Zonemaster::Engine::Test::DNSSEC->all( $zone ); =cut @@ -208,12 +208,14 @@ Readonly::Hash our %LDNS_digest_algorithms_supported => ( =item all() + my @logentry_array = all( $zone ); + Runs the default set of tests for that module, i.e. between L depending on the tested zone. If L finds no DNSKEY nor DS RRs, no other test is run. If L finds a DNSKEY RR, L is run. Takes a L object. -Returns an array of L objects. +Returns a list of L objects. =back @@ -318,6 +320,8 @@ sub all { =item metadata() + my $hash_ref = metadata(); + Returns a reference to a hash, the keys of which are the names of all Test Cases in the module, and the corresponding values are references to an array containing all the message tags that the Test Case can use in L. @@ -1320,9 +1324,11 @@ Readonly my %TAG_DESCRIPTIONS => ( =item tag_descriptions() + my $hash_ref = tag_descriptions(); + Used by the L. -Returns a reference to a hash, the keys of which are the message tags and the corresponding values are strings (message ids). +Returns a reference to a hash, the keys of which are the message tags and the corresponding values are strings (message IDs). =back @@ -1336,6 +1342,8 @@ sub tag_descriptions { =item version() + my $version_string = version(); + Returns a string containing the version of the current module. =back @@ -1352,6 +1360,8 @@ sub version { =item _ip_disabled_message() + my $bool = _ip_disabled_message( $logentry_array_ref, $ns, @query_type_array ); + Checks if the IP version of a given name server is allowed to be queried. If not, it adds a logging message and returns true. Else, it returns false. Takes a reference to an array of L objects, a L object and an array of strings (query type). @@ -1397,13 +1407,13 @@ sub _ip_disabled_message { =item dnssec01() -Test Case that verifies if all DS records have digest types registered with IANA. + my @logentry_array = dnssec01( $zone ); -See L for more details. +Runs the L. Takes a L object. -Returns a list of an array of L objects and a L object. +Returns a list of L objects. =back @@ -1555,13 +1565,13 @@ sub dnssec01 { =item dnssec02() -Test Case that verifies if all DS records have a matching DNSKEY. + my @logentry_array = dnssec02( $zone ); -See L for more details. +Runs the L. Takes a L object. -Returns a list of an array of L objects and a L object. +Returns a list of L objects. =back @@ -1846,13 +1856,13 @@ sub dnssec02 { =item dnssec03() -Test Case that checks iteration counts for NSEC3. + my @logentry_array = dnssec03( $zone ); -See L for more details. +Runs the L. Takes a L object. -Returns a list of an array of L objects and a L object. +Returns a list of L objects. =back @@ -1941,13 +1951,13 @@ sub dnssec03 { =item dnssec04() -Test Case that checks the durations of the signatures for the DNSKEY and SOA RRsets. + my @logentry_array = dnssec04( $zone ); -See L for more details. +Runs the L. Takes a L object. -Returns a list of an array of L objects and a L object. +Returns a list of L objects. =back @@ -2050,13 +2060,13 @@ sub dnssec04 { =item dnssec05() -Test Case that checks DNSKEY algorithms. + my @logentry_array = dnssec05( $zone ); -See L for more details. +Runs the L. Takes a L object. -Returns a list of an array of L objects and a L object. +Returns a list of L objects. =back @@ -2142,13 +2152,13 @@ sub dnssec05 { =item dnssec06() -Test Case that checks for DNSSEC extra processing at child name servers. + my @logentry_array = dnssec06( $zone ); -See L for more details. +Runs the L. Takes a L object. -Returns a list of an array of L objects and a L object. +Returns a list of L objects. =back @@ -2193,13 +2203,13 @@ sub dnssec06 { =item dnssec07() -Test Case that checks if both DS and DNSKEY RRs are present. + my @logentry_array = dnssec07( $zone ); -See L for more details. +Runs the L. Takes a L object. -Returns a list of an array of L objects and a L object. +Returns a list of L objects. =back @@ -2268,13 +2278,13 @@ sub dnssec07 { =item dnssec08() -Test Case that checks if the DNSKEY RRset is signed. + my @logentry_array = dnssec08( $zone ); -See L for more details. +Runs the L. Takes a L object. -Returns a list of an array of L objects and a L object. +Returns a list of L objects. =back @@ -2421,13 +2431,13 @@ sub dnssec08 { =item dnssec09() -Test Case that checks if the SOA RRset is signed. + my @logentry_array = dnssec09( $zone ); -See L for more details. +Runs the L. Takes a L object. -Returns a list of an array of L objects and a L object. +Returns a list of L objects. =back @@ -2589,13 +2599,13 @@ sub dnssec09 { =item dnssec10() -Test Case that checks for the presence of either NSEC or NSEC3 RRs, with proper coverage and signatures. + my @logentry_array = dnssec10( $zone ); -See L for more details. +Runs the L. Takes a L object. -Returns a list of an array of L objects and a L object. +Returns a list of L objects. =back @@ -3114,13 +3124,13 @@ sub dnssec10 { =item dnssec11() -Test Case that checks if the delegation step from parent is properly signed. + my @logentry_array = dnssec11( $zone ); -See L for more details. +Runs the L. Takes a L object. -Returns a list of an array of L objects and a L object. +Returns a list of L objects. =back @@ -3285,13 +3295,13 @@ sub dnssec11 { =item dnssec13() -Test Case that checks if all DNSKEY algorithms are used to sign the zone. + my @logentry_array = dnssec13( $zone ); -See L for more details. +Runs the L. Takes a L object. -Returns a list of an array of L objects and a L object. +Returns a list of L objects. =back @@ -3372,13 +3382,13 @@ sub dnssec13 { =item dnssec14() -Test Case that checks for valid RSA DNSKEY key size. + my @logentry_array = dnssec14( $zone ); -See L for more details. +Runs the L. Takes a L object. -Returns a list of an array of L objects and a L object. +Returns a list of L objects. =back @@ -3462,13 +3472,13 @@ sub dnssec14 { =item dnssec15() -Test Case that checks the existence of CDS and CDNSKEY RRs. + my @logentry_array = dnssec15( $zone ); -See L for more details. +Runs the L. Takes a L object. -Returns a list of an array of L objects and a L object. +Returns a list of L objects. =back @@ -3689,13 +3699,13 @@ sub dnssec15 { =item dnssec16() -Test Case that validates CDS. + my @logentry_array = dnssec16( $zone ); -See L for more details. +Runs the L. Takes a L object. -Returns a list of an array of L objects and a L object. +Returns a list of L objects. =back @@ -3955,13 +3965,13 @@ sub dnssec16 { =item dnssec17() -Test Case that validates CDNSKEY. + my @logentry_array = dnssec17( $zone ); -See L for more details. +Runs the L. Takes a L object. -Returns a list of an array of L objects and a L object. +Returns a list of L objects. =back @@ -4224,13 +4234,13 @@ sub dnssec17 { =item dnssec18() -Test Case that validates trust from DS to CDS and CDNSKEY. + my @logentry_array = dnssec18( $zone ); -See L for more details. +Runs the L. Takes a L object. -Returns a list of an array of L objects and a L object. +Returns a list of L objects. =back @@ -4412,4 +4422,4 @@ sub dnssec18 { return ( @results, info( TEST_CASE_END => { testcase => (split /::/, (caller(0))[3])[-1] } ) ); } ## end sub dnssec18 -1; \ No newline at end of file +1; diff --git a/lib/Zonemaster/Engine/Test/Delegation.pm b/lib/Zonemaster/Engine/Test/Delegation.pm index 30eba9157..2145c48cc 100644 --- a/lib/Zonemaster/Engine/Test/Delegation.pm +++ b/lib/Zonemaster/Engine/Test/Delegation.pm @@ -27,7 +27,7 @@ Zonemaster::Engine::Test::Delegation - Module implementing tests focused on zone =head1 SYNOPSIS - my @results = Zonemaster::Engine::Test::Delegation->all($zone); + my @results = Zonemaster::Engine::Test::Delegation->all( $zone ); =head1 METHODS @@ -35,11 +35,13 @@ Zonemaster::Engine::Test::Delegation - Module implementing tests focused on zone =item all() + my @logentry_array = all( $zone ); + Runs the default set of tests for that module, i.e. L. Takes a L object. -Returns an array of L objects. +Returns a list of L objects. =back @@ -64,6 +66,8 @@ sub all { =item metadata() + my $hash_ref = metadata(); + Returns a reference to a hash, the keys of which are the names of all Test Cases in the module, and the corresponding values are references to an array containing all the message tags that the Test Case can use in L. @@ -380,9 +384,11 @@ Readonly my %TAG_DESCRIPTIONS => ( =item tag_descriptions() + my $hash_ref = tag_descriptions(); + Used by the L. -Returns a reference to a hash, the keys of which are the message tags and the corresponding values are strings (message ids). +Returns a reference to a hash, the keys of which are the message tags and the corresponding values are strings (message IDs). =back @@ -396,6 +402,8 @@ sub tag_descriptions { =item version() + my $version_string = version(); + Returns a string containing the version of the current module. =back @@ -412,6 +420,8 @@ sub version { =item _ip_disabled_message() + my $bool = _ip_disabled_message( $logentry_array_ref, $ns, @query_type_array ); + Checks if the IP version of a given name server is allowed to be queried. If not, it adds a logging message and returns true. Else, it returns false. Takes a reference to an array of L objects, a L object and an array of strings (query type). @@ -455,13 +465,14 @@ sub _ip_disabled_message { =item _max_length_name_for() + my $name_string = _max_length_name_for( $name ); + Makes up a name of maximum length in the given domain name. Used as an helper function for Test Case L. Takes a L object. Returns a string. - =back =cut @@ -486,12 +497,14 @@ sub _max_length_name_for { =item _find_dup_ns() + my @logentry_array = _find_dup_ns( %hash ); + Checks if given name servers have distinct IP addresses. Used as an helper function for Test Case L. Takes a hash - the keys of which are C, C and C, and their corresponding values are a string, a string and a reference to an array of L objects, respectively. -Returns a list of an array of L objects and a L object. +Returns a list of L objects. =back @@ -541,13 +554,13 @@ sub _find_dup_ns { =item delegation01() -Test Case that verifies if there is a mininum number of name servers. + my @logentry_array = delegation01( $zone ); -See L for more details. +Runs the L. Takes a L object. -Returns a list of an array of L objects and a L object. +Returns a list of L objects. =back @@ -676,13 +689,13 @@ sub delegation01 { =item delegation02() -Test Case that verifies if name servers have distinct IP addresses. + my @logentry_array = delegation02( $zone ); -See L for more details. +Runs the L. Takes a L object. -Returns a list of an array of L objects and a L object. +Returns a list of L objects. =back @@ -723,13 +736,13 @@ sub delegation02 { =item delegation03() -Test Case that verifies if there is no truncation on referrals. + my @logentry_array = delegation03( $zone ); -See L for more details. +Runs the L. Takes a L object. -Returns a list of an array of L objects and a L object. +Returns a list of L objects. =back @@ -791,13 +804,13 @@ sub delegation03 { =item delegation04() -Test Case that verifies if name servers are authoritative. + my @logentry_array = delegation04( $zone ); -See L for more details. +Runs the L. Takes a L object. -Returns a list of an array of L objects and a L object. +Returns a list of L objects. =back @@ -865,13 +878,13 @@ sub delegation04 { =item delegation05() -Test Case that verifies if NS RRs do not point to a CNAME alias. + my @logentry_array = delegation05( $zone ); -See L for more details. +Runs the L. Takes a L object. -Returns a list of an array of L objects and a L object. +Returns a list of L objects. =back @@ -942,13 +955,13 @@ sub delegation05 { =item delegation06() -Test Case that verifies the existence of a SOA RR. + my @logentry_array = delegation06( $zone ); -See L for more details. +Runs the L. Takes a L object. -Returns a list of an array of L objects and a L object. +Returns a list of L objects. =back @@ -998,13 +1011,13 @@ sub delegation06 { =item delegation07() -Test Case that verifies if parent's zone glue name records are present in child zone. + my @logentry_array = delegation07( $zone ); -See L for more details. +Runs the L. Takes a L object. -Returns a list of an array of L objects and a L object. +Returns a list of L objects. =back @@ -1066,4 +1079,4 @@ sub delegation07 { return ( @results, info( TEST_CASE_END => { testcase => (split /::/, (caller(0))[3])[-1] } ) ); } ## end sub delegation07 -1; \ No newline at end of file +1; diff --git a/lib/Zonemaster/Engine/Test/Nameserver.pm b/lib/Zonemaster/Engine/Test/Nameserver.pm index 6a5b66ee4..2879bcd54 100644 --- a/lib/Zonemaster/Engine/Test/Nameserver.pm +++ b/lib/Zonemaster/Engine/Test/Nameserver.pm @@ -25,9 +25,7 @@ Zonemaster::Engine::Test::Nameserver - Module implementing tests focused on the =head1 SYNOPSIS - my @results = Zonemaster::Engine::Test::Nameserver->all($zone); - -=head1 METHODS + my @results = Zonemaster::Engine::Test::Nameserver->all( $zone ); =cut @@ -37,15 +35,19 @@ Readonly my @NONEXISTENT_NAMES => qw{ xn--nameservertest.ripe.net }; +=head1 METHODS + =over =item all() + my @logentry_array = all( $zone ); + Runs the default set of tests for that module, i.e. L. Takes a L object. -Returns an array of L objects. +Returns a list of L objects. =back @@ -105,6 +107,8 @@ sub all { =item metadata() + my $hash_ref = metadata(); + Returns a reference to a hash, the keys of which are the names of all Test Cases in the module, and the corresponding values are references to an array containing all the message tags that the Test Case can use in L. @@ -535,9 +539,11 @@ Readonly my %TAG_DESCRIPTIONS => ( =item tag_descriptions() + my $hash_ref = tag_descriptions(); + Used by the L. -Returns a reference to a hash, the keys of which are the message tags and the corresponding values are strings (message ids). +Returns a reference to a hash, the keys of which are the message tags and the corresponding values are strings (message IDs). =back @@ -551,6 +557,8 @@ sub tag_descriptions { =item version() + my $version_string = version(); + Returns a string containing the version of the current module. =back @@ -567,6 +575,8 @@ sub version { =item _ip_disabled_message() + my $bool = _ip_disabled_message( $logentry_array_ref, $ns, @query_type_array ); + Checks if the IP version of a given name server is allowed to be queried. If not, it adds a logging message and returns true. Else, it returns false. Takes a reference to an array of L objects, a L object and an array of strings (query type). @@ -612,13 +622,13 @@ sub _ip_disabled_message { =item nameserver01() -Test Case that verifies if a name server is not recursive. + my @logentry_array = nameserver01( $zone ); -See L for more details. +Runs the L. Takes a L object. -Returns a list of an array of L objects and a L object. +Returns a list of L objects. =back @@ -681,13 +691,13 @@ sub nameserver01 { =item nameserver02() -Test Case that verifies EDNS0 support. + my @logentry_array = nameserver02( $zone ); -See L for more details. +Runs the L. Takes a L object. -Returns a list of an array of L objects and a L object. +Returns a list of L objects. =back @@ -784,13 +794,13 @@ sub nameserver02 { =item nameserver03() -Test Case that verifies zone transfer (AXFR) availability. + my @logentry_array = nameserver03( $zone ); -See L for more details. +Runs the L. Takes a L object. -Returns a list of an array of L objects and a L object. +Returns a list of L objects. =back @@ -831,13 +841,13 @@ sub nameserver03 { =item nameserver04() -Test Case that verifies if replies from a name server come from its expected IP address. + my @logentry_array = nameserver04( $zone ); -See L for more details. +Runs the L. Takes a L object. -Returns a list of an array of L objects and a L object. +Returns a list of L objects. =back @@ -889,13 +899,13 @@ sub nameserver04 { =item nameserver05() -Test Case that verifies behaviour on AAAA queries. + my @logentry_array = nameserver05( $zone ); -See L for more details. +Runs the L. Takes a L object. -Returns a list of an array of L objects and a L object. +Returns a list of L objects. =back @@ -992,13 +1002,13 @@ sub nameserver05 { =item nameserver06() -Test Case that verifies if a name server can be resolved to an IP address. + my @logentry_array = nameserver06( $zone ); -See L for more details. +Runs the L. Takes a L object. -Returns a list of an array of L objects and a L object. +Returns a list of L objects. =back @@ -1044,13 +1054,13 @@ sub nameserver06 { =item nameserver07() -Test Case that checks if authoritative name servers return an upward referral. + my @logentry_array = nameserver07( $zone ); -See L for more details. +Runs the L. Takes a L object. -Returns a list of an array of L objects and a L object. +Returns a list of L objects. =back @@ -1103,13 +1113,13 @@ sub nameserver07 { =item nameserver08() -Test Case that checks if authoritative name servers responses match the case of every letter in QNAME. + my @logentry_array = nameserver08( $zone ); -See L for more details. +Runs the L. Takes a L object. -Returns a list of an array of L objects and a L object. +Returns a list of L objects. =back @@ -1170,13 +1180,13 @@ sub nameserver08 { =item nameserver09() -Test Case that checks if authoritative name servers return consistent responses for equivalent names with different cases in the query. + my @logentry_array = nameserver09( $zone ); -See L for more details. +Runs the L. Takes a L object. -Returns a list of an array of L objects and a L object. +Returns a list of L objects. =back @@ -1323,13 +1333,13 @@ sub nameserver09 { =item nameserver10() -Test Case that checks if authoritative name servers respond correctly to queries with undefined EDNS VERSION. + my @logentry_array = nameserver10( $zone ); -See L for more details. +Runs the L. Takes a L object. -Returns a list of an array of L objects and a L object. +Returns a list of L objects. =back @@ -1407,13 +1417,13 @@ sub nameserver10 { =item nameserver11() -Test Case that checks if authoritative name servers responses do not include unknown EDNS OPTION-CODE. + my @logentry_array = nameserver11( $zone ); -See L for more details. +Runs the L. Takes a L object. -Returns a list of an array of L objects and a L object. +Returns a list of L objects. =back @@ -1530,13 +1540,13 @@ sub nameserver11 { =item nameserver12() -Test Case that checks if authoritative name servers responses have the "Z" bit cleared, even if set in the query. + my @logentry_array = nameserver12( $zone ); -See L for more details. +Runs the L. Takes a L object. -Returns a list of an array of L objects and a L object. +Returns a list of L objects. =back @@ -1586,13 +1596,13 @@ sub nameserver12 { =item nameserver13() -Test Case that checks for the presence of a OPT pseudo-RR in a truncated response to a EDNS query. + my @logentry_array = nameserver13( $zone ); -See L for more details. +Runs the L. Takes a L object. -Returns a list of an array of L objects and a L object. +Returns a list of L objects. =back @@ -1642,13 +1652,13 @@ sub nameserver13 { =item nameserver15() -Test Case that verifies if a name server responds to certain TXT queries in the CHAOS class, specifically about its software version. + my @logentry_array = nameserver15( $zone ); -See L for more details. +Runs the L. Takes a L object. -Returns a list of an array of L objects and a L object. +Returns a list of L objects. =back @@ -1713,4 +1723,4 @@ sub nameserver15 { return ( @results, info( TEST_CASE_END => { testcase => (split /::/, (caller(0))[3])[-1] } ) ); } ## end sub nameserver15 -1; \ No newline at end of file +1; diff --git a/lib/Zonemaster/Engine/Test/Syntax.pm b/lib/Zonemaster/Engine/Test/Syntax.pm index 949e2fb07..66e2f5d28 100644 --- a/lib/Zonemaster/Engine/Test/Syntax.pm +++ b/lib/Zonemaster/Engine/Test/Syntax.pm @@ -29,7 +29,7 @@ Zonemaster::Engine::Test::Syntax - Module implementing tests focused on validati =head1 SYNOPSIS - my @results = Zonemaster::Engine::Test::Syntax->all($zone); + my @results = Zonemaster::Engine::Test::Syntax->all( $zone ); =head1 METHODS @@ -37,12 +37,14 @@ Zonemaster::Engine::Test::Syntax - Module implementing tests focused on validati =item all() + my @logentry_array = all( $zone ); + Runs the default set of tests for that module, i.e. between L depending on the tested zone. If L passes, the remaining tests are run. Takes a L object. -Returns an array of L objects. +Returns a list of L objects. =back @@ -83,6 +85,8 @@ sub all { =item metadata() + my $hash_ref = metadata(); + Returns a reference to a hash, the keys of which are the names of all Test Cases in the module, and the corresponding values are references to an array containing all the message tags that the Test Case can use in L. @@ -357,9 +361,11 @@ Readonly my %TAG_DESCRIPTIONS => ( =item tag_descriptions() + my $hash_ref = tag_descriptions(); + Used by the L. -Returns a reference to a hash, the keys of which are the message tags and the corresponding values are strings (message ids). +Returns a reference to a hash, the keys of which are the message tags and the corresponding values are strings (message IDs). =back @@ -373,6 +379,8 @@ sub tag_descriptions { =item version() + my $version_string = version(); + Returns a string containing the version of the current module. =back @@ -389,6 +397,8 @@ sub version { =item _ip_disabled_message() + my $bool = _ip_disabled_message( $logentry_array_ref, $ns, @query_type_array ); + Checks if the IP version of a given name server is allowed to be queried. If not, it adds a logging message and returns true. Else, it returns false. Takes a reference to an array of L objects, a L object and an array of strings (query type). @@ -432,6 +442,8 @@ sub _ip_disabled_message { =item _name_has_only_legal_characters() + my $bool = _name_has_only_legal_characters( $name ); + Checks if a given name contains only allowed characters. Takes a L object. @@ -457,6 +469,8 @@ sub _name_has_only_legal_characters { =item _label_starts_with_hyphen() + my $bool = _label_starts_with_hyphen( $name ); + Checks if a given name starts with an hyphen ('-'). Takes a L object. @@ -484,6 +498,8 @@ sub _label_starts_with_hyphen { =item _label_ends_with_hyphen() + my $bool = _label_ends_with_hyphen( $name ); + Checks if a given name ends with an hyphen ('-'). Takes a L object. @@ -511,6 +527,8 @@ sub _label_ends_with_hyphen { =item _label_not_ace_has_double_hyphen_in_position_3_and_4() + my $bool = _label_not_ace_has_double_hyphen_in_position_3_and_4( $name ); + Checks if a given name does not contain a double hyphen ('--'), with the exception of 'xn--'. Takes a L object. @@ -538,6 +556,8 @@ sub _label_not_ace_has_double_hyphen_in_position_3_and_4 { =item _get_name() + my $name = _get_name( $item ); + Converts a given argument to a L object. Used as an helper function for Test Cases L to L. Takes a string (name), or a L object, or a L object. @@ -569,12 +589,14 @@ sub _get_name { =item _check_name_syntax() + my @logentry_array = _check_name_syntax( $label_prefix_string, $item ); + Checks the syntax of a given name. Makes use of L and L. Used as an helper function for Test Cases L, L and L. Takes a string (label prefix) and either a string (name), a L object, or a L object. -Returns a list of an array of L objects and a L object. +Returns a list of L objects. =back @@ -643,13 +665,13 @@ sub _check_name_syntax { =item syntax01() -Test Case that verifies if a name contains only allowed characters. + my @logentry_array = syntax01( $item ); -See L for more details. +Runs the L. Takes either a string (name), a L object or a L object. -Returns a list of an array of L objects and a L object. +Returns a list of L objects. =back @@ -685,13 +707,13 @@ sub syntax01 { =item syntax02() -Test Case that verifies if a name does not start or end with a hyphen ('-'). + my @logentry_array = syntax02( $item ); -See L for more details. +Runs the L. Takes either a string (name), a L object or a L object. -Returns a list of an array of L objects and a L object. +Returns a list of L objects. =back @@ -740,13 +762,13 @@ sub syntax02 { =item syntax03() -Test Case that verifies if a name does not contain a hyphen in 3rd and 4th position (with the exception of 'xn--'). + my @logentry_array = syntax03( $item ); -See L for more details. +Runs the L. Takes either a string (name), a L object or a L object. -Returns a list of an array of L objects and a L object. +Returns a list of L objects. =back @@ -786,14 +808,13 @@ sub syntax03 { =item syntax04() -Test Case that verifies if a name server is conform to previous syntax rules (L, L). -It also verifies if its top-level domain contains only numeric characters. + my @logentry_array = syntax04( $item ); -See L for more details. +Runs the L. Takes either a string (name), a L object or a L object. -Returns a list of an array of L objects and a L object. +Returns a list of L objects. =back @@ -814,13 +835,13 @@ sub syntax04 { =item syntax05() -Test Case that verifies if a SOA RNAME has a conform usage of at sign ('@'). + my @logentry_array = syntax05( $zone ); -See L for more details. +Runs the L. Takes a L object. -Returns a list of an array of L objects and a L object. +Returns a list of L objects. =back @@ -863,13 +884,13 @@ sub syntax05 { =item syntax06() -Test Case that verifies if a SOA RNAME is RFC822 compliant. + my @logentry_array = syntax06( $zone ); -See L for more details. +Runs the L. Takes a L object. -Returns a list of an array of L objects and a L object. +Returns a list of L objects. =back @@ -1017,14 +1038,13 @@ sub syntax06 { =item syntax07() -Test Case that verifies if SOA MNAME is conform to previous syntax rules (L, L). -It also verifies if its top-level domain contains only numeric characters. + my @logentry_array = syntax07( $zone ); -See L for more details. +Runs the L. Takes a L object. -Returns a list of an array of L objects and a L object. +Returns a list of L objects. =back @@ -1052,14 +1072,13 @@ sub syntax07 { =item syntax08() -Test Case that verifies if MX name is conform to previous syntax rules (L, L). -It also verifies if its top-level domain contains only numeric characters. + my @logentry_array = syntax08( $zone ); -See L for more details. +Runs the L. Takes a L object. -Returns a list of an array of L objects and a L object. +Returns a list of L objects. =back @@ -1084,4 +1103,4 @@ sub syntax08 { return @results; } -1; \ No newline at end of file +1; diff --git a/lib/Zonemaster/Engine/Test/Zone.pm b/lib/Zonemaster/Engine/Test/Zone.pm index 37a1bbabb..3d7b272e8 100644 --- a/lib/Zonemaster/Engine/Test/Zone.pm +++ b/lib/Zonemaster/Engine/Test/Zone.pm @@ -30,7 +30,7 @@ Zonemaster::Engine::Test::Zone - Module implementing tests focused on the DNS zo =head1 SYNOPSIS - my @results = Zonemaster::Engine::Test::Zone->all($zone); + my @results = Zonemaster::Engine::Test::Zone->all( $zone ); =head1 METHODS @@ -38,11 +38,13 @@ Zonemaster::Engine::Test::Zone - Module implementing tests focused on the DNS zo =item all() + my @logentry_array = all( $zone ); + Runs the default set of tests for that module, i.e. between L depending on the tested zone. Takes a L object. -Returns an array of L objects. +Returns a list of L objects. =back @@ -76,6 +78,8 @@ sub all { =item metadata() + my $hash_ref = metadata(); + Returns a reference to a hash, the keys of which are the names of all Test Cases in the module, and the corresponding values are references to an array containing all the message tags that the Test Case can use in L. @@ -452,9 +456,11 @@ Readonly my %TAG_DESCRIPTIONS => ( =item tag_descriptions() + my $hash_ref = tag_descriptions(); + Used by the L. -Returns a reference to a hash, the keys of which are the message tags and the corresponding values are strings (message ids). +Returns a reference to a hash, the keys of which are the message tags and the corresponding values are strings (message IDs). =back @@ -468,6 +474,8 @@ sub tag_descriptions { =item version() + my $version_string = version(); + Returns a string containing the version of the current module. =back @@ -484,6 +492,8 @@ sub version { =item _is_ip_version_disabled() + my $bool = _is_ip_version_disabled( $ns, $query_type_string ); + Checks if the IP version of a given name server is allowed to be queried. If not, it adds a logging message and returns true. Else, it returns false. Takes a L object and a string (query type). @@ -524,6 +534,8 @@ sub _is_ip_version_disabled { =item _retrieve_record_from_zone() + my $packet = _retrieve_record_from_zone( $zone, $name, $query_type_string ); + Retrieves resource records of given type for the given name from the response of the first authoritative server of the given zone that has at least one. Used as an helper function for Test Cases L to L. @@ -560,13 +572,13 @@ sub _retrieve_record_from_zone { =item zone01() -Test Case that checks if master name server in SOA is fully qualified. + my @logentry_array = zone01( $zone ); -See L for more details. +Runs the L. Takes a L object. -Returns a list of an array of L objects and a L object. +Returns a list of L objects. =back @@ -730,13 +742,13 @@ sub zone01 { =item zone02() -Test Case that verifies SOA 'refresh' minimum value. + my @logentry_array = zone02( $zone ); -See L for more details. +Runs the L. Takes a L object. -Returns a list of an array of L objects and a L object. +Returns a list of L objects. =back @@ -782,13 +794,13 @@ sub zone02 { =item zone03() -Test Case that verifies if SOA 'retry' value is lower than SOA 'refresh' value. + my @logentry_array = zone03( $zone ); -See L for more details. +Runs the L. Takes a L object. -Returns a list of an array of L objects and a L object. +Returns a list of L objects. =back @@ -833,13 +845,13 @@ sub zone03 { =item zone04() -Test Case that verifies SOA 'retry' minimum value. + my @logentry_array = zone04( $zone ); -See L for more details. +Runs the L. Takes a L object. -Returns a list of an array of L objects and a L object. +Returns a list of L objects. =back @@ -885,13 +897,13 @@ sub zone04 { =item zone05() -Test Case that verifies SOA 'expire' minimum value. + my @logentry_array = zone05( $zone ); -See L for more details. +Runs the L. Takes a L object. -Returns a list of an array of L objects and a L object. +Returns a list of L objects. =back @@ -948,13 +960,13 @@ sub zone05 { =item zone06() -Test Case that verifies SOA 'minimum' (default TTL) value. + my @logentry_array = zone06( $zone ); -See L for more details. +Runs the L. Takes a L object. -Returns a list of an array of L objects and a L object. +Returns a list of L objects. =back @@ -1011,13 +1023,13 @@ sub zone06 { =item zone07() -Test Case that checks if SOA master is not an alias (CNAME). + my @logentry_array = zone07( $zone ); -See L for more details. +Runs the L. Takes a L object. -Returns a list of an array of L objects and a L object. +Returns a list of L objects. =back @@ -1077,13 +1089,13 @@ sub zone07 { =item zone08() -Test Case that checks if MX records do not resolve to a CNAME. + my @logentry_array = zone08( $zone ); -See L for more details. +Runs the L. Takes a L object. -Returns a list of an array of L objects and a L object. +Returns a list of L objects. =back @@ -1119,13 +1131,13 @@ sub zone08 { =item zone09() -Test Case that checks if there is a target host (MX, A or AAAA) to deliver e-mail for the domain name. + my @logentry_array = zone09( $zone ); -See L for more details. +Runs the L. Takes a L object. -Returns a list of an array of L objects and a L object. +Returns a list of L objects. =back @@ -1288,13 +1300,13 @@ sub zone09 { =item zone10() -Test Case that checks if a zone return exactly one SOA record. + my @logentry_array = zone10( $zone ); -See L for more details. +Runs the L. Takes a L object. -Returns a list of an array of L objects and a L object. +Returns a list of L objects. =back @@ -1352,4 +1364,4 @@ sub zone10 { return ( @results, info( TEST_CASE_END => { testcase => (split /::/, (caller(0))[3])[-1] } ) ) } ## end sub zone10 -1; \ No newline at end of file +1; diff --git a/t/util.t b/t/util.t index bb129b831..83204d650 100644 --- a/t/util.t +++ b/t/util.t @@ -11,7 +11,7 @@ isa_ok( name( "foo.bar.com" ), 'Zonemaster::Engine::DNSName' ); my $dref = pod_extract_for( 'DNSSEC' ); isa_ok( $dref, 'HASH' ); ok( scalar( keys %$dref ) > 3, 'At least four keys' ); -like( $dref->{dnssec01}, qr/Test Case that verifies if all DS records have digest types registered with IANA/, 'Expected content.' ); +like( $dref->{dnssec01}, qr/ my \@logentry_array = dnssec01\( \$zone \);/, 'Expected content.' ); subtest 'parse_hints()' => sub { my @cases = (