1  # Shadow-based integration test
 2  
 3  This is an integration test for arti that uses the
 4  [shadow](https://shadow.github.io/) simulator. It creates a simulation of a
 5  small Tor network, uses the `arti` client to perform some transfers across this
 6  simulated network, and validates that the transfers succeeded.
 7  
 8  ## Running locally
 9  
10  To run locally, you'll need to install shadow itself somewhere on our `PATH`,
11  following [shadow's installation
12  instructions](https://shadow.github.io/docs/guide/supported_platforms.html).
13  
14  Next you'll need to install executables that will run inside the simulation, in the
15  locations where [`shadow.yaml`](./shadow.yaml) expects to find them.
16  
17  * Ensure [`tgen`](https://github.com/shadow/tgen/) is on your PATH.
18  
19  * Ensure [`tor`](https://gitlab.torproject.org/tpo/core/tor) is on your PATH.
20    Typically you can install it using your host system's package manager.
21  
22  * Ensure [`obfs4proxy`](https://gitlab.com/yawning/obfs4) is located at
23    `/usr/bin/obfs4proxy`. Typically you can install it using your host system's
24    package manager.
25  
26  * Build an `arti` client with some extra features enabled such that the binary
27    ends up at `../../target/x86_64-unknown-linux-gnu/debug/arti-extra`. In the CI
28    this done in job `rust-latest-arti-extra-features` with the invocation:
29  
30    ```shell
31    $ cargo build --locked --verbose \
32        --target x86_64-unknown-linux-gnu \
33        -p arti -p tor-circmgr \
34        --bin arti \
35        --features full,experimental-api,arti-client/keymgr,tor-circmgr/ntor_v3,onion-service-service
36    $ mv target/x86_64-unknown-linux-gnu/debug/arti target/x86_64-unknown-linux-gnu/debug/arti-extra
37    ```
38  
39  * Build a "vanilla" `arti` client so that the binary is at:
40    `../../target/x86_64-unknown-linux-gnu/debug/arti`. In the CI this is done in
41    job `rust-latest` with the invocation:
42  
43    ```shell
44    $ cargo build --locked --verbose --target x86_64-unknown-linux-gnu -p arti
45    ```
46  
47  Once those are installed, you can invoke the [`run`](./run) script from
48  this directory.