Developer Docs
Boundary Snap Acceptance Matrix
Executable boundary-snap acceptance criteria, verification commands, CI artifacts, and remaining physical-device checks.
Automated acceptance for issue #280
This maps the issue’s acceptance criteria to executable checks. Synthetic fixtures and injected Qt events are not physical-device or real-image acceptance. The implementation and measurement contract are documented in Selection Boundary Snap.
Run and retain evidence
Build through the repository’s normal build/test scripts. After building tests:
ctest --test-dir build -L boundary-snap-acceptance --output-on-failure
On Windows, first prepend %QT_PATH%\bin to PATH as described in the developer build instructions. scripts/run-tests.bat handles Qt DLL setup for the full run.
The label covers seven suites, including RegionSelector_BoundarySnapMetrics. The metrics suite runs the Qt offscreen backend and writes build/boundary-snap-metrics.json. The existing macOS, Windows and Ubuntu 22.04 CI jobs execute these tests and upload that JSON alongside their JUnit and CTest logs. A workflow definition alone is not evidence of a passing platform run; inspect the artifact for the exact commit.
Metrics include build type, Qt version, CPU model/architecture, OS, backend, source and logical selection dimensions, DPR, p50/p95, hits, fallbacks, incorrect results, source conversion time/storage sharing, controller/source storage sizes, and whole-process peak RSS. p95_target_met evaluates the 4 ms target but does not determine the test exit code: slow or contended CI hosts still have to return either the correct crop or the unmodified raw rectangle. Each scenario must first produce an exact hit with the deadline disabled (preflight_correct). Thus an implementation that always falls back cannot pass. A failed preflight, incorrect crop/fallback behavior, invalid arguments and report-write failures return nonzero. Peak RSS includes Qt and the source image; it is not incremental cache usage or GPU memory. Windows uses the documented process memory API; Unix hosts use getrusage. Missing metadata remains explicitly unavailable.
For Release measurements outside CTest:
./scripts/build-release.sh
cmake --build release --config Release --target RegionSelector_BoundarySnapBenchmark
ctest --test-dir release -C Release -R '^RegionSelector_BoundarySnapMetrics$' --output-on-failure
On Windows use scripts\build-release.bat for the first command and prepend %QT_PATH%\bin to PATH before the CTest command. The app build script prepares release/ but only builds SnapTray, so the explicit benchmark target build is required. CTest locates the executable on every platform and writes release/boundary-snap-metrics.json. No threshold settings are persisted. The production query budget stays at 4 ms; a per-query zero budget provides deterministic coverage of timeout fallback and lock clearing without sleeping or relying on scheduler load.
Core and geometry matrix
| Issue criterion | Automated check | What the assertion establishes |
|---|---|---|
| Horizontal/vertical hard edges; uniform/no-edge areas | Detection_BoundarySnapIndex::hardEdges |
Exact RGB mean and support, both axes and four source formats; adjacent flat columns rejected |
| Single pixel and short line; span-external contrast | supportAndSpan |
Sparse support rejected; same line accepted only in its occupied span |
| Threshold boundaries; correct mean-of-distance scoring | supportThresholdBoundary, meanDistanceIsNotMeanSquaredDistance |
54% rejected, 55% accepted; squared-distance substitution would fail |
| Low contrast, antialiasing, gradient/shadow, text-like strokes, table grid | contrastAndTexture, antialiasedEdgesAndGrid |
Controlled pixel fixtures with known edge positions; not real font/photo recognition |
| Empty/tiny/oversized input, invalid span, alpha and storage ownership | invalidAndAlpha, hardEdges |
Safe rejection, transparent RGB ignored through premultiplication, QImage copy-on-write independence |
| Multiple candidates, distance/strength/support/coordinate ordering | RegionSelector_BoundarySnap::rankingAndJitter, tieAndConstraints |
Nearer edge wins; strength then support breaks ties; exact ties choose lower coordinate |
| Eight handles, fixed opposite sides, four DPRs | handlesAndDpr |
32 cases at odd coordinates, each final physical crop equals target, only moving edges report guides |
| Both corner axes use the raw span | cornerQueriesUseRawSpans |
A fixture that fails if X is committed before evaluating Y |
| Minimum size, screen bounds, aspect ratio | tieAndConstraints, existing RegionSelector_SelectionStateManager cases |
Illegal transforms fall back, fixed sides stay fixed; existing eight-handle bounds and ratio tests stay active |
| Rounded far screen edge | roundedScreenEdge |
400 px at 150%, 1366 px at 125%, 2560 px at 150/175% and 3840 px at 225% retain snapping while the orthogonal span is clamped to the image |
| Nonrepresentable physical boundary | unrepresentableEdges |
Fractional/Retina edges absent from the integer crop mapping never produce a hit |
| Light/dark card fixtures | lightAndDarkCards |
Eight synthetic theme/DPR cases land on exact known crop edges |
| Hysteresis, leaving radius, invalidated span | hysteresisAndSourceReplacement, rankingAndJitter |
Lock retention and exit; zero candidate switches for the scripted near-edge jitter trace |
| Source/DPR replacement | sourceReplacementChangesScaleAndLock |
Old physical lock is not reused with a different capture scale |
| Timeout/resource fallback | timeoutFallsBackAndDropsLocks, invalidSourcesAndBudgetGuard |
Zero budget returns raw, clears lock before next query; invalid DPR and excessive spans are inert |
| Cache agreement | Not applicable | No image-sized cache or alternative cached query path exists |
Interaction, display and output matrix
| Issue criterion | Automated check | Scope/limit |
|---|---|---|
| Noncentral handle press; first move has no offset jump | RegionInputHandler::testBoundarySnapToggleDoesNotAccumulate, existing offset cases |
Real mouse event coordinates and original press delta |
| Alt/Option and S, stationary press/release, autorepeat, final release position | testBoundarySnapInteraction, testBoundarySnapToggleDoesNotAccumulate |
20 on/off cycles with exact geometry/signal counts; final mouse event modifiers honored |
| Initial selection, whole-rectangle movement and excluded modes stay unchanged | testBoundarySnapLeavesCreationAndMoveAlone, testBoundarySnapExcludedModes |
No guides; exact raw geometry; no key-triggered geometry signals in multi/replace/history/locked-ratio modes; Alt-bearing mouse moves match the ordinary resize baseline |
| Outside-click expansion and keyboard precision remain intact | Existing input outside-click cases, selection manager keyboard cases, HistoryReplay::testDetectedWindowMetadataSurvivesHighlightClear |
Existing ordinary geometry and arrow/Shift-arrow behavior |
| One final geometry commit per update | handlesAndDpr, repeated key-toggle test |
One selectionChanged, never a raw-then-snapped pair |
| Esc restores original resize | testResizeEscapeDoesNotAcceptQuickPin |
Move first, then restore the pre-drag rectangle in both Esc routes, with/without snapping and Quick Pin; release emits no pin and writes no history |
| Local guides appear and disappear | RegionPainterChrome::testSnapGuidesAreLocalAndTransient |
Both short edge segments must independently change pixels, with no differences outside them; clearing/finishing returns the original rendered image |
| History entry/return, close, late input | HistoryReplay::testBoundarySnapHistoryAndCloseLifecycle |
Replay uses a different image and cannot snap; restored live capture must use its own edge; close clears source/guides and late input cannot reuse them |
| Save/copy crop and history source remain clean | testBoundarySnapCaptureRoundTrip |
Actual shared export pipeline pixels equal original crop while guides are active; history canvas unchanged. OS clipboard transfer itself remains covered by existing platform tests |
| DPR and negative screen origin | testBoundarySnapCaptureRoundTrip, sourceReplacementChangesScaleAndLock |
Actual selector/export context at DPR 1/1.25/1.5/2 with a negative widget origin asserted after each canvas geometry update; simulated capture changes, not physical mixed-monitor routing |
| Old asynchronous work cannot change a new capture | Source/lifecycle tests; no asynchronous worker | There is no worker completion callback to exercise |
| 4K/6K time and memory | RegionSelector_BoundarySnapMetrics |
20 warmups + 200 independent two-axis queries per size/DPR, final crop/fallback verified for every sample; timing target and process peak reported |
What remains outside automated acceptance
- Real screenshots of light/dark applications, code, dialogs/shadows and photos; target coverage and false-snap rates over a representative, labelled corpus. Synthetic contrast fixtures cannot establish these rates.
- Human mouse/trackpad correction counts and perceived jitter. The scripted trace only establishes deterministic lock stability for that trace.
- Physical macOS Retina and Windows 100/125/150/200% mixed-monitor routing, real pointer sampling and native capture/GPU allocation peaks.
- Ubuntu X11 window-manager interception of Alt-drag. Injected Qt events prove the S alternative’s application behavior, not the window manager’s event delivery.
- Windows/Linux results until the exact follow-up commit’s CI artifacts are available. CI virtual/offscreen screens do not replace the physical checks above.
These remain open acceptance items; automated tests do not justify auto-closing #280 or claiming all physical pixel boundaries and objects can snap.
Reading CI evidence
Select a CI Build run whose head SHA matches the PR, then inspect its three test-evidence-* artifacts. The JUnit/CTest logs establish which tests ran; boundary-snap-metrics.json records host-specific timing and memory. Require correct and every scenario’s preflight_correct before interpreting timing. p95_target_met is a separate performance result, not a universal guarantee. Local timing snapshots are not duplicated in these pages.