Document & refactor Stelline a bit

[tertsdiepraam]

No description provided.

[ximon18]

I think this needs to be worded differently. A query is "sent" (sort of, more on that in a minute) but I'm not sure if it goes to the "tested program", that depends on what you mean by "tested program".

Stelline tests consists of several parts:

• A test recipe/replay script (stored in /test-data/ as .rpl files)
• A test that defines:
  • A runner.
  • A client.
  • A network connection.
  • (optional) A server.

Stelline tests broadly fall into two categories, real client with mock responses, or real/simple client with real responses, or even a mix of both (see https://github.com/NLnetLabs/domain/blob/xfr/test-data/server/secondary_zone_lifecycle.rpl).

Examples of real clients with mock responses can be seen in the /tests/net-client*.rs tests. Each test creates a real client and connects it to the Stelline mock response "server" by using a Stelline mock Dgram connection that allows the Stelline runner to capture the requests and reply using responses from the .rpl script. These tests use the "do_client_simple()" "runner".

Examples of real clients with real responses can be seen in src/net/server/tests/integration.rs. The server_tests() fn runs tests using test-data/server/*.rpl recipe/replay scripts using the "do_client()" "runner". This runner dispatches requests using a factory supplied by the test function. The factory helps it select the right kind of client for the test, e.g. UDP, TCP, using a TSIG key or not, etc. This runner also has logic for handling large mutli-response answers such as occur with XFR. The test also does much more setup work than the client only tests as it sets up a real server that will receive requests via a mock network connection and respond to them (based on how it was configured by the test based on the .rpl file config block). The server tests and "do_client" runer also support mixing real and mock servers which is just a matter of using the right mock network connection (a connection to a real server, or a connection to the Stelline mock response "server"). Some of these tests also use a different "simple" client (defined in src/stelline/simple_dgram_client.rs) which is a real client but interferes as little as possible with the request and the response so that Stelline tests can test additional things.

So, back to the start. Does a request get "sent". Yes as far as the client code but no actual network activiity occurs, not even localhost. And what is the "tested program"? It's either the Stelline framework itself which receives the request and replies per the .rpl script, or it's a real server created by the test function.

So, your comment isn't wrong, but I'm wondering how and where we can capture these details, and how to hint in higher level docs at these different use cases and supporting logic.