arti/tor-rtmock
Nick Mathewson 2102d2e2b5 Add noop_method_call warning.
This would have saved ahf and me a lot of confusion in debugging a
situation where we were cloning a reference of a type that didn't
implement Clone.
2021-05-27 14:32:29 -04:00
..
src Add noop_method_call warning. 2021-05-27 14:32:29 -04:00
tests Split mocking parts of rtcompat into new rtmock crate. 2021-05-03 09:10:33 -04:00
Cargo.toml Give every Cargo.toml a repository field 2021-05-19 14:56:09 -04:00
README.md Add automatically generated README.md files to each crate. 2021-05-25 15:41:23 -04:00

README.md

tor-rtmock

Support for mocking with tor-rtcompat asynchronous runtimes.

Overview

The tor-rtcompat crate defines a Runtime trait that represents most of the common functionality of . This crate provides mock implementations that override a Runtime, in whole or in part, for testing purposes.

This crate is part of Arti, a project to implement Tor in Rust. It is used to write tests for higher-level crates in Arti that rely on asynchronous runtimes.

This crate should should only be used for writing tests.

Currently, we support mocking the passage of time (via [MockSleepRuntime]), and impersonating the internet (via [MockNetRuntime]).

Examples

Suppose you've written a function that relies on making a connection to the network and possibly timing out:

use tor_rtcompat::{Runtime,SleepProviderExt};
use std::{net::SocketAddr, io::Result, time::Duration, io::Error};
use futures::io::AsyncWriteExt;

async fn say_hi(runtime: impl Runtime, addr: &SocketAddr) -> Result<()> {
   let delay = Duration::new(5,0);
   runtime.timeout(delay, async {
      let mut conn = runtime.connect(addr).await?;
      conn.write_all(b"Hello world!\r\n").await?;
      conn.close().await?;
      Ok::<_,Error>(())
   }).await??;
   Ok(())
}

But how should you test this function?

You might try connecting to a well-known website to test the connection case, and to a well-known black hole to test the timeout case... but that's a bit undesirable. Your tests might be running in a container with no internet access; and even if they aren't, it isn't so great for your tests to rely on the actual state of the internet. Similarly, if you make your timeout too long, your tests might block for a long time; but if your timeout is too short, the tests might fail on a slow machine or on a slow network.

Or, you could solve both of these problems by using tor-rtmock to replace the internet and the passage of time. (Here we're only replacing the internet.)

#
use tor_rtmock::{MockSleepRuntime,MockNetRuntime,net::MockNetwork};
use tor_rtcompat::{TcpProvider,TcpListener};
use futures::io::AsyncReadExt;

let addr1 = "198.51.100.7".parse().unwrap();
let addr2 = "198.51.100.99".parse().unwrap();
let sockaddr = "198.51.100.99:101".parse().unwrap();

tor_rtcompat::test_with_runtime(|rt| async {
   // Make a runtime that pretends that we are at the first address...
   let fake_internet = MockNetwork::new();
   let rt1 = fake_internet.builder().add_address(addr1).runtime(rt.clone());
   // ...and one that pretends we're listening at the second address.
   let rt2 = fake_internet.builder().add_address(addr2).runtime(rt);
   let listener = rt2.listen(&sockaddr).await.unwrap();

   // Now we can test our function!
   let (result1,output) = futures::join!(
          say_hi(rt1, &sockaddr),
          async {
              let (mut conn,addr) = listener.accept().await.unwrap();
              assert_eq!(addr.ip(), addr1);
              let mut output = Vec::new();
              conn.read_to_end(&mut output).await.unwrap();
              output
          });

   assert!(result1.is_ok());
   assert_eq!(&output[..], b"Hello world!\r\n");
});

(TODO: Add an example for the timeout case.)

License: MIT OR Apache-2.0