BugLens 🔍🐛

The Ultimate Flutter In-App QA & Developer Debugging Toolkit

BugLens is a complete in-app debugging, live inspection, and QA issue-reporting SDK for Flutter applications running across all platforms (Android, iOS, Web, macOS, Windows, Linux).

It provides 1-line setup and zero-boilerplate drop-in interceptors for Networking (Dio & HTTP), State Management (Bloc & Riverpod), Navigation, Video Recording, and Console Prints.

---

⚡ Super Easy 1-Line Setup

Option 1: 1-Line in main() (Recommended)

Automatically initializes bindings, configures BugLens, captures unhandled errors, intercepts print() statements, and injects the overlay:

import 'package:bug_lens/bug_lens.dart';
import 'package:flutter/material.dart';

void main() => BugLens.run(() => const MyApp());

class MyApp extends StatelessWidget {
  const MyApp({super.key});

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      navigatorObservers: [BugLens.navigatorObserver],
      home: const HomeScreen(),
    );
  }
}

Option 2: 1-Line in MaterialApp

If you prefer standard main(), simply add builder: BugLens.builder():

void main() => runApp(const MyApp());

class MyApp extends StatelessWidget {
  const MyApp({super.key});

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      // 🌟 1-Line Setup: Injects BugLens overlay, screenshot capturer & video recorder
      builder: BugLens.builder(),
      navigatorObservers: [BugLens.navigatorObserver],
      home: const HomeScreen(),
    );
  }
}

---

🌟 Key Features

• 🌐 Alice-Like Network Interceptor: Plug BugLens.dioInterceptor directly into Dio or HTTP clients to automatically record all requests, responses, headers, query params, payloads, latency, status badges, and generate ready-to-run cURL commands.
• 🎥 Screen Video Recording: Record problem reproduction video clips at ~8-10 FPS on any platform (Mobile, Desktop, Web) with a floating REC indicator pill and interactive player.
• 📊 Standalone HTML Dashboard Exporter: Generates offline-ready, responsive .html reports with embedded screenshots, animated video replay, network tables, and error stack traces.
• 🧱 Drop-in State Interceptors: Attach BugLens.blocObserver or BugLens.riverpodObserver to automatically track state transitions and mutations without boilerplate.
• 🖨️ Console Print Interceptor: Automatically captures standard print() statements into structured searchable logs.
• 📐 Live UI & Widget Inspector: Tap any widget on screen at runtime to view its dimensions, global coordinates (x, y), route, parent & children hierarchy, and tap "Report This Widget" to pre-attach its metrics directly to a bug report.
• 🎨 Screenshot Annotation Studio: Draw freehand lines, arrows, rectangles, circles, text labels, markers, and blackout blur boxes over captured screens.
• 🛡️ Privacy & Redaction by Default: Automatically masks sensitive headers (Authorization, Cookie, X-Api-Key) and sensitive payload fields (password, token, secret, cvv, credit_card).

---

🔌 Plug-and-Play Interceptors

1. Dio Network Interceptor

import 'package:dio/dio.dart';
import 'package:bug_lens/bug_lens.dart';

final dio = Dio();

// All HTTP calls, responses, and errors are recorded automatically!
dio.interceptors.add(BugLens.dioInterceptor);

2. HTTP Client Tracker

import 'package:bug_lens/bug_lens.dart';

final reqId = BugLens.httpTracker.trackRequest(
  url: 'https://api.example.com/data',
  method: 'GET',
);
// track response
BugLens.httpTracker.trackResponse(requestId: reqId, statusCode: 200, body: json);

3. Bloc / Cubit State Observer

import 'package:flutter_bloc/flutter_bloc.dart';
import 'package:bug_lens/bug_lens.dart';

void main() {
  // Automatically logs all Bloc events, transitions, changes, and errors!
  Bloc.observer = BugLens.blocObserver;
  BugLens.run(() => const MyApp());
}

4. Riverpod State Observer

import 'package:flutter_riverpod/flutter_riverpod.dart';
import 'package:bug_lens/bug_lens.dart';

void main() {
  BugLens.run(
    () => ProviderScope(
      observers: [BugLens.riverpodObserver], // Automatically tracks provider updates
      child: const MyApp(),
    ),
  );
}

---

🎥 Screen Video Recording

Start and stop recording programmatically, or tap the video icon in the inspector:

// Start recording screen frames
BugLens.startRecording();

// Stop recording and attach video to the QA bug report
BugLens.stopRecording();

// Check status
bool recording = BugLens.isRecording;

---

🧪 Automated Test Reporter

Generate comprehensive HTML test reports during automated widget and integration tests:

testWidgets('Checkout smoke test', (tester) async {
  BugLensTestReporter.step('Navigate to cart');
  // ...
  BugLensTestReporter.step('Tap checkout');
  // ...
  final htmlReport = await BugLensTestReporter.generateHtmlReport(
    testName: 'Checkout Smoke Test',
    success: true,
  );
});

---

⚙️ Advanced Custom Configuration

If you need custom buffer limits, themes, or custom redaction rules:

void main() {
  WidgetsFlutterBinding.ensureInitialized();

  BugLens.init(
    environment: BugLensEnvironment.dev,
    config: const BugLensConfig(
      enabled: true,
      maxLogs: 500,
      maxNetworkRequests: 200,
      maxErrors: 100,
      privacy: BugLensPrivacyConfig(
        redactHeaders: true,
        redactResponseBody: true,
      ),
    ),
  );

  BugLens.runZonedApp(() {
    runApp(const MyApp());
  });
}

---

💡 How to Open BugLens in Your App

1. Floating Trigger Button: Tap the floating bug icon on screen (draggable, snaps to screen bounds, displays an error badge when issues occur).
2. Keyboard Shortcut: Press Ctrl+Shift+B (Windows/Linux) or Cmd+Shift+B (macOS) on Web & Desktop.
3. Programmatic Triggers:

   BugLens.open();    // Open console HUD
   BugLens.report();  // Open QA Bug Reporter directly
   BugLens.inspect(); // Activate Live Widget Inspector
   BugLens.close();   // Close console
   

---

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.