flight_blackbox 0.1.0
flight_blackbox: ^0.1.0 copied to clipboard
Deterministic in-app event-sourcing black box and crash-to-testWidgets synthesizer for Flutter applications.
flight_blackbox ✈️📦 #
Deterministic in-app event-sourcing ring buffer and crash-to-testWidgets synthesizer for Flutter.
The Paradigm Shift #
When an app crashes or experiences a race condition in QA or production, developers typically receive a stack trace:
Null check operator used on a null value in _RenderFlex...
Or a video recording from a tester saying: "It crashed when I tapped pay while navigating back."
Developers typically spend days trying to manually recreate the exact gesture velocities, asynchronous timing, and network response payloads to reproduce the bug.
flight_blackbox eliminates the reproduction cycle:
- Records user pointer events, route transitions, and HTTP calls into a fixed, zero-allocation circular ring buffer.
- When a crash occurs (or QA triggers a report), it serializes the session into a compact, encrypted
.flightlogor.eflightlog. - The Synthesizer CLI converts that recording into an executable
testWidgetsDart test file. - Run
flutter test test/repros/crash_test.dartand the bug reproduces with breakpoints right inside your IDE.
Key Architectural Highlights #
- Engine-Level Pointer Interception & Semantic Resolution: Taps directly into
GestureBinding.instance.pointerRouter.addGlobalRouteand walks the render tree viaSemanticResolverto generate resilient finders (find.byKey,find.text,find.byType) rather than fragile pixel coordinates. - Zero-Allocation Ring Buffer: $O(1)$ enqueue/dequeue using pre-allocated circular memory slots. Zero heap garbage collection impact during high-frequency gesture tracking.
- Keyboard & IME Input Tracking: Intercepts
flutter/textinputplatform messages, mapping keystrokes to target inputs withRedactionEnginemasking and generating cleantester.enterText(...)assertions. - Platform Channel Replay &
MissingPluginExceptionImmunity: Captures allMethodChannelcalls and automatically generatesPlatformChannelReplayBinding.installAll(...)stubs in tests so third-party plugins (camera, biometric, bluetooth) never fail in CI headless test environments. - WebSocket Recording & In-Process Replay: Automatically records bidirectional WebSocket frames and replays them deterministically via
FlightWebSocketReplayServer. - Pure-Dart Authenticated Cryptography: Full ChaCha20 quarter-round stream cipher + HMAC-SHA256 authenticated encryption engine (
.eflightlog) with PBKDF2 key derivation. Zero external native dependencies. - Automatic DI Test Harness Scaffolding: Detects your project's DI architecture (Riverpod, GetIt, Bloc, Provider) and generates complete
test/flight_harness.dartscaffolding. - Sub-Pixel Noise Throttling: Smart distance & delta filtering for
PointerMoveEventso finger drags don't overflow the memory buffer. - Enterprise-Grade PII Sanitizer: Automatic regex and key-based scrubbing for credit cards, bearer tokens, passwords, and emails before anything hits the buffer.
- Dual Replay Harness: Standalone
FlightReplayServerautomatically mocks recorded HTTP calls during test execution with zero external network dependencies. - Pure Dart CLI:
dart run flight_blackbox:synthesizeruns anywhere—including lightweight CI/CD agents—without requiring the Flutter GUI engine.
Architecture Overview #
flowchart TD
subgraph Flutter App Runtime
P[PointerRouter Ingress] --> RB[Fixed EventRingBuffer]
N[NavigatorObserver] --> RB
H[HttpOverrides] --> RB
L[WidgetsBindingObserver] --> RB
end
subgraph Crash / Bug Trigger
RB --> Dump[Crash Session Exporter]
Dump --> Log[".flightlog (GZIP Binary)"]
end
subgraph Developer Workflow
Log --> CLI["dart run flight_blackbox:synthesize"]
CLI --> Synthesizer[FlightSynthesizer]
Synthesizer --> DartTest["crash_repro_test.dart"]
DartTest --> Replay["flutter test (Halts on exact line with debugger!)"]
end
Getting Started #
1. Add to pubspec.yaml #
dependencies:
flight_blackbox: ^0.1.0
2. Initialize in main.dart #
import 'package:flutter/material.dart';
import 'package:flight_blackbox/flight_blackbox.dart';
void main() {
WidgetsFlutterBinding.ensureInitialized();
// Start recording
FlightRecorder.instance.start(
config: FlightConfig(
bufferCapacity: 1000,
enablePointerRecording: true,
enableNavigationRecording: true,
enableHttpRecording: true,
enableCrashRecording: true,
),
);
runApp(const MyApp());
}
class MyApp extends StatelessWidget {
const MyApp({super.key});
@override
Widget build(BuildContext context) {
return MaterialApp(
navigatorObservers: [
FlightRecorder.instance.navigatorObserver, // Tracks route pushes/pops
],
builder: (context, child) {
// Optional: Diagnostic floating pill for internal/staging builds
return FlightRecorderOverlay(
child: child ?? const SizedBox.shrink(),
);
},
home: const HomeScreen(),
);
}
}
Synthesizing a Test from a Crash Log #
When a .flightlog or encrypted .eflightlog is exported (or caught by the automatic crash dumper):
# Standard synthesis
dart run flight_blackbox:synthesize -i crash.flightlog -o test/repros/crash_test.dart -w "const MyApp()"
# Synthesizing from an encrypted session with DI harness auto-detection
dart run flight_blackbox:synthesize \
-i crash.eflightlog \
-k "your-secure-passphrase" \
-o test/repros/crash_test.dart \
-w "const MyApp()" \
-H auto
CLI Options #
| Flag | Abbr | Description | Default |
|---|---|---|---|
--input |
-i |
Path to .flightlog or .eflightlog |
Required |
--output |
-o |
Destination path for generated Dart test | test/repro_test.dart |
--widget |
-w |
Root application widget constructor | const Placeholder() |
--description |
-d |
Test description inside testWidgets |
Reproduced Flight Session Test |
--key |
-k |
Decryption passphrase for .eflightlog |
null |
--harness |
-H |
Generates test/flight_harness.dart (auto, riverpod, bloc, get_it, provider) |
null |
Sample Synthesized Test with Semantic Resolution & Platform Stubs #
// AUTO-GENERATED BY FLIGHT RECORDER
import 'package:flutter/material.dart';
import 'package:flutter_test/flutter_test.dart';
import 'package:flight_blackbox/flight_blackbox.dart';
import 'package:my_app/main.dart';
final List<ReplayFixture> _recordedFixtures = [
ReplayFixture(
method: 'GET',
urlPattern: 'https://api.myapp.com/cart',
statusCode: 200,
responseBody: r'''{"items": [{"id": 42, "name": "Item"}]}''',
),
];
void main() {
testWidgets('Reproduced Flight Session Test', (WidgetTester tester) async {
// 1. Configure viewport & device metrics to match recording
tester.view.physicalSize = const Size(1080.0, 2400.0);
tester.view.devicePixelRatio = 2.62;
addTearDown(tester.view.resetPhysicalSize);
addTearDown(tester.view.resetDevicePixelRatio);
// 2. Install deterministic HTTP replay server & platform stubs
final replayServer = FlightReplayServer(fixtures: _recordedFixtures);
replayServer.install();
addTearDown(replayServer.uninstall);
// 3. Pump application tree
await tester.pumpWidget(const MyApp());
await tester.pumpAndSettle();
// 4. Deterministic interaction replay with semantic finders
await tester.pump(const Duration(milliseconds: 140));
await tester.tap(find.byKey(const Key('catalog_search_field')));
await tester.pump(const Duration(milliseconds: 80));
await tester.enterText(find.byKey(const Key('catalog_search_field')), 'Laptop');
await tester.pumpAndSettle();
// Tap button resolved by text
await tester.tap(find.text('Add to Cart'));
await tester.pump();
});
}
Run it locally:
flutter test test/repros/crash_test.dart
Security & PII Redaction #
flight_recorder adopts a safe-by-default posture:
- Headers like
Authorization,Cookie,X-Api-Keyare automatically masked to[REDACTED]. - JSON object keys containing
password,token,secret,credit_card,ssn,cvvare recursively redacted. - Strings are checked against Regex rules for credit cards, emails, and bearer tokens.
You can register custom redaction rules easily:
FlightRecorder.instance.start(
config: FlightConfig(
redactionEngine: RedactionEngine(
rules: [
RedactRule.emails(),
RedactRule.creditCards(),
RedactRule(
name: 'phone_numbers',
pattern: RegExp(r'\+?\d{10,14}'),
replacement: '[PHONE_REDACTED]',
),
],
),
),
);
Diagnostic Overlay #
Wrap your app with FlightRecorderOverlay in staging or dogfood builds. A floating diagnostic button gives testers and developers instant access to:
- A live event stream showing recent pointer events, navigation history, and network calls.
- Export
.flightlogto share directly on GitHub or Jira. - Copy Dart Test to clipboard to immediately paste into your test suite.