Module swarm_nl::testing_guide

A doc-only module explaining how to run core library tests.

Note: the library is compatible with both tokio and async-std runtimes, however all tests are written to use the tokio executor. Therefore, to run the tests you must specify the runtime feature flag e.g. cargo test --features=tokio-runtime.

There are two classes of tests in the core library:

• node_behaviour tests for single node setup and behaviour.
• layer_communication tests involving the synchronization between two nodes.

Node behaviour testing

These are simple unit tests that check the behaviour of a single node. To run these tests, simply run the following command:

cargo test node_ --features=tokio-runtime

Layer communication testing

In order to create tests for communication between two nodes, we used the Rust conditional compilation feature to be able to setup different nodes and test their communication. All commands for running these tests should be run with -- --nocapture to verify the expected results.

For these tests, we’ve created two test nodes: node1 and node2.

• Node 1 is setup by calling the setup_node_1 function which uses a pre-configured cryptographic keypair and the setup_core_builder_1 function to configure a default node. This keeps its identity consistent across tests.

• Node 2 is setup by calling the setup_node_2 function which creates a new node identity every time it is called. It then adds Node 1 as its bootnode and establishes a connection by dialing Node 1.

Peer dialing tests

The peer dialing tests checks if a node can dial another node by using a listening node and a dialing node. To run these tests, start the listening node by running the following command in one terminal:

cargo test dialing_peer_works --features=test-listening-node --features=tokio-runtime -- --nocapture

Then, in another terminal run the dialing node:

cargo test dialing_peer_works --features=test-dialing-node --features=tokio-runtime -- --nocapture

The application event handler will log the dialing node’s peer id and the listening node’s peer id.

Fetching tests

The fetching test checks if a node can fetch a value from another node. These tests use a server node and a client node.

To run these tests first start the server node in one terminal:

cargo test rpc_fetch_works --features=test-server-node --features=tokio-runtime -- --nocapture

And in another terminal, run the client node:

cargo test rpc_fetch_works --features=test-client-node --features=tokio-runtime -- --nocapture

Then you can check that the server node prints out a “Recvd incoming RPC:” message with the data sent by the client node.

Kademlia tests

For Kademlia tests, we have a reading node and a writing node. We use a time delay to simulate the reading node “sleeping” so as to allow the writing node to make changes to the DHT.

When the reading node “wakes up” it then tries to read the value from the DHT. If the value is what it expects, the tests passes successfully.

To run this test, run the following command in one terminal to launch the “reading” node:

cargo test kademlia_record_store_itest_works --features=test-reading-node --features=tokio-runtime -- --nocapture

And then run the following command in another terminal to launch the “writing node”:

cargo test kademlia_record_store_itest_works --features=test-writing-node --features=tokio-runtime -- --nocapture

Record providers tests

To run the providers tests, we have a reading node and a writing node.

We first run the “writing” node to store a record in the DHT. Then we run a “reading” node to fetch the list of providers of the record that’s been written.

Then we simply assert that node 1 is a provider of the record.

To run this test, first run the “writing” node:

cargo test kademlia_provider_records_itest_works --features=test-writing-node --features=tokio-runtime -- --nocapture

Then, in another terminal, run the “reading” node:

cargo test kademlia_provider_records_itest_works --features=test-reading-node --features=tokio-runtime -- --nocapture

Gossipsub tests

Join/Exit tests

For Gossipsub tests, we have a subscribe node and a query node.

When the “subscribe” node is set up, it joins a mesh network. Then node 2 is setup and connects to node 1, sleeps for a while (to allow propagtion of data from node 1) and then joins the network. After joining, it then queries the network layer for gossipping information. This information contains topics the node is currently subscribed to such as the peers that node 2 knows (which is node 1) and the network they are a part of. The peers that have been blacklisted are also returned.

In this test, we test that node 1 is a part of the mesh network that node 2 is subscribed to.

To run this test, first run the “subscribe” node:

cargo test gossipsub_join_exit_itest_works --features=test-subscribe-node --features=tokio-runtime -- --nocapture

Then, in another terminal, run the “query” node:

cargo test gossipsub_join_exit_itest_works --features=test-query-node --features=tokio-runtime -- --nocapture

Publish/Subscribe tests

For this test we have a listening node and a broadcast node. The first node is setup which joins a mesh network. Then, node 2 is setup and connects to node 1, sleeps for a few seconds (to allow propagtion of data from node 1) and then joins the network. It then joins the network that node 1 was already a part of and sends a broadcast message to every peer in the mesh network.

The indicator of the success of this test is revealed in the application’s event handler function which logs the message received from node 2.

To run this test, first run the “listening” node in one terminal:

cargo test gossipsub_message_itest_works --features=test-listening-node --features=tokio-runtime -- --nocapture

Then run the “broadcast” node in another terminal:

cargo test gossipsub_message_itest_works --features=test-broadcast-node --features=tokio-runtime -- --nocapture