docs: testing guide for module authors

docs/building-modules.md

@@ -1,4 +1,4 @@
-# Building modules
+# Building Modules
 
 A Station Module is a long-running process that's performing jobs like network probes, content
 delivery, and computation.
@@ -10,7 +10,7 @@ In the long run, we want Zinnia to be aligned with the Web APIs as much as feasi
 
 For the shorter term, we are going to take shortcuts to deliver a useful platform quickly.
 
-## Getting started
+## Getting Started
 
 If you haven't done so, then install `zinnia` CLI per
 [our instructions](../cli/README.md#installation).
@@ -30,7 +30,13 @@ Hello universe!
 
 See [example modules](../examples) for more advanced examples.
 
-## Modules
+## Table of Contents
+
+- [Importing JavaScript Modules](#importing-javascript-modules)
+- [Platform APIs](#platform-apis)
+- [Testing Guide](#testing-guide)
+
+## Importing JavaScript Modules
 
 Zinnia supports ES Modules (also known as
 [JavaScript Modules](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Modules)).
@@ -77,6 +83,11 @@ import * as code from "../../other/code.js";
 
 ## Platform APIs
 
+- [Standard JavaScript APIs](#standard-javascript-apis)
+- [Web APIs](#web-apis)
+- [Unsupported Web APIs](#unsupported-web-apis)
+- [libp2p](#libp2p)
+
 ### Standard JavaScript APIs
 
 Zinnia provides all standard JavaScript APIs, you can find the full list in
@@ -187,7 +198,36 @@ individual methods in [MDN web docs](https://developer.mozilla.org/en-US/docs/We
 
 - [DOMException](https://developer.mozilla.org/en-US/docs/Web/API/DOMException)
 
-### libp2p
+### Unsupported Web APIs
+
+#### File API
+
+Tracking issue: n/a
+
+- [Blob](https://developer.mozilla.org/en-US/docs/Web/API/blob)
+- [File](https://developer.mozilla.org/en-US/docs/Web/API/File)
+- [FileReader](https://developer.mozilla.org/en-US/docs/Web/API/FileReader)
+
+#### Service Workers & Web Workers
+
+Tracking issue: n/a
+
+- [CacheStorage](https://developer.mozilla.org/en-US/docs/Web/API/CacheStorage)
+- [Cache](https://developer.mozilla.org/en-US/docs/Web/API/Cache)
+- [Worker](https://developer.mozilla.org/en-US/docs/Web/API/Worker)
+- [caches](https://developer.mozilla.org/en-US/docs/Web/API/caches)
+
+#### WebSockets Standard
+
+Tracking issue: n/a
+
+- [WebSocket](https://developer.mozilla.org/en-US/docs/Web/API/WebSocket)
+
+#### Other
+
+- `XMLHttpRequest` Standard
+
+## libp2p
 
 Zinnia comes with a built-in libp2p node based on
 [rust-libp2p](https://github.com/libp2p/rust-libp2p). The node is shared by all Station Modules
@@ -289,44 +329,65 @@ Report that a single job was completed.
 
 Call this function every time your module completes a job. It's ok to call it frequently.
 
-<!--
-UNSUPPORTED APIs
--->
+## Testing Guide
 
-## Unsupported Web APIs
+Zinnia provides lightweight tooling for writing and running automated tests.
 
-#### File API
+- [Test Runner](#test-runner)
+- [Assertions](#assertions)
 
-Tracking issue: n/a
+### Test Runner
 
-- [Blob](https://developer.mozilla.org/en-US/docs/Web/API/blob)
-- [File](https://developer.mozilla.org/en-US/docs/Web/API/File)
-- [FileReader](https://developer.mozilla.org/en-US/docs/Web/API/FileReader)
+The built-in test runner is intentionally minimalistic for now. Let us know what features you would
+like us to add!
 
-#### Service Workers & Web Workers
+Example test file (e.g. `test/smoke.test.js`):
 
-Tracking issue: n/a
+```js
+import { test } from "zinnia:test";
 
-- [CacheStorage](https://developer.mozilla.org/en-US/docs/Web/API/CacheStorage)
-- [Cache](https://developer.mozilla.org/en-US/docs/Web/API/Cache)
-- [Worker](https://developer.mozilla.org/en-US/docs/Web/API/Worker)
-- [caches](https://developer.mozilla.org/en-US/docs/Web/API/caches)
+test("a sync test", () => {
+  // run your test
+  // throw an error when an assertion fails
+});
 
-#### WebSockets Standard
+test("a test can be async too", async () => {
+  // run some async code
+  // throw an error when an assertion fails
+});
+```
 
-Tracking issue: n/a
+Notes:
 
-- [WebSocket](https://developer.mozilla.org/en-US/docs/Web/API/WebSocket)
+- Calling `test()` DOES NOT run the test immediately. It adds the test to the queue.
+- Therefore, you should never `await` the value returned by `test()` .
+- The tests are executed sequentially in the order in which they were registered via `test()` calls.
 
-#### Other
+You can run the tests using `zinnia run`:
 
-- `XMLHttpRequest` Standard
+```bash
+❯ zinnia run test/smoke.test.js
+```
 
-## Assertions
+To run a test suite consisting of multiple test files, create a top-level test suite file and import
+individual test files.
 
-Zinnia bundles assertion functions provided by Deno's `std/testing/asserts.ts`.
+For example, you can create `test-all.js` in your project root:
 
-Example:
+```js
+import "./test/smoke.test.js";
+import "./test/user.test.js";
+// and so on
+```
+
+### Assertions
+
+You can use most assertion libraries that are compatible with browsers and Deno, for example
+[Chai](https://www.chaijs.com).
+
+Zinnia provides a built-in assertion library based on Deno's `std/testing/asserts.ts`.
+
+Example usage:
 
 ```js
 import { assertEquals } from "zinnia:assert";