Skip to content

Commit 1ea75db

Browse files
committed
docs: document the clusterd test driver in the testing guide
The headless clusterd test driver (#37008) is a new system-test framework for targeted compute experiments, but guide-testing.md only listed sqllogictest, testdrive, and pgtest. Add a subsection pointing at the scripts, the run commands, and the design doc. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_012QXMSBfD9bXzJaqs52URyV
1 parent 6d4c0fb commit 1ea75db

1 file changed

Lines changed: 34 additions & 0 deletions

File tree

doc/developer/guide-testing.md

Lines changed: 34 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -222,6 +222,40 @@ documented at the [pgtest crate][pgtest-docs].
222222

223223
[pgtest-docs]: https://dev.materialize.com/api/rust/mz_pgtest/index.html
224224

225+
### clusterd test driver
226+
227+
The frameworks above all drive Materialize as a whole, through the SQL layer.
228+
That makes them awkward for targeted compute experiments: as noted under [What
229+
kind of tests should I write?](#what-kind-of-tests-should-i-write), unit testing
230+
functions in the middle of the [compute](/src/compute) stack is "an exercise in
231+
frustration", but going through SQL means going through the catalog, the
232+
optimizer, and the controller's timestamp and read-hold machinery.
233+
234+
The clusterd test driver
235+
([`src/clusterd-test-driver`](/src/clusterd-test-driver)) fills that gap. It is a
236+
headless frontend that speaks the cluster protocol to a real `clusterd`
237+
directly, with no `environmentd`, so a test controls the exact persist state,
238+
the exact commands the replica receives, and the exact timestamps. Tests are
239+
text scripts where each command is followed by a `----` block holding its
240+
expected output; that block is the assertion, and `REWRITE=1` regenerates it in
241+
place (like datadriven). The scripts live in
242+
[`test/clusterd-test-driver/scripts`](/test/clusterd-test-driver/scripts).
243+
244+
Run the scenarios against a real `clusterd` under Docker:
245+
246+
```shell
247+
$ bin/mzcompose --find clusterd-test-driver run default
248+
```
249+
250+
or run the same scripts on the host, without Docker images:
251+
252+
```shell
253+
$ bin/pyactivate test/clusterd-test-driver/run-local.py
254+
```
255+
256+
See the [design doc](design/20260612_headless_clusterd_test_driver.md) for the
257+
full command vocabulary and architecture.
258+
225259
## Long-running tests
226260

227261
These are still a work in progress. The beginning of the orchestration has

0 commit comments

Comments
 (0)