59 lines
4.0 KiB
Markdown
59 lines
4.0 KiB
Markdown
# 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.
|