flutter-async-test-unhandled-future-rejection

Flutter Async Test Unhandled Future Rejection

Problem

Tests that create Futures which will reject (throw errors) can fail in CI even when:

• You catch the error with .catchError() at the end
• You use try/catch around the await
• The test passes locally

The Flutter/Dart test framework detects "unhandled" Future rejections during test execution, even if you plan to handle them later. This causes flaky tests that pass locally but fail in CI due to timing differences.

Context / Trigger Conditions

Symptoms:

• Test passes locally with flutter test but fails in CI
• Error message is truncated or cryptic (e.g., "ROR]" instead of "[ERROR]")
• Test name appears in error output but no clear assertion failure
• Test involves creating Futures to URLs/resources that don't exist
• Using patterns like:

  final future = someAsyncOperation(); // This will throw
  // ... do assertions ...
  await future.catchError((_) {}); // Too late - already flagged as unhandled
  

Common scenarios:

• Testing that a method can only be called once (state guards)
• Testing timeout/cancellation behavior
• Testing error handling paths
• Any test that intentionally triggers errors in async code

Solution

Don't create Futures that will reject - test the state machine directly

Instead of:

test('start throws if already started', () async {
  final session = SomeSession(url: 'wss://fake.url');

  // BAD: This Future will reject when connection fails
  final startFuture = session.start();

  // Even this won't help - rejection already detected
  await Future.delayed(Duration.zero);

  expect(() => session.start(), throwsA(isA<StateError>()));

  // Too late to catch - test already failed
  await startFuture.catchError((_) {});
});

Do this:

test('start throws if already started', () {
  // GOOD: Completely synchronous, no network calls
  final session = SomeSession(url: 'wss://example.com');

  // Use a synchronous state transition to exit the "startable" state
  session.cancel(); // Transitions state without network call

  // Now test that start() throws when not in initial state
  expect(
    () => session.start(),
    throwsA(isA<StateError>()),
  );

  session.dispose();
});