permission_inspector 0.0.3

A developer-only permission debugger overlay for Flutter. Inspect live permission states, track changes, and debug permission issues in real-time.

Permission Inspector

A developer-only permission debugger overlay for Flutter
Debug runtime permissions with ease. No more guessing!

---

The Problem

Every Flutter developer faces these permission headaches:

• Permissions fail silently with no clear debugging info
• Android behaves differently per OEM (Samsung, Xiaomi, etc.)
• iOS permission states are unclear (Denied vs. Restricted?)
• Debugging permission issues is painful and time-consuming
• Testing different permission states requires manual device work

The Solution

Permission Inspector is a floating debug overlay that shows you exactly what's happening with your app's permissions in real-time.

Features

Live Permission State Viewer

• See all permissions your app uses at a glance
• Shows: Granted / Denied / Permanently Denied / Restricted / Limited
• Color-coded status indicators for instant recognition
• Real-time updates as permissions change

Debug Information

• Last Request Time - When you last asked for this permission
• Request Count - How many times you've requested it
• OS Version - Current Android/iOS version
• OEM-specific behavior insights

Permission Simulation

• Mock any permission state without changing device settings
• Test deny, grant, permanently denied scenarios instantly
• Perfect for edge case testing and QA workflows
• Clear simulations and return to real states anytime

Beautiful Debug Overlay

• Draggable - Position it wherever you need
• Collapsible - Minimize when not in use
• Dark theme - Easy on the eyes during long debug sessions
• Zero config - Works out of the box

Universal Compatibility

• Works with any permission package
• Built-in integration with permission_handler
• Works on Android and iOS

---

Quick Start

Installation

Add to your pubspec.yaml:

dependencies:
  permission_inspector: ^0.0.1
  permission_handler: ^12.0.1  # Required peer dependency

Basic Usage

import 'package:permission_inspector/permission_inspector.dart';

// Show the debug overlay
PermissionInspector.showOverlay(context);

That's it! The overlay will appear and automatically track common permissions.

---

Usage Examples

1. Auto-Track Common Permissions

// In your main app or debug screen
FloatingActionButton(
  onPressed: () => PermissionInspector.showOverlay(context),
  child: Icon(Icons.security),
)

2. Track Specific Permissions

// Track specific permissions you care about
await PermissionInspector.trackPermissions([
  Permission.camera,
  Permission.microphone,
  Permission.location,
]);

PermissionInspector.showOverlay(context);

3. Request Permissions with Tracking

Replace your normal permission requests:

// Old way
final status = await Permission.camera.request();

// New way - automatically tracked in inspector
final status = await PermissionInspector.request(Permission.camera);

if (status.isGranted) {
  // Open camera
}

4. Simulate Permission States (Testing)

Perfect for testing edge cases without manual device manipulation:

// Simulate a denied camera permission
PermissionInspector.simulatePermission(
  Permission.camera,
  PermissionStatus.denied,
);

// Test your app's behavior with denied camera
// ...

// Clear simulation to return to real state
await PermissionInspector.clearSimulation(Permission.camera);

5. Custom Configuration

PermissionInspector.showOverlay(
  context,
  config: InspectorConfig(
    enableSimulation: true,        // Enable mock permissions
    autoRefresh: true,              // Auto-refresh every 3s
    refreshIntervalSeconds: 3,      
    showOsVersion: true,            // Show OS info
    showDebugInfo: true,            // Show request counts, times
    startMinimized: false,          // Start expanded
    maxHeight: 0.7,                 // Max 70% screen height
  ),
);

6. Minimal Production Mode

Use minimal config in production builds (though we recommend debug-only):

PermissionInspector.showOverlay(
  context,
  config: InspectorConfig.minimal, // Minimal UI, no simulation
);

---

Perfect For

• Development - See permission states while building features
• Debugging - Quickly identify why permissions fail
• Testing - Test all permission scenarios without device setup
• QA - Reproduce and verify permission-related bugs
• OEM Testing - See how different Android OEMs behave

---

Production Safety

Important: This is a developer tool. Remove it from production builds!

// Recommended: Only show in debug mode
if (kDebugMode) {
  PermissionInspector.showOverlay(context);
}

Or use build flavors to exclude it entirely from release builds.

---

API Reference

Main Methods

// Show/hide overlay
PermissionInspector.showOverlay(context, {config});
PermissionInspector.hideOverlay();
PermissionInspector.toggleOverlay(context, {config});

// Track permissions
await PermissionInspector.trackPermission(Permission.camera);
await PermissionInspector.trackPermissions([Permission.camera, ...]);
await PermissionInspector.trackAllCommonPermissions();

// Request with tracking
final status = await PermissionInspector.request(Permission.camera);

// Simulate permissions (testing)
PermissionInspector.simulatePermission(Permission.camera, PermissionStatus.denied);
await PermissionInspector.clearSimulation(Permission.camera);
await PermissionInspector.clearAllSimulations();

// Refresh states
await PermissionInspector.refreshPermission(Permission.camera);
await PermissionInspector.refreshAll();

// Get info
List<PermissionInfo> permissions = PermissionInspector.permissions;
String osVersion = PermissionInspector.getOsVersion();
bool isSimulated = PermissionInspector.isSimulated(Permission.camera);

---

Contributing

Found a bug? Have a feature idea? PRs and issues welcome!

---

Show Your Support

If this package helped you debug permissions, give it a star on GitHub!

---

Made for Flutter developers who are tired of permission debugging pain