#tor #arti #async #testing


Testing mock support for tor-rtcomapt

22 releases (11 breaking)

new 0.11.0 Oct 31, 2023
0.9.1 Sep 5, 2023
0.8.2 Jun 30, 2023
0.7.2 Mar 31, 2023
0.0.0 Jun 24, 2021

#214 in Asynchronous

Download history 224/week @ 2023-07-17 176/week @ 2023-07-24 329/week @ 2023-07-31 196/week @ 2023-08-07 248/week @ 2023-08-14 201/week @ 2023-08-21 203/week @ 2023-08-28 404/week @ 2023-09-04 154/week @ 2023-09-11 233/week @ 2023-09-18 163/week @ 2023-09-25 290/week @ 2023-10-02 204/week @ 2023-10-09 289/week @ 2023-10-16 295/week @ 2023-10-23 409/week @ 2023-10-30

1,212 downloads per month
Used in 20 crates (7 directly)




Support for mocking with tor-rtcompat asynchronous runtimes.


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 only be used for writing tests.

The principal entrypoint for writing tests is MockRuntime, particularly test_with_various.

It supports mocking the passage of time (via SimpleMockTimeProvider and MockExecutor), and impersonating the internet (via MockNetRuntime).

Comprehensive example

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

With tor-rtmock you can test this function, replacing the internet, and the passage of time. The test runs instantly, without actually blocking, even though it tests a timeout. And it tests the function against your mocked server, without making any actual network connections.

use tor_rtcompat::{Runtime, SleepProviderExt as _n};
use std::{io, net::{IpAddr, SocketAddr}, time::Duration};
use futures::{channel::oneshot, io::{AsyncReadExt as _, AsyncWriteExt as _}, poll};
use std::io::ErrorKind;
use tor_rtmock::{MockRuntime, /*MockNetRuntime,*/ net::MockNetwork};
use tor_rtcompat::{TcpProvider as _, TcpListener as _};

// Code to be tested:

/// Connects to `addr`, says hello, and returns whatever the server sent back
async fn converse(runtime: impl Runtime, addr: &SocketAddr) -> io::Result<Vec<u8>> {
   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?;
       let mut response = vec![];
       conn.read_to_end(&mut response).await?;

// In test module:

MockRuntime::test_with_various(|rt| async move {
    // The provided `rt` has an empty fake network.
    // We wrap it up with views onto a nonempty one we're using for the test:
    let fake_internet = MockNetwork::new();

    // Make a view that pretends we're at the server address
    let sip: IpAddr = "".parse().unwrap();
    let srt = fake_internet.builder().add_address(sip).runtime(rt.clone());

    // Make a view that pretends we're at the client address
    let cip: IpAddr = "".parse().unwrap();
    let crt = fake_internet.builder().add_address(cip).runtime(rt.clone());

    // Helper to spawn a task to execute `converse` and report its results
    // Returns a oneshot::Receiver that becomes ready when `converse` has returned
    let spawn_test = |saddr| {
        let (ret_tx, ret_rx) = oneshot::channel();
        let crt = crt.clone();
        rt.spawn_identified("function under test", async move {
            let ret = converse(crt, &saddr).await;

    eprintln!("First test.  Nothing is listening.");
    let saddr = SocketAddr::new(sip, 1);
    let ret = spawn_test(saddr).await.unwrap();
    assert_eq!(ret.unwrap_err().kind(), ErrorKind::ConnectionRefused);

    eprintln!("Second test.  Listening, but no-one picks up the phone: timeout.");
    let saddr = SocketAddr::new(sip, 2);
    let listener = srt.listen(&saddr).await.unwrap();
    let mut ret_fut = spawn_test(saddr);
    rt.progress_until_stalled().await; // let it run as far as it can get
    assert!(ret_fut.try_recv().unwrap().is_none()); // it hasn't completed right away
    assert!(poll!(&mut ret_fut).is_pending()); // alternative check, works with any future
    rt.advance_by(Duration::from_secs(4)).await; // run for 4 seconds, < timeout
    assert!(ret_fut.try_recv().unwrap().is_none()); // it still hasn't completed
    rt.advance_by(Duration::from_secs(1)).await; // run for 1 more, reaching timeout
    let ret = ret_fut.try_recv().unwrap().unwrap();
    assert_eq!(ret.unwrap_err().kind(), ErrorKind::TimedOut);

    eprintln!("Third test.  Working.");
    let saddr = SocketAddr::new(sip, 3);
    let listener = srt.listen(&saddr).await.unwrap();
    let mut ret_fut = spawn_test(saddr);
    let (mut conn, caddr) = listener.accept().await.unwrap();
    eprintln!("listener accepted from {caddr:?}");
    assert_eq!(caddr.ip(), cip);
    let expect = b"Hello world!\r\n";
    let mut output = vec![b'X'; expect.len()];
    conn.read_exact(&mut output).await.unwrap();
    eprintln!("listener received {output:?}");
    assert_eq!(output, expect);
    let reply_data = b"reply data";
    let ret = ret_fut.await.unwrap();
    assert_eq!(ret.unwrap(), reply_data);

License: MIT OR Apache-2.0


~239K SLoC