docs(testing): document conductor test class and correct dance-test drift - #7
docs(testing): document conductor test class and correct dance-test drift#7owleyeview wants to merge 1 commit into
Conversation
…rift The sweettest suite is now written in two styles, but the testing docs described only the dance DSL. Tests that assert guest execution, Integrity validation, or substrate records call zome externs directly and use none of the fixture/token/executor machinery. - Add testing/conductor-test-spec.md covering the conductor test class, the two conductor setups, the test-probe coordinator and its artifact boundary, isolated augmentation, build ordering, and the rejection-assertion helpers. - Add a routing rule to the testing strategy so authors pick a style by what layer the assertion is about, and an inverse rule (§7) in the step authoring guide for when a new step type is not the answer. Correct code references that no longer match the implementation: - HolonsContextBehavior is gone; contexts are TransactionContext obtained through a space manager's TransactionManager. HolonSpaceBehavior's quoted signature was six methods out of date. - SourceHolon/ExpectedHolon are SourceSnapshot/ExpectedSnapshot; TokenId is SnapshotId; the HolonSnapshot wrapper no longer exists. - ExpectedSnapshot.snapshot is not an Option. A Deleted expectation carries an identity-only snapshot, so "None iff Deleted" was unimplementable, and as_source() is total rather than panicking on Deleted. - FixtureHolon stores head_snapshot and last_live_snapshot, deriving state from the head. Document the last-live fallback that makes post-delete steps expressible -- previously unspecified behavior. - FixtureHolons.snapshot_to_fixture_holon is keyed by SnapshotId. - TestHolonState has SavedLookup and no Error variant. - The strategy doc still carried the pre-refactor TestReference enum, contradicting the harness spec on the same type. - DanceTestState, DanceTestExecutionState, SessionState and StagingArea no longer exist; dance calls go to the holons zome via dance_adapter carrying DanceRequestEnvelope/DanceResponseEnvelope. - DanceTestStep variants use named fields, and not every variant carries a TestReference. Document both step shapes. - Executor helpers are resolve_execution_reference and record. - Document TestCaseInit and the finalize() bracket that carries fixture transient holons into execution. Also repair garbled sentences and a broken code block in the dance test spec, fix its duplicate section 10, note that tests/tryorama holds only scaffolding, and add the strategy doc and new spec to the nav.
evomimic
left a comment
There was a problem hiding this comment.
Review findings
P1 — The “two distinct styles” routing rule excludes an existing hybrid sweettest
The strategy and new conductor spec say that sweettests are either fixture/step-based dance tests or direct-zome conductor tests, and route client-operation assertions to dance tests.
tests/sweetests/tests/commit_conflict_tests.rs is neither: it executes real client runtime commands to assert the commit response, while directly calling the test-probe zome to plant the conflicting substrate state. Its assertion is about client-visible commit lifecycle, but a fixture/step-only dance test cannot establish its prerequisite.
Document this conductor-assisted runtime style (or explicitly describe it as an exception), and include the suite in the current test-class inventory. Otherwise the routing rule will steer authors toward an impossible dance test or an inappropriate new step.
P2 — Delete semantics reintroduce the snapshot model this PR removes
In dance-test-spec.md, §10 says:
Deleted expected holons contain no snapshot
That contradicts the updated ExpectedSnapshot contract in the same PR and the harness spec: a deleted expectation retains an identity-only snapshot; only its content is not meaningful for comparison.
Replace the sentence with the corrected semantics so the dance spec does not direct implementers back to an Option-based representation.
P2 — Commit semantics still refer to the removed Error lifecycle state
In dance-test-spec.md, §7.2 says the commit adder updates a FixtureHolon to Saved or Error.
TestHolonState no longer has an Error variant, and FixtureHolon lifecycle state is derived from its head snapshot. Remove or replace this stale failure path with the actual failed-commit behavior.
The sweettest suite is now written in two styles, but the testing docs described only the dance DSL. Tests that assert guest execution, Integrity validation, or substrate records call zome externs directly and use none of the fixture/token/executor machinery.
Correct code references that no longer match the implementation:
Also repair garbled sentences and a broken code block in the dance test spec, fix its duplicate section 10, note that tests/tryorama holds only scaffolding, and add the strategy doc and new spec to the nav.