mirror of
https://github.com/urbit/shrub.git
synced 2024-12-04 23:04:24 +03:00
c8337088cb
This was causing syntax errors upon loading the web interface and sending the initial build request to Ford. This commit appears to fix that. For future `.umd` authors, see the `/web/unmark/doc/umd` file for Urbit-flavored markdown syntax.
59 lines
2.4 KiB
Plaintext
59 lines
2.4 KiB
Plaintext
:- ~[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:
|
|
|
|
```
|
|
/+ tester
|
|
|_ tester-type:tester
|
|
++ test-some-test
|
|
(expect-eq 4 4 "trivial")
|
|
--
|
|
```
|
|
|
|
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.
|
|
|