simple_permission_workflow #

A small Dart/Flutter library that simplifies usage of the permission_handler inner library by offering a centralized permission workflow (status check, rationale dialog, request, open app settings).

Features #

• Single workflow to check and request permissions.
• Optional rationale UI support via withRationale.
• Injection of service factories to replace real permission services with fakes for tests.
• Returns a structured SPWResponse describing the result.

Quick highlights #

• Avoids direct calls to native permission_handler code in tests by allowing to inject fake services.
• Designed to be small and testable.

Installation #

Add the package to your pubspec.yaml (adjust source as required):

dependencies:
  simple_permission_workflow:
    path: ../simple_permission_workflow

Then run:

flutter pub get

Usage #

Basic usage:

final spw = SimplePermissionWorkflow();
final response = await spw.launchWorkflow(SPWPermission.contacts);

if (response.granted) {
  // permission granted
} else {
  // handle denied or permanently denied
}

Using withRationale (optional): supply widgets to display rationale dialogs before requesting permissions.

final spw = SimplePermissionWorkflow().withRationale(
  buildContext: context,
  rationaleWidget: MyRationaleWidget(),               // shown when rationale needed
  permanentlyDeniedRationaleWidget: MyPermanentWidget()// shown when permanently denied
);

final response = await spw.launchWorkflow(SPWPermission.location);

Service factory injection (recommended for testing):

final fakeResponse = SPWResponse()
  ..granted = true
  ..reason = 'granted';

final plugin = SimplePermissionWorkflow({
  SPWPermission.contacts: () => FakeContactsService(fakeResponse),
});

final res = await plugin.launchWorkflow(SPWPermission.contacts);

FakeContactsService is any implementation of SPWPermissionService that returns the expected SPWResponse.

API notes #

• SimplePermissionWorkflow([Map<SPWPermission, SPWPermissionService Function()>? factories])
  By default the plugin registers real service factories (e.g. SPWContactsPermission). Passing a map allows overriding any permission service with a factory returning a custom or fake implementation.

• Future<SPWResponse> launchWorkflow(SPWPermission permission)
  Finds the factory for permission, instantiates the service and runs its request method. If no factory is found, it throws ArgumentError.

Testing #

To avoid MissingPluginException and binding errors in tests:

1. Initialize Flutter bindings at top of your test main():

TestWidgetsFlutterBinding.ensureInitialized();

2. Inject fake services instead of using platform MethodChannel based implementations:

class FakeService implements SPWPermissionService {
  final PermissionStatus status;
  FakeService(this.status);
  @override
  Future<PermissionStatus> request() async => status;
}

final plugin = SimplePermissionWorkflow({
  SPWPermission.contacts: () => FakeService(PermissionStatus.granted),
});

3. To test a Future that should throw, do NOT await it directly. Use one of these forms:

// let expect handle the Future
expect(plugin.launchWorkflow(SPWPermission.location), throwsArgumentError);

// or await expectLater
await expectLater(plugin.launchWorkflow(SPWPermission.location), throwsArgumentError);

4. Compare fields of SPWResponse (e.g. res.granted) rather than instance identity unless == is implemented.

Run tests:

flutter test

Development notes #

• The project exposes SimplePermissionWorkflowPlatform and a MethodChannel implementation for runtime use. Tests should avoid swapping to platform MethodChannel unless the platform is properly mocked.
• To add a new permission type: implement an SPWPermissionService in services/impl/, register its factory in the default constructor map or rely on injection.
• Keep UI rationale widgets out of core logic; withRationale simply holds references and triggers dialogs only if a valid BuildContext is given.

Contributing #

See CONTRIBUTING.md for contribution guidelines, testing conventions and PR process.

License #

Choose a license and add it to the repository (e.g. MIT, BSD, etc.).