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 projection, exact undo-group delta, dirty state, stable operator ID, committed phase
Zero-history commit	Authored projection and prior dirty state remain unchanged
Cancel or commit failure	Exact authored projection restored, no new history, prior dirty state, stable operator ID, terminal canceled/blocked phase
Blocked start	Commit closure never runs; authored state, history, and dirty state are unchanged
Preview failure	Cancel finalizer runs, authored state is restored, and helpers are removed
Preview helpers	No helper component remains after commit or cancel
Undoable commit	assert_undo_redo_round_trip restores both initial and committed semantic 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 dispatch path or production finalizer used by the input system. Do not duplicate its state transition in the test.
4. Call assert_committed, assert_canceled, or assert_blocked with the expected authored and undo deltas, then assert_status with the stable operator ID and terminal phase.
5. For helpers, call assert_no_helpers::<ToolHelper>. For undoable work, project the meaningful state through assert_undo_redo_round_trip; use assert_projection_unchanged for no-op paths.

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, preview/commit failure rollback, blocked no-op, terminal ID/phase
Palette and registered commands	Typed immediate commit versus modal preview ownership; failed CSG start terminates
Selection and scene commands	Atomic Group Selection across repeated undo/redo; grouped Reset Lighting and Project Sun history
Asset workflows	Asset/sub-asset placement; material/texture group assignment; audio/animation assignment and incompatible targets
Viewport material drop	Exact renderer slot/primitive/brush-face preview, cancel, commit, cleanup, undo, and redo
Draw Brush and CSG	Modal cancel; decomposed commit; CSG validation/read-only block, cancel, grouped commit, and deleted-brush restoration
Brush clip and element gizmo	Production finalizers, geometry round trip, Escape rollback, and helper cleanup
Terrain sculpt and paint	Multi-dab grouped commit, no-op release, commit failure rollback, cancel, clean-view interruption, and resource cleanup
Physics placement	Prerequisite block, no-op commit, exact cancel, real settle commit, multi-selection grouping, helper cleanup, undo, and redo
Transform gizmo finalization	Actual tracker finalizer, continuous multi-target grouping, no-op release, and missing-primary survivor rollback

The shared harness covers formal operators and multi-frame modal paths. Atomic inspector and history mutations that do not own ActiveOperator use focused typed history tests with equivalent semantic projection and undo/redo assertions.