https://github.com/dnslink-std/test

Internal test harness for DNSLink implementations
https://github.com/dnslink-std/test

dnslink integration-test standard

Last synced: 3 months ago
JSON representation

Internal test harness for DNSLink implementations

• Host: GitHub
• URL: https://github.com/dnslink-std/test
• Owner: dnslink-std
• License: other
• Created: 2021-06-02T03:47:18.000Z (over 3 years ago)
• Default Branch: main
• Last Pushed: 2022-06-03T07:39:43.000Z (over 2 years ago)
• Last Synced: 2024-04-29T17:49:39.877Z (9 months ago)
• Topics: dnslink, integration-test, standard
• Language: JavaScript
• Homepage:
• Size: 116 KB
• Stars: 3
• Watchers: 1
• Forks: 1
• Open Issues: 1
• Metadata Files:
  • Readme: README.md
  • License: LICENSE

Awesome Lists containing this project

README

        
# dnslink-test

A language independent test harness for DNSLink implementations such as [dnslink-std/js](https://github.com/dnslink-std/js/) or [dnslink-std/go](https://github.com/dnslink-std/go/).

- [Installation](#installation)

- [Usage](#usage)

  - [Built-in DNS server](#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`](./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:

```json

{

  "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): 

```console

$ dnslink-test --server-only

{

  "udp": 49953,

  "tcp": 37755,

  "doh": 39427

}

```

## License

Published under dual-license: [MIT OR Apache-2.0](./LICENSE)