From 452e0b70010459068cf3bd0aaff45ee7fdcb54a9 Mon Sep 17 00:00:00 2001
From: KernelDeimos <7225168+KernelDeimos@users.noreply.github.com>
Date: Thu, 20 Nov 2025 14:25:53 -0500
Subject: [PATCH] doc: update documentation for TestKernel

---
 src/backend/tools/README.md | 60 +++++++++++++++++++++++++++++++++++++
 1 file changed, 60 insertions(+)

diff --git a/src/backend/tools/README.md b/src/backend/tools/README.md
index 1fa891273..aadfb4781 100644
--- a/src/backend/tools/README.md
+++ b/src/backend/tools/README.md
@@ -8,6 +8,66 @@ a test iterator through all the services.
 
 The Test Kernel is ideal for running unit and integration tests against individual services, ensuring they behave correctly.
 
+### Usage
+
+```
+node src/backend/tools/test`
+```
+
+### Testing Services
+
+Implement the method `_test` on any service. When `_test` is called the "construct"
+phase has already completed (meaning `_construct` on your service has been called
+by now if you've implemented it), but the "init" phase will never happen (so _init
+is never called).
+
+> **TODO:** I want to add support for mocking `_init` for deeper testing.
+
+For example, it should look similar to this snippet:
+
+```javascript
+class ExampleService extends BaseService {
+    // ...
+    async _test ({ assert }) {
+      assert.equal('actual', 'expected', 'rule should have a description');
+    }
+}
+```
+
+Notice the parameter `assert` - this holds the TestKernel's testing API. The
+reason this is a named parameter is to leave room for future support of
+multiple testing APIs if this is ever desired or we decide to migrate
+incrementally.
+
+The last parameter to `assert.equal` is a message describing the test rule.
+The message should always be a short statement with minimal punctuation.
+
+#### TestKernel's testing API
+
+The `assert` value here is a function that also has other methods defined
+in its properties. When called directly, `assert` will run the callback you
+provide as an assertion. When no `name` parameter is specified, the callback
+itself will be printed as the name of the assertion - this is useful for
+very short expressions which are self-descriptive.
+
+```javascript
+class ExampleService extends BaseService {
+    // ...
+    async _test ({ assert }) {
+        assert(() => 1 === 2, 'one should equal two');
+        assert.equal(1, 2, 'one should equal two')
+        assert(() => 3 === 4); // prints out as: `() => 3 === 4`
+    }
+}
+```
+
+| Method         | Parameters                      | Types                                             | Description                                                                                                                       |
+|----------------|---------------------------------|---------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------|
+| `assert`       | `callback`, `name?`             | `callback: () => boolean`, `name?: string`        | Runs the callback as an assertion. If `name` is omitted, the callback's source text is used as the printed name of the assertion. |
+| `assert.equal` | `actual`, `expected`, `message` | `actual: any`, `expected: any`, `message: string` | Asserts that `actual === expected`. The final parameter is a short descriptive message for the test rule.                         |
+
+
+
 ### Test Kernel Notes
 
 1. **Logging**: