FleuryTester class - fleury_test_support library

Constructors

FleuryTester({AnimationPolicy animationPolicy = AnimationPolicy.enabled, CellSize viewportSize = const CellSize(80, 24), ColorMode colorMode = ColorMode.truecolor, GlyphTier glyphTier = GlyphTier.unicode, InlineImageSupport images = InlineImageSupport.none, TextPresentationPolicy textPolicy = TextPresentationPolicy.spec, bool overlayRepaintBoundaries = true, Clipboard? clipboard, InputParser? terminalParser, FleuryTestFailureHandler failureHandler = _throwFleuryTestFailure}): Constructs a tester with fresh, isolated framework pieces. Tests typically don't call this directly — use testWidgets from package:fleury_test.

Properties

binding → TuiBinding: The binding installed above the test tree. Exposed so tests can override animation policy mid-flight or read out scheduler state.
no setter
clipboard → Clipboard: The clipboard the tester installs via ClipboardScope. Defaults to a fresh InProcessClipboard; assert copies with (tester.clipboard as InProcessClipboard).lastWritten or pass a custom fake to the constructor.
final
clock → FakeClock: Monotonic clock shared by scheduler and any other timing primitive that reads from a Clock. Advanced implicitly by pump; tests can also advance directly for fine-grained control.
no setter
colorMode ↔ ColorMode: Capability profile installed in the ambient MediaQuery. Tests set glyphTier to GlyphTier.ascii to exercise the ASCII drawing fallback, or images to InlineImageSupport.placements to exercise the true-pixel image path.
getter/setter pair
dispatcher → InputDispatcher: Input dispatcher driven by sendKey / type. Tests sending non-key events (e.g. ResizeEvent) can dispatch directly via this object.
no setter
focusManager → FocusManager: The focus manager wired into pumpWidget's wrapping FocusManagerScope. Tests that need to assert focused-node identity reach in via this getter.
no setter
glyphTier ↔ GlyphTier: getter/setter pair
hashCode → int: The hash code for this object.
no setterinherited
images ↔ InlineImageSupport: getter/setter pair
keyboardCapabilities ↔ KeyboardCapabilities: The confirmed keyboard capabilities the session runs under. Defaults to the press-only legacy profile, so the existing down-only test corpus keeps meaning what it meant. Set KeyboardCapabilities.full to drive held-state scenarios.
getter/setter pair
lastCommandResult → CommandInvocationResult?: The latest command invocation result visible from the focused context: from its nearest command registry or any registry above it, the app's included, whichever recorded last.
no setter
overlay → OverlayState: The OverlayState of the tester's wrapping Overlay. Useful for assertions on overlay entry count when a test exercises OverlayEntry.insert directly. Throws when called before the first pumpWidget.
no setter
overlayRepaintBoundaries → bool: Whether the harness Overlay wraps each entry in a repaint boundary, as every production host does (buildTuiRoot takes the Overlay default).
final
owner → BuildOwner: The BuildOwner managing the test tree. Exposed for advanced scenarios (e.g. asserting dirty-element queue length).
no setter
root → Element?: The mounted root element, or null before the first pumpWidget.
no setter
rootRenderObject → RenderObject?: The root render object of the mounted tree, or null before mounting.
no setter
runtimeType → Type: A representation of the runtime type of the object.
no setterinherited
scheduler → FakeTickerScheduler: FakeClock-backed scheduler driving every Ticker / FrameTicker in the test tree.
no setter
textPolicy ↔ TextPresentationPolicy: The surface's text width/lowering policy (RFC 0019), as the width probe resolved it on a real terminal.
getter/setter pair
viewportSize ↔ CellSize: Default size used by render / renderToString when no explicit size is given, and the size installed in the ambient MediaQuery. Mutable so tests can grow / shrink the viewport mid-test:
getter/setter pair

Methods

