@@ -4,6 +4,8 @@ weight = 10
44template = "doc.html"
55+++
66
7+## Structure
8+
79The `%base` desk includes a `-test` thread which can run unit tests you've
810written. A test is a Hoon file which produces a `core`. The `-test` thread will
911look for any arms in the core whose name begin with `test-`, e.g:
@@ -53,9 +55,15 @@ expressions in the test file itself. To do that, you'd just import the file with
5355You're free to do any compositions, import types, etc, as long as the file
5456ultimately produces a `core` with `test-*` arms.
5557
58+## Running
59+
5660The `-test` thread takes a `(list path)` in the Dojo, where each path is a path
57−to a test file. The `path` must include the full path prefix
58−(`/[ship]/[desk]/[case]`). The conventional location for tests is a `/tests`
61+to a test file. The `path` _must_ include the full path prefix
62+(`/[ship]/[desk]/[case]`). The `path` _may_ omit the mark, since a `.hoon` file
63+is assumed. The `path` _may_ include the name of a test arm after the filename.
64+In that case, only the specified test arm will be run.
65+
66+The conventional location for tests is a `/tests`
5967directory in the root of a desk.
6068
6169The output of the `-test` thread will note which arms were tested and whether
@@ -68,7 +76,7 @@ they succeeded. It will also include:
6876Here's an example of running the tests for the `naive.hoon` library:
6977
7078```
71−> -test ~[%/tests/lib/naive/hoon]
79+> -test %/tests/lib/naive ~
7280built /tests/lib/naive/hoon
7381> test-zod-spawn-to-zero: took 81359µs
7482OK /lib/naive/test-zod-spawn-to-zero
@@ -84,6 +92,19 @@ OK /lib/naive/test-address-padding
8492ok=%.y
8593```
8694
95+Here's an example of running just a single test for `naive.hoon`, the
96+`++test-deposit` arm:
97+
98+```
99+> -test %/tests/lib/naive/test-deposit ~
100+built /tests/lib/naive/hoon
101+> test-deposit: took ms/45.542
102+OK /lib/naive/test-deposit
103+ok=%.y
104+```
105+
106+## More info
107+
87108A good reference example is the test file for the `/lib/number-to-words.hoon`
88109library, located in `/tests/lib/number-to-words.hoon`. Note that the `/tests`
89110directory is not typically included in standard pills. If you want to have a