dusk library

fluttersdk_dusk — E2E driver for Flutter apps (LLM agent + integration test surfaces).

Public API:

  • DuskPlugin: host-side install entry. Idempotent. Wraps the app's widget root in a RepaintBoundary (no GlobalKey) so the screenshot extension can find it via render-tree walk.
  • RefRegistry: e<N> token system for stable element handles across snapshot/action tool calls.
  • DuskSnapshotEnricher: typedef for the snapshot-enricher extension point (Magic ships MagicFormEnricher via this). Wind diagnostics flow through fluttersdk_wind_diagnostics_contracts.WindDebugRegistry instead (registered by Wind.installDebugResolver()).
  • DuskArtisanProvider: registers 41 dusk:* commands + 39 MCP tool descriptors into artisan.
  • buildPerfReport: the pure builder behind ext.dusk.perf_end, callable from a host's conformance test with the same maps the extension reads.
  • PerfInteraction, activeInteraction and perfInteractionAt: the interaction a dusk gesture opens inside a perf session, read off the zone as Zone.current[#fluttersdk_interaction], from frame-zone work through the active slot, or from any recorded time through perfInteractionAt.
  • rendererReader: the pointer behind the report's env.renderer, which a host may reassign.

Classes

DuskArtisanProvider
Contributes dusk:* commands and MCP tool descriptors to the artisan dispatcher.
DuskPlugin
fluttersdk_dusk plugin install entry. Idempotent.
DuskQuery
Immutable predicate set stored alongside a qN query handle.
PerfInteraction
One dusk gesture inside a perf session, from dispatch to settle.
RefEntry
A single addressable entry stored in RefRegistry.
RefRegistry
Static registry mapping [ref=eN] tokens to RefEntry records.

Enums

PerfMode
What a measurement session switches on.

Properties

framePerfReader ↔ Map<String, Object?> Function()
Reader for the current frame-performance data and liveness signal.
getter/setter pair
pendingHttpCountReader ↔ int Function()
Reader for the live in-flight HTTP request count.
getter/setter pair
perfExtrasReader ↔ Map<String, Object?> Function()
Reader for the magic-side performance extras, the source of the report's counters.magic and summary.routeTransitions.
getter/setter pair
perfInsightContributors ↔ List<List<Map<String, Object?>> Function(Map<String, Object?> report)>
Insight rules contributed by the host, run by ext.dusk.perf_end's insight engine after its built-in rules.
getter/setter pair
perfSessionBeginHook ↔ void Function(PerfMode mode)
Command that opens a measurement session in the packages dusk cannot import: it zeroes wind's counters and telescope's frame buffer, and turns wind's counting ON.
getter/setter pair
perfSessionEndHook ↔ void Function()
Command that closes a measurement session, turning wind's counting back off.
getter/setter pair
perfTimelineReader ↔ List<Map<String, Object?>> Function()
Reader for the host-side timeline rows ext.dusk.perf_trace exports beside dusk's own interactions and frames: HTTP requests, queries, magic notifies, counters, anything with a time on it.
getter/setter pair
recentExceptionsReader ↔ List<Map<String, dynamic>> Function({int limit})
Reader for recent exception entries from TelescopeStore.
getter/setter pair
recentLogsReader ↔ List<Map<String, dynamic>> Function({int limit, String? minLevel})
Reader for recent log entries from TelescopeStore.
getter/setter pair
rendererReader ↔ String Function()
Reader for the renderer the app draws with, the source of the report's env.renderer.
getter/setter pair

Functions

activeInteraction() → PerfInteraction?
The most recently opened interaction that has not settled, or null when none is open or no perf session is.
buildPerfReport(Map<String, Object?> framePerf, Map<String, Object?> extras, Map<String, Object?>? wind, {required Map<String, Object?> env, PerfMode mode = PerfMode.attribution, int? framesDrawn, int framesOutsideSession = 0, bool sessionClockMismatch = false, double? durationMs, bool full = false}) → Map<String, Object?>
Builds the bounded report for one closed session; see analysePerf.
perfInteractionAt(int us) → PerfInteraction?
The interaction whose window [startUs, closedAtUs ?? now] holds us, or null when none does.
recentCapturedExceptions({int limit = 20}) → List<Map<String, dynamic>>
Returns the most recently captured non-fatal errors, newest-first, up to limit entries.

Typedefs

DuskNavigateAdapter = Future<bool> Function(String route)
Optional consumer-side hook that ext.dusk.navigate consults before falling back to SystemNavigator.routeInformationUpdated.
DuskSnapshotEnricher = String? Function(Element element, RefRegistry refs)
Snapshot enricher contract (oracle finding #3 lock-ins, plan §Risks Accepted).