flutter-dispose-timer-test-failure

name	flutter-dispose-timer-test-failure
description	Fix Flutter test failure "A Timer is still pending even after the widget tree was disposed". Use when: (1) Widget tests fail with timer pending error, (2) dispose() contains Future(), Future.delayed(), or Timer calls, (3) Riverpod provider modifications in dispose(). The fix is to use deactivate() instead of dispose() for cleanup that might trigger async work.
author	Claude Code
version	1.0.0
date	"2025-01-26T00:00:00.000Z"

Flutter Dispose Timer Test Failure

Problem

Flutter widget tests fail with the error "A Timer is still pending even after the widget tree was disposed" when dispose() contains Future-based cleanup code.

Context / Trigger Conditions

• Test error: A Timer is still pending even after the widget tree was disposed
• Widget's dispose() method contains:
  • Future(() => ...)
  • Future.delayed(...)
  • Timer(...) or Timer.periodic(...)
  • Riverpod ref.read(provider.notifier).someMethod() wrapped in Future
• Tests pass individually but fail when run together
• Error appears at end of test, not during widget interaction

Solution

Step 1: Identify the problematic code

Look for patterns like this in your widget:

// BAD: Creates pending timer that test framework detects
@override
void dispose() {
  final notifier = _overlayNotifier;
  if (notifier != null) {
    Future(() => notifier.setSettingsOpen(false));  // <- Problem!
  }
  super.dispose();
}

Step 2: Move cleanup to deactivate()

Use deactivate() instead of dispose() and remove the Future wrapper:

// GOOD: Runs synchronously before widget is removed
@override
void deactivate() {
  _overlayNotifier?.setSettingsOpen(false);  // Direct call, no Future
  super.deactivate();
}

Step 3: Understand the lifecycle difference

• deactivate(): Called when widget is removed from tree, but State might be reinserted
• dispose(): Called when State will never build again, permanent cleanup

For most notification/provider cleanup, deactivate() is appropriate.

Verification

1. Run the specific test that was failing
2. Run the full test suite
3. Verify no "Timer is still pending" errors

Example

Before (causes test failure):

class _SettingsScreenState extends ConsumerState<SettingsScreen> {
  OverlayNotifier? _overlayNotifier;

  @override
  void dispose() {
    final notifier = _overlayNotifier;
    if (notifier != null) {
      // This Future creates a pending timer!
      Future(() => notifier.setSettingsOpen(false));
    }
    super.dispose();
  }
}

After (tests pass):

class _SettingsScreenState extends ConsumerState<SettingsScreen> {
  OverlayNotifier? _overlayNotifier;

  @override
  void deactivate() {
    // Synchronous call, no timer created
    _overlayNotifier?.setSettingsOpen(false);
    super.deactivate();
  }
}

Notes

• The original Future(() => ...) pattern is often used to defer provider modifications until after the current build phase, avoiding "Cannot modify provider during build" errors
• If you need deferred execution, consider WidgetsBinding.instance.addPostFrameCallback instead, though this also creates timers that can fail tests
• For Riverpod, modifying providers in deactivate() is usually safe since the widget tree is being torn down, not built
• This issue often surfaces when multiple tests run sequentially, as the test framework checks for pending timers between tests

References

• Flutter Widget Lifecycle
• Flutter Testing: Pending Timers