Blacksite/docs/editor/operator-regression-testing.md

Operator Regression Testing

Blacksite editor operators and modal tools must preserve the authored scene across preview, commit, cancellation, validation failure, and undo/redo. Tests share operators::test_harness::OperatorInvariantHarness so a new tool proves the same contract instead of inventing local assertions.

Required invariants

Every production operator test must cover the paths it exposes:

Path	Required proof
Commit	Expected authored entity delta, exact undo-group delta, dirty state, committed phase
Cancel or commit failure	No authored entity delta, no new history, prior dirty state, canceled phase
Blocked start	Commit closure never runs; authored state, history, and dirty state are unchanged
Preview helpers	No helper component remains after commit or cancel
Undoable commit	assert_undo_redo_round_trip restores both initial and committed projections
Continuous edit	The entire interaction creates one history command, not one per frame or target

The harness intentionally fails with the invariant name in the assertion message. Tests may add domain assertions, but should not replace these shared lifecycle checks.

Adding a tool test

1. Build a minimal World with ActiveOperator, EditorHistory, and SceneIo. Add tool-specific selection/resources and SelectedEntity when history helpers update selection.
2. Capture OperatorInvariantHarness immediately before starting the operation.
3. Run the real operator entry point or the same production commit/cancel function used by its input system.
4. Call assert_committed, assert_canceled, or assert_blocked with the expected authored and undo deltas.
5. For helpers, call assert_no_helpers::<ToolHelper>. For undoable work, project the meaningful state through assert_undo_redo_round_trip.

Do not satisfy a lifecycle test by constructing an EditorCommand and checking only its label. The test must mutate a world and prove restoration.

Current coverage

Workflow	Coverage
Generic EditorOperator	Commit cleanup, commit failure rollback, blocked no-op
Asset placement	Commit, dirty state, single undo, authored spawn round trip
Sub-asset placement	Missing dependency commit failure leaves no side effects
Texture/material assignment	Multi-actor grouped undo; missing material failure; empty-selection block
Draw Brush	Full modal-state cancel; decomposed multi-brush grouped commit and round trip
Brush CSG	Pending-preview cancel; merge commit/deletion grouped round trip
Brush clip and element gizmo	Clip grouped geometry round trip; Escape rollback and helper cleanup
Transform gizmo finalization	Multi-target continuous edit grouped into one undo command

Terrain strokes and physics-settle sessions are roadmap tools, not current production operators. Their implementation tickets must add harness fixtures before those tools can pass their own exit gates; Gitea issue BS-JD-502 remains the umbrella until that coverage exists.