TESTING.udon

:-  ~[comments+&]
;>

# Writing Unit Tests

Urbit comes with a built in system for writing tests. Like hoon files with a
certain shape go in `%/app` or `%/gen` or `%/mar`, hoon files with a certain
shape can go in `%/tests` and then are exposed to a system wide test runner.

Say you put a test suite in `%/tests/new-hoon/thr.hoon`:

```
> +ls %/tests
new-hoon/
> +ls %/tests/new-hoon
ls/hoon mp/hoon myb/hoon thr/hoon
```

You can then just run that individual test suite (and not the ones that are beside it in the `%/tests/new-hoon` directory) with:

```
> +tests /new-hoon/thr
/new-hoon/thr/test-seconds OK
/new-hoon/thr/test-partition OK
/new-hoon/thr/test-firsts OK
/new-hoon/thr/test-apply OK
```

## The test file

So what is the structure of these test files? They contain a door, with arms starting with `++test-` or `++check-`. At minimum:

```
/+  *test
|%
++  test-some-test
  (expect-eq !>(4) !>(4))
--
```

All of the utilities you need to write tests are in the tester library. Also, like other hoon files, you can stack cores for models and utility functions with only the final core being inspected for test arms.

## Some Details

So internally, how does this work?

The `+test` generator depends on each file/directory in `%/tests/` through a renderer. Each node in the filesystem tree is rendered by `%/ren/test-tree.hoon`, which calls itself recursively for subdirectories.

This means all compiling of test cases happens inside ford, which can cache work and not recompile tests whose dependencies haven't changed. At runtime, all the `+test` generator does is filter and execute tests from the tree.

I would like to get to a place where any direct scrying of the filesystem is discouraged, and almost everything flows through the functional reactive build system. This is what it is here for.

### Future distribution of hoon libraries

Implicit in having a standard way to write tests and a standard `+test` runner is the idea that all functionality on the current desk should be tested.

Let's say I'm shipping a program on Urbit and I use multiple third-party libraries. Each of those libraries should have their own test suites placed in `%/tests/`. When I `|merge` their desks into my application desk, having a standard test runner means that all their tests and all my application tests get run. If you're depending on a library, you want to make sure that the tests for your dependencies run when you test your application.