heddle

Test lab · version 0.8.0

Test lab

9 scenarios that run the library and check what each call did. They are deterministic and need no network and no model. A commit id is a hash of content, so a replay has to reproduce every id. A scenario is a script that writes a recording by running it: a list of calls on named histories. The recording goes through JSON and is replayed on fresh histories. Each step becomes a turn: what it returned, where HEAD went, how many objects it wrote and how long it took. The assertions read that trace. Two more checks compare the replay with the script's own run, turn by turn, and compare the end states.

Every run is kept. The record is a Heddle linear history: one commit per check-in. bun run lab --record commits to reports/lab/record.heddle.json, which is tracked in the repository and printed into this page. Runs made here are committed to a second history, saved in this browser. The charts read a heddle/stream built from both, one channel per metric. The scrubber under them is mountHistory on this browser's record: drag it back and the charts show the record as it was.

The lab runs in your browser. It needs JavaScript, which has not run.

What it checks

The lab's scenarios
ScenarioWhat it pins
Undo, redo and the cut tail
linear
A linear history: undo and redo write nothing, the ends refuse, and a commit after an undo parks the commits that were ahead under undone/1.
Branches, checkout and a detached HEAD
graph
A graph history: branch, switch, commit on a detached HEAD, walk checkouts back with undoCheckout, and keep commits no branch reaches.
Merge, conflict and revert
merge
Different parts merge cleanly. The same part changed twice is a conflict that commits nothing until a strategy settles it. A revert undoes one commit as a new one.
Restore one part
restore
restore brings one part back from an older commit as a new commit. Nothing outside the part changes, and a part the source never had is removed.
Bundles and live sync
sync
Three copies and a relay. Bundles carry only what the other side lacks, a diverged copy is parked and merged, and two writes to one register are settled by the last writer on every copy.
Save, load and change the model
storage
A saved history comes back with its position. Linear always opens as graph. Graph opens as linear only while it is one line. A bundle that was tampered with is refused.
Ids from content, storage from change
identity
Two histories that never met give the same content the same ids. Messages and labels are outside the id. A commit writes only the nodes on the path it changed.
Latency under load
load
150 commits on a 300-item state, then undo, redo and jumps. Every call is timed against a budget, and every commit is checked to write only the path it changed.
Recordings replay exactly
replays
Every scenario's recording, sent through JSON and replayed twice, makes the same turns and ends on the same commit ids. A recording with one value changed diverges at that turn, and the comparison names it.

The load scenario's budgets: set p95 ≤ 60 ms, undo p95 ≤ 40 ms, verify ≤ 4000 ms, and at most 4 objects written per commit on a 300-item state. The time budgets are generous on purpose. They catch a change in complexity, such as a commit that starts to cost ten times more, not the noise between two machines. The object count is exact and does not depend on the machine.

Run it elsewhere

The page, the command line, the test suite and a script all run the same scenarios from heddle/lab.

Ways to run the lab
WhereHowWhat you get
This pageRun allChecks, traces and a check-in kept in this browser.
Command linebun run lab [ids] [--json] [--out file]A line per scenario and latency per call. Exits 1 on a failure. --out appends the check-in to an NDJSON file.
The recordbun run lab --recordCommits the check-in to reports/lab/record.heddle.json, a Heddle history tracked in the repository, and verifies it. The next site build prints it into this page.
Test suitebun test test/lab.test.tsEvery scenario passes, two runs make the same trace, recordings replay, check-ins round-trip.
Benchmarkbun run bench [items] [commits] [grouped]The Performance section's numbers, on Bun.
A script or an agentwindow.heddleLab.runAll()The check-in as JSON, from this page in any browser.

heddle/lab

The lab ships with the package, so an app can record its own Heddle calls and replay them in its tests.

heddle/lab exports
ExportDoes
new Script(title)Writes a recording by doing it: step(on, op, args, expect?) runs the call on the script's own histories and records it, and returns the turn, so the script can read real commit ids as it goes. open, commit, set and remove are shorthands.
replay(recording, options?)Runs a recording on fresh histories. Returns { turns, state, world }: one turn per step, each history's head, tree, commit count and verify result, and the histories themselves.
compareTurns(expected, actual)The first turn where two runs differ in anything but time, as { turn, field, expected, actual }, or null.
stepper(recording)A replay that advances one step per next() call.
SCENARIOS, runScenario(id, options?), runAll(options?)The default scenarios and their runner. A result has pass, checks, ms, turns, recording and state.
buildCheckin({ results, env, source? })The durable record of a run. checkinsToNdjson, parseCheckins and compareCheckins read, write and compare them.
historyCheckins(kv?, { key?, cap? })A store that keeps check-ins in a Heddle linear history: append is a commit, history() is the history, at(target) reads the record as of any commit. With kv it is saved after every change.
metricsStream(checkins), streamSeries(stream, channel, label, unit)The check-ins as a heddle/stream, one channel per metric and one tick per check-in, and a channel as a chart series.
bench({ items?, commits?, shape? })The benchmark of the Performance section: timings per call and the sizes of the saved history, a snapshot copy and a delta bundle.

window.heddleLab

On this page, for a script or an agent driving a browser. Every call returns plain JSON.

window.heddleLab
CallReturns
scenarios()[{ id, title, about }] for every scenario.
run(id)A promise of that scenario's result: pass, checks, turns, recording, state.
runAll()A promise of the check-in for a run of every scenario.
result(id)The last result of a scenario on this page, or null.
replay(recording){ turns, state } for any heddle.lab.recording.
checkins()The repository's check-ins and this browser's, oldest first.
record()Both records: commits, head commit id and check-in count of the browser's history and of the repository's.
bench({ items?, commits?, shape? })The benchmark's result.

Formats

heddle.lab.recording, version 1

{ format, version, title, steps }. A step is { on, op, args, expect? }: the history it runs on, one of 21 calls, JSON arguments, and the error code it is meant to raise, if any.

heddle.lab.checkin, version 1

One run: id, time, source, environment, scenarios passed, every check, turns, flagged turns, the latency of each call (n, p50, p95, max) and each scenario's end-state hash. One check-in per line is NDJSON.

Not here: thrd.it's lab also has a server API and MCP tools. Heddle is a library with a static site, so its lab has neither.