github.com/StackExchange/dnscontrol/v4@v4.11.0/documentation/integration-tests.md (about)

     1  ### Integration Tests
     2  
     3  This is a simple framework for testing dns providers by making real requests.
     4  
     5  There is a sequence of changes that are defined in the test file that are run against your chosen provider.
     6  
     7  For each step, it will run the config once and expect changes. It will run it again and expect no changes. This should give us much higher confidence that providers will work in real life.
     8  
     9  ## Configuration
    10  
    11  `providers.json` should have an object for each provider type under test. This is identical to the json expected in `creds.json` for dnscontrol, except it also has a "domain" field specified for the domain to test. The domain does not even need to be registered for most providers. Note that `providers.json` expects environment variables to be specified with the relevant info.
    12  
    13  ## Running a test
    14  
    15  1. The integration tests need a test domain to run on. All the records of this domain will be deleted!
    16  2. Define all environment variables expected for the provider you wish to run.
    17  3. run `cd integrationTest && go test -v -provider $NAME` where $NAME is the name of the provider you wish to run.
    18  
    19  Example:
    20  
    21  ```shell
    22  egrep ROUTE53 providers.json
    23  ```
    24  
    25  ```text
    26      "KeyId": "$ROUTE53_KEY_ID",
    27      "SecretKey": "$ROUTE53_KEY",
    28      "domain": "$ROUTE53_DOMAIN"
    29  ```
    30  
    31  ```shell
    32  export ROUTE53_KEY_ID="redacted"
    33  export ROUTE53_KEY="also redacted"
    34  export ROUTE53_DOMAIN="testdomain.tld"
    35  ```
    36  
    37  ```shell
    38  cd integrationTest              # NOTE: Not needed if already in that subdirectory
    39  go test -v -verbose -provider ROUTE53
    40  ```
    41  
    42  The `-start` and `-end` flags allow you to run just a portion of the tests.
    43  
    44  ```shell
    45  go test -v -verbose -provider ROUTE53 -start 16
    46  go test -v -verbose -provider ROUTE53 -end 5
    47  go test -v -verbose -provider ROUTE53 -start 16 -end 20
    48  ```
    49  
    50  The actual tests are in the file `integrationTest/integration_test.go`.  The
    51  tests are in a little language which can be used to describe just about any
    52  interaction with the API.  Look for the comment `START HERE` or the line
    53  `func makeTests` for instructions.
    54  
    55  
    56  {% hint style="warning" %}
    57  **WARNING**: THE RECORDS IN THE TEST DOMAIN WILL BE DELETED.  Only use
    58  a domain that is not used in production. Some providers have a way
    59  to run tests on domains that aren't registered (often a test
    60  environment or a side-effect of the company not being a registrar).
    61  In other cases we use a domain we squat on, or we register a domain
    62  called `dnscontrol-$provider.com` just for testing.
    63  {% endhint %}
    64  
    65  {% hint style="info" %}
    66  **ProTip**: If you run these tests frequently (and we hope you do), you
    67  should create a script that you can `source` to set these
    68  variables. Be careful not to check this script into Git since it
    69  contains credentials.
    70  {% endhint %}