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

Libraries

permission_inspector