Debug Mode Feature

This document provides technical documentation about the Debug Mode feature in the Flutter Mobile Project Template. The Debug Mode feature offers developers tools for testing and debugging application functionality directly within the running app. It includes utilities for testing error handling, maintenance mode, force updates, and navigation.

Overview

The Debug Mode feature consists of a suite of developer tools accessible at runtime to assist with testing various application states and behaviors without modifying code. It is designed to be available only in development environments and not in production builds.

Sources: packages/features/debug_mode/lib/src/ui/debug_page.dart19-66 packages/features/debug_mode/lib/src/ui/navigation_debug_page.dart7-27

Main Debug Page

The main Debug Page serves as the entry point to debugging tools and provides buttons for various debugging actions. It's implemented as a ConsumerWidget using the Riverpod state management library.

Key features of the main Debug Page include:

1. Error Simulation - Triggers network errors to test error handling
2. Maintenance Mode Toggle - Enables maintenance mode for testing the maintenance page
3. Force Update Trigger - Simulates a required app update condition
4. Navigation Debugging - Provides access to the Navigation Debug Page

Sources: packages/features/debug_mode/lib/src/ui/debug_page.dart19-66

Navigation Debug Page

The Navigation Debug Page allows developers to test application routing by:

1. Displaying all available routes in the application
2. Providing a dropdown menu to select a route
3. Allowing manual editing of the route path
4. Offering a button to navigate to the selected route

This feature is particularly useful for testing deep linking and complex navigation patterns.

Sources: packages/features/debug_mode/lib/src/ui/navigation_debug_page.dart7-118

Implementation Details

Debug Page Navigator

The Debug Mode feature implements a DebugPageNavigator interface to handle navigation between debug screens. This interface is provided through a Riverpod provider which must be implemented by the application.

Sources: packages/features/debug_mode/lib/src/ui/debug_page.dart12-17 packages/features/debug_mode/lib/src/ui/debug_page.g.dart11-29

Integration with Other Features

The Debug Mode feature integrates with other features in the application:

1. Force Update Feature: Can trigger a simulated force update scenario by setting a target version higher than the current app version
2. Maintenance Mode: Can enable maintenance mode to test the maintenance page UI and behavior
3. Error Handling: Can generate exceptions to test error handling mechanisms

This integration allows comprehensive testing of application behavior under various conditions without changing code or waiting for specific server-side states.

Sources: packages/features/debug_mode/lib/src/ui/debug_page.dart31-61

Route Path Extraction

The Navigation Debug Page includes a utility extension (_ToPaths) on List<RouteBase> that extracts all available route paths from the GoRouter configuration. It recursively explores the route tree, including child routes, to build a comprehensive list of navigation paths.

extension _ToPaths on List<RouteBase> {
  List<String> toPaths([String? parentPath]) {
    // Recursively extract route paths
    // ...
  }
}

This extracted list is filtered to exclude debug-related routes to prevent navigation loops.

Sources: packages/features/debug_mode/lib/src/ui/navigation_debug_page.dart95-118

Usage

Accessing Debug Mode

The application should provide a way to access the Debug Mode, typically:

1. In development/staging builds only
2. Through a specific route or gesture (e.g., a hidden button or multi-tap sequence)

The debug page is usually added to the router configuration conditionally based on build configuration:

debug_mode{Debug Mode?}
go_router --> debug_mode
debug_mode -->|Yes| debug_route[DebugPageRoute]

Testing App States

To test different application states:

1. To simulate a server error: Press "Show error SnackBar"
2. To test maintenance mode: Press "Enable maintenance mode"
3. To test force update screen: Press "Enable force update"

Testing Navigation

To test application navigation:

1. Navigate to the Navigation Debug Page using the "Go navigation debug page" button
2. Select a route from the dropdown menu or manually enter a route path
3. Press "Go" to navigate to the selected route

Best Practices

1. Security: Ensure Debug Mode is never included in production builds
2. Restoration: After testing with Debug Mode, reset the application state (restart may be required)
3. Documentation: When adding new features, consider adding debug utilities to test them

Sources: packages/features/debug_mode/lib/src/ui/debug_page.dart19-66 packages/features/debug_mode/lib/src/ui/navigation_debug_page.dart7-118