accessibilitySnapshot() → AccessibilitySnapshot: Returns a text-first accessibility/fallback snapshot for the tree.
commandRegistry({BuildContext? context}) → CommandRegistry: Returns the active command registry for context, or for the current focus/default test context when context is omitted.
describeTree() → String: Multi-line dump of the current element tree. Useful in test failure messages and ad-hoc debugging.
dispose() → void: Tears down the test fixtures. Called automatically by testWidgets from package:fleury_test; tests that construct a FleuryTester manually must call this in their test teardown.
exists(Finder finder) → bool: Returns true when finder matches at least one element.
find(Finder finder) → List<Element>: Applies finder to the current tree, returning every match as a list. Throws if pumpWidget hasn't been called yet.
findOne(Finder finder) → Element: Like find but asserts exactly one match and returns it. On zero or multiple matches, invokes the configured failure handler with a dump of the current tree.
holdKey(KeySelector key, {Set<KeyModifier> modifiers = const {}}) → void: Presses key down (without releasing) — the start of a held-key scenario. Requires keyboardCapabilities with held-state support for the session to track it.
invokeCommand(CommandId id, {BuildContext? context}) → Future<CommandInvocationResult>: Invokes a command by stable ID, pumping requested frames while it waits. Test time does not advance automatically. For a command that awaits a dialog, start the invocation, answer the dialog, then await its result.
invokeSemanticAction(SemanticAction action, {SemanticNode? node, SemanticNodeId? id, SemanticRole? role, String? label, Object? value, Object? payload, bool? focused, bool? selected, bool? enabled, bool? checked, bool? busy, String? validationError}) → Future<SemanticActionInvocationResult>: Invokes a semantic action on a node in the current semantic tree.
latchFrame() → KeyboardSnapshot: Publishes the frame-clock latch out of band, for a test that samples the keyboard without rendering.
mountWidget(Widget widget) → void: Mounts or updates widget without laying it out or painting it.
noSuchMethod(Invocation invocation) → dynamic: Invoked when a nonexistent method or property is accessed.
inherited
paste(String text) → void: Dispatches a bracketed PasteEvent — the whole blob at once, as a real paste arrives (so embedded newlines don't act as Enter).
press(KeySequence sequence) → void: Presses a whole KeySequence the way a terminal delivers it: a bare printable step arrives as typed text, a chord or special step as a key event. So press(.d.d) sends two TextInputEvents and press(.ctrl.s) a single KeyEvent, exercising the real text-vs-key routing rather than a synthetic shortcut. Multi-step sequences dispatch their steps in order, completing the sequence in the dispatcher.
pump([Duration? duration]) → void: Advances time and completes a frame: build, layout, paint, then post-frame callbacks. When duration is null, time does not advance.
pumpAndSettle({Duration step = const Duration(milliseconds: 16), Duration timeout = const Duration(seconds: 10)}) → void: Pumps in step increments until a frame does no build work (the tree has settled) or timeout elapses. Throws when timeout is hit while the tree still rebuilds every step.
pumpFleuryHome(Widget widget) → void: Like pumpWidget, but mounts widget as the home of Fleury's standard FleuryApp shell. Use this for app-level tests so navigation, commands, status, and other app-owned scopes match the canonical production shape; use bare pumpWidget for widget-level tests or to exercise a custom shell. Runtime hosts mount either shape exactly as supplied.
pumpWidget(Widget widget) → void: Mounts widget as the root of the test tree (wrapped in the canonical TuiBindingScope + FocusManagerScope + Overlay chrome). On subsequent calls, swaps the user widget in place while preserving the binding / focus manager / overlay state — this matches WidgetTester.pumpWidget semantics, where state keyed by the wrappers (e.g. focused node identity) survives across re-pumps. Completes the first frame, including layout and post-frame callbacks.
releaseKey(KeySelector key, {Set<KeyModifier> modifiers = const {}}) → void: Releases a key previously pressed with holdKey.
render({CellSize? size}) → CellBuffer: Renders the current tree into a fresh CellBuffer sized to size (defaulting to viewportSize). An explicit size also updates viewportSize and ambient MediaQuery, like a terminal resize.
renderToString({CellSize? size, String emptyMark = '·', String imageMark = '#'}) → String: Renders the current tree and stringifies the buffer with one row per line. Leading cells write their grapheme, continuation cells contribute nothing (their leading cell handles them), and empty cells are rendered with emptyMark (default · for visibility against runs of whitespace).
semanticInspectionJson() → Map<String, Object?>: Returns semanticInspectionSnapshot as schema-versioned JSON.
semanticInspectionSnapshot() → SemanticInspectionSnapshot: Returns a machine-readable semantic inspection snapshot for the tree.
semantics() → SemanticTree: Returns an immutable semantic snapshot for the current tree.
semanticTreeDebugString({bool includeState = true}) → String: Returns a deterministic, redaction-aware semantic tree dump.
sendBatch(InputBatch batch) → void: Dispatches a correlated InputBatch, as a lifecycle-mode terminal or the DOM source emits for printables.
sendKey(KeyEvent event) → void: Dispatches event through the input dispatcher and flushes any builds it triggered. Use for special chords (arrows, escape, ctrl-shortcuts).
sendMouse(MouseEvent event) → void: Dispatches a MouseEvent (e.g. a left-button click for click-to-focus). Render first so focus rects are recorded.
sendTerminalBytes(List<int> bytes, {bool flush = false}) → void: Feeds terminal bytes through a persistent parser and the input dispatcher. UTF-8, escape sequences and bracketed paste can span calls. Set flush only when simulating the terminal driver's ambiguity timeout (for example, a standalone Escape); read boundaries do not flush automatically.
settle({Duration step = const Duration(milliseconds: 16), Duration timeout = const Duration(seconds: 5), int stableSteps = 4}) → Future<void>: The async analog of pumpAndSettle for data-bound widgets: yields to the real event loop between steps so pending microtasks, timers, and stream emissions land (a StreamBuilder/QueryBuilder's first value arrives on a later event-loop turn), then flushes builds — repeating until a step does no build work or timeout is hit.
toString() → String: A string representation of this object.
inherited
type(String text) → void: Dispatches one or more graphemes of typed text through the input dispatcher. Equivalent to a TextInputEvent(text).

Operators

operator ==(Object other) → bool: The equality operator.
inherited