dnslink-test

A language independent test harness for DNSLink implementations such as dnslink-std/js or dnslink-std/go.

• Installation
• Usage
  • Built-in DNS server

Installation

The tests are written in javascript and published through npm. This means for the execution of the tests Node.js is required.

You can run the tests "on-the-fly" using $ npx @dnslink/test or install them permanently using npm i @dnslink/test -g and then run it using $ dnslink-test.

Usage

To use this harness you need to prepare an executable, lets call it my-impl.

1. my-impl needs to be able to process command line arguments. The first argument for my-impl is a domain name.
2. Using the domain name as input, my-impl needs to output a JSON formatted object to stdout.
3. The output needs to have a found object containing all the DNSLink entries found for a domain.
4. Any found DNSLink entry needs to be returned in the found, like: { "links": { "foo": "bar" } }, if redirects happen with deep linking, the path property needs to be set like ..."path": [{ "pathname": "/dir/name", "search": { "foo": ["bar"] }}]
5. Now you can run tests using dnslink-test -- my-impl and it will show whether or not your implementation passes.
6. Optionally, your implementation may support standard log messages and/or codes for debugging why a DNSLink entry can not found. To enable this you need to also return a log object that contains all the log entries and run the tests with the --enable log flag: $ dnslink-test --enable log -- my-impl.
7. While developing you can use --skip or --only to disable/enable specific tests in order to make development more comfortable.

The list of rules that an implementation needs to cover is defined in ./integration-tests.js.

Built-in DNS server

dnslink-test comes automatically with a DNS server that is run on the localhost's UDP and TCP ports, as well as a DNS-over-HTTPS compatible endpoint (thought it is a regular HTTP endpoint).

The implementation tested receives a second argument which contains a JSON object. Looking like this:

{
  "udp": 2345,
  "tcp": 2346,
  "doh": 2347,
  "flags": {}
}

The udp, tpc and doh numbers are ports on which the local server are listening for the duration of the tests. They contain the DNS TXT entries for all known domains.

Note: The flags objects contains any flags that you may have passed in.

One can also run the DNS server in a standalone mode (for debug, or in custom CI setups):

$ dnslink-test --server-only
{
  "udp": 49953,
  "tcp": 37755,
  "doh": 39427
}

License

Published under dual-license: MIT OR Apache-2.0