Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.
Awesome Lists | Featured Topics | Projects
https://github.com/xsawyerx/test-dns

Test DNS queries and zone configuration
https://github.com/xsawyerx/test-dns
Last synced: 28 days ago
JSON representation
Test DNS queries and zone configuration
Host: GitHub
URL: https://github.com/xsawyerx/test-dns
Owner: xsawyerx
Created: 2010-01-11T11:20:32.000Z (almost 15 years ago)
Default Branch: master
Last Pushed: 2019-04-22T16:49:56.000Z (over 5 years ago)
Last Synced: 2024-10-13T11:37:13.373Z (about 1 month ago)
Language: Perl
Homepage:
Size: 82 KB
Stars: 2
Watchers: 2
Forks: 3
Open Issues: 0
Metadata Files:
- Readme: README.mkdn
- Changelog: Changes
Awesome Lists containing this project

README

        # NAME

Test::DNS - Test DNS queries and zone configuration

# VERSION

version 0.203

# SYNOPSIS

This module helps you write tests for DNS queries. You could test your domain

configuration in the world or on a specific DNS server, for example.

    use Test::DNS;

    use Test::More tests => 4;

    my $dns = Test::DNS->new();

    $dns->is_ptr( '1.2.3.4' => 'single.ptr.record.com' );

    $dns->is_ptr( '1.2.3.4' => [ 'one.ptr.record.com', 'two.ptr.record.com' ] );

    $dns->is_ns( 'google.com' => [ map "ns$_.google.com", 1 .. 4 ] );

    $dns->is_a( 'ns1.google.com' => '216.239.32.10' );

    ...

# DESCRIPTION

Test::DNS allows you to run tests which translate as DNS queries. It's simple to

use and abstracts all the difficult query checks from you. It has a built-in

tests naming scheme so you don't have to name your tests (as shown in all

the examples) even though it supports the option.

    use Test::DNS;

    use Test::More tests => 1;

    my $dns = Test::DNS->new( nameservers => [ 'my.dns.server' ] );

    $dns->is_ptr( '1.1.1.1' => 'my_new.mail.server' );

That was a complete test script that will fetch the PTR (if there is one), warns

if it's missing one (an option you can remove via the _warnings_ attribute) and

checks against the domain you gave. You could also give for each test an

arrayref of expected values. That's useful if you want to check multiple values.

For example:

    use Test::DNS;

    use Test::More tests => 1;

    my $dns = Test::DNS->new();

    $dns->is_ns( 'my.domain' => [ 'ns1.my.domain', 'ns2.my.domain' ] );

    # or

    $dns->is_ns( 'my.domain' => [ map "ns$_.my.domain", 1 .. 5 ] );

You can set the _follow\_cname_ option if your PTR returns a CNAME instead of an

A record and you want to test the A record instead of the CNAME. This happened

to me at least twice and fumbled my tests. I was expecting an A record, but got

a CNAME to an A record. This is obviously legal DNS practices, so using the

_follow\_cname_ attribute listed below, the test went with flying colors. This

is a recursive CNAME to A record function so you could handle multiple CNAME

chaining if one has such an odd case.

New in version 0.04 is the option to give a hashref as the testing values (not

including a test name as well), which makes things much easier to test if you

want to run multiple tests and don't want to write multiple lines. This helps

