55 lines
3.0 KiB
Markdown
55 lines
3.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 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.
|