write & run unit tests in the namespace. display the results alongside relevant documentation.
what?
“doctest” is a set of hawk templates for structuring unit tests and documentation.
features
1) the interface will warn you when your tests or documentation are not up to the standards.
2) test results can be displayed with readable styling and defined in the same namespace tree as the related documentation.
3) hawk files run real hoon code. so the test results are “live” and easy to keep up to date:
just re-run the hawk tree with a pulse timer.
4) once encoded in hawk, the tests and documentation can be made public to the web - thus enforcing more public accountability for testing quality.
why?
tests are a great form of documentation.
each test is an oportunity to teach something.
mixing prose and live-code in a hawk document is a much richer communication medium than either code or prose alone.
bundling tests with documentation puts more eyes on the tests, resulting in better tests.
the person who writes the tests should probably also be the person who writes the documentation, so bundling them explicitly makes organizational sense.
writing tests is a great way to think deeply about your interfaces, so having an integrated testing environment will lead to better interfaces.
what about more complicated tests?
testing something like a vane interface might require some setup and asynchronicity.
i think threads are a good way to test such things, and hawk files are good at handling threads.