connect [Test::DNS](https://metacpan.org/pod/Test::DNS) with freshly-parsed data (YAML/JSON/XML/etc.).

    use Test::DNS;

    use YAML 'LoadFile';

    use Test::More tests => 2;

    my $dns = Test::DNS->new();

    # running two DNS tests in one command!

    $dns->is_ns( {

        'first.domain'  => [ map { "ns$_.first.domain"  } 1 .. 4 ],

        'second.domain' => [ map { "ns$_.second.domain" } 5, 6   ],

    } );

    my $tests = LoadFile('tests.yaml');

    $dns->is_a( $tests, delete $tests->{'name'} ); # $tests is a hashref

# EXPORT

This module is completely Object Oriented, nothing is exported.

# ATTRIBUTES

## nameservers($arrayref)

Same as in [Net::DNS](https://metacpan.org/pod/Net::DNS). Sets the nameservers, accepts an arrayref.

    my $dns = Test::DNS->new(

        'nameservers' => [ 'IP1', 'DOMAIN' ],

    );

## warnings($boolean)

Do you want to output warnings from the module (in valid TAP), such as when a

record doesn't a query result or incorrect types?

This helps avoid common misconfigurations. You should probably keep it, but if

it bugs you, you can stop it using:

    my $dns = Test::DNS->new(

        'warnings' => 0,

    );

Default: 1 (on).

## follow\_cname($boolean)

When fetching an A record of a domain, it may resolve to a CNAME instead of an A

record. That would result in a false-negative of sorts, in which you say "well,

yes, I meant the A record the CNAME record points to" but [Test::DNS](https://metacpan.org/pod/Test::DNS) doesn't

know that.

If you want want Test::DNS to follow every CNAME recursively till it reaches the

actual A record and compare **that** A record, use this option.

    my $dns = Test::DNS->new(

        'follow_cname' => 1,

    );

Default: 0 (off).

# SUBROUTINES/METHODS

## is\_a( $domain, $ips, \[$test\_name\] )

Check the A record resolving of domain or subdomain.

`$ip` can be an arrayref.

`$test_name` is not mandatory.

    $dns->is_a( 'domain' => 'IP' );

    $dns->is_a( 'domain', [ 'IP1', 'IP2' ] );

Returns false if the assertion fails.

## is\_ns( $domain, $ips, \[$test\_name\] )

Check the NS record resolving of a domain or subdomain.

`$ip` can be an arrayref.

`$test_name` is not mandatory.

    $dns->is_ns( 'domain' => 'IP' );

    $dns->is_ns( 'domain', [ 'IP1', 'IP2' ] );

Returns false if the assertion fails.

## is\_ptr( $ip, $domains, \[$test\_name\] )

Check the PTR records of an IP.

`$domains` can be an arrayref.

`$test_name` is not mandatory.

    $dns->is_ptr( 'IP' => 'ptr.records.domain' );

    $dns->is_ptr( 'IP', [ 'first.ptr.domain', 'second.ptr.domain' ] );

Returns false if the assertion fails.

## is\_mx( $domain, $domains, \[$test\_name\] )

Check the MX records of a domain.

`$domains` can be an arrayref.

`$test_name` is not mandatory.

    $dns->is_mx( 'domain' => 'mailer.domain' );

    $dns->is_ptr( 'domain', [ 'mailer1.domain', 'mailer2.domain' ] );

Returns false if the assertion fails.

## is\_cname( $domain, $domains, \[$test\_name\] )

Check the CNAME records of a domain.

`$domains` can be an arrayref.

`$test_name` is not mandatory.

    $dns->is_cname( 'domain' => 'sub.domain' );

    $dns->is_cname( 'domain', [ 'sub1.domain', 'sub2.domain' ] );

Returns false if the assertion fails.

## is\_txt( $domain, $txt, \[$test\_name\] )

Check the TXT records of a domain.

`$txt` can be an arrayref.

`$test_name` is not mandatory.

    $dns->is_txt( 'domain' => 'v=spf1 -all' );

    $dns->is_txt( 'domain', [ 'sub1.domain', 'sub2.domain' ] );

Returns false if the assertion fails.

## is\_record( $type, $input, $expected, \[$test\_name\] )

The general function all the other is\_\* functions run.

`$type` is the record type (CNAME, A, NS, PTR, MX, etc.).

`$input` is the domain or IP you're testing.

`$expected` can be an arrayref.

`$test_name` is not mandatory.

    $dns->is_record( 'CNAME', 'domain', 'sub.domain', 'test_name' );

Returns false if the assertion fails.

## BUILD

[Moose](https://metacpan.org/pod/Moose) builder method. Do not call it or override it. :)

# HASH FORMAT

The hash format option (since version 0.04) allows you to run the tests using a

single hashref with an optional parameter for the test\_name. The count is no

longer 1 (as it is with single tests), but each key/value pair represents a test

case.

    # these are 2 tests

    $dns->is_ns( {

        'first.domain'  => [ map { "ns$_.first.domain"  } 1 .. 4 ],

        'second.domain' => [ map { "ns$_.second.domain" } 5, 6   ],

    } );

    # number of tests: keys %{$tests}, test name: $tests->{'name'}

    $dns->is_a( $tests, delete $tests->{'name'} ); # $tests is a hashref

# DEPENDENCIES

[Moose](https://metacpan.org/pod/Moose)

[Net::DNS](https://metacpan.org/pod/Net::DNS)

[Test::Deep](https://metacpan.org/pod/Test::Deep)

# AUTHOR

Sawyer X, ``

# BUGS

Please report any bugs or feature requests to `bug-test-dns at rt.cpan.org`, or

through the web interface at

[http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Test-DNS](http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Test-DNS). I will be notified,

and then you'll automatically be notified of progress on your bug as I make

changes.

# SUPPORT

You can find documentation for this module with the perldoc command.

    perldoc Test::DNS

You can also look for information at:

- Github

    [http://github.com/xsawyerx/test-dns](http://github.com/xsawyerx/test-dns)

- RT: CPAN's request tracker

    [http://rt.cpan.org/NoAuth/Bugs.html?Dist=Test-DNS](http://rt.cpan.org/NoAuth/Bugs.html?Dist=Test-DNS)

- AnnoCPAN: Annotated CPAN documentation

    [http://annocpan.org/dist/Test-DNS](http://annocpan.org/dist/Test-DNS)

- CPAN Ratings

    [http://cpanratings.perl.org/d/Test-DNS](http://cpanratings.perl.org/d/Test-DNS)

- Search CPAN

    [http://search.cpan.org/dist/Test-DNS/](http://search.cpan.org/dist/Test-DNS/)

# ACKNOWLEDGEMENTS

# LICENSE AND COPYRIGHT

Copyright 2019 Sawyer X.

This program is free software; you can redistribute it and/or modify it

under the terms of either: the GNU General Public License as published

by the Free Software Foundation; or the Artistic License.

See http://dev.perl.org/licenses/ for more information.

# AUTHOR

Sawyer X 

# COPYRIGHT AND LICENSE

This software is Copyright (c) 2019 by Sawyer X.

This is free software, licensed under:

    The MIT (X11) License