Skip to content

docs(testing): document conductor test class and correct dance-test drift - #7

Open
owleyeview wants to merge 1 commit into
mainfrom
docs/sweetest-conductor-tests-and-probe-boundary
Open

docs(testing): document conductor test class and correct dance-test drift#7
owleyeview wants to merge 1 commit into
mainfrom
docs/sweetest-conductor-tests-and-probe-boundary

Conversation

@owleyeview

Copy link
Copy Markdown
Contributor

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.

…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.
@owleyeview
owleyeview requested a review from evomimic August 5, 2026 15:03

@evomimic evomimic left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants