log: Support reportErrorToUserBriefly

The motivation of having this indirection, rather than using
`showErrorDialog` and `showSnackBar` directly, is to keep
dependencies of `lib/log.dart` from relying on widget code.

Signed-off-by: Zixuan James Li <[email protected]>

Author: gnprice

assets/l10n/app_en.arb

@@ -293,6 +293,10 @@
   "@errorDialogTitle": {
     "description": "Generic title for error dialog."
   },
+  "snackBarDetails": "Details",
+  "@snackBarDetails": {
+    "description": "Button label for snack bar button that opens a dialog with more details."
+  },
   "lightboxCopyLinkTooltip": "Copy link",
   "@lightboxCopyLinkTooltip": {
     "description": "Tooltip in lightbox for the copy link action."

lib/log.dart

@@ -30,3 +30,31 @@ bool debugLog(String message) {
   }());
   return true;
 }
+
+typedef ReportErrorCallback = void Function(String? message, {String? details});
+
+/// Display an error message in a [SnackBar].
+///
+/// This shows a [SnackBar] containing the message if [ZulipApp] is ready,
+/// otherwise logs it to the console.
+///
+/// If `message` is null, this will clear the existing [SnackBar]s if there
+/// are any.  Useful for promptly dismissing errors.
+///
+/// If `details` is non-null, the [SnackBar] will contain a button that would
+/// open a dialog containing the error details.
+// This gets set in [ZulipApp].  We need this indirection to keep `lib/log.dart`
+// from importing widget code, because the file is a dependency for the rest of
+// the app.
+ReportErrorCallback reportErrorToUserBriefly = defaultReportErrorToUserBriefly;
+
+void defaultReportErrorToUserBriefly(String? message, {String? details}) {
+  // Error dismissing is a no-op to the default handler.
+  if (message == null) return;
+  // If this callback is still in place, then the app's widget tree
+  // hasn't mounted yet even as far as the [Navigator].
+  // So there's not much we can do to tell the user;
+  // just log, in case the user is actually a developer watching the console.
+  assert(debugLog(message));
+  if (details != null) assert(debugLog(details));
+}

lib/widgets/app.dart

@@ -5,10 +5,12 @@ import 'package:flutter/material.dart';
 import 'package:flutter/scheduler.dart';
 import 'package:flutter_gen/gen_l10n/zulip_localizations.dart';
 
+import '../log.dart';
 import '../model/localizations.dart';
 import '../model/narrow.dart';
 import 'about_zulip.dart';
 import 'app_bar.dart';
+import 'dialog.dart';
 import 'inbox.dart';
 import 'login.dart';
 import 'message_list.dart';
@@ -84,6 +86,8 @@ class ZulipApp extends StatefulWidget {
   /// TODO refactor this better, perhaps unify with ZulipBinding
   @visibleForTesting
   static void debugReset() {
+    _snackBarCount = 0;
+    reportErrorToUserBriefly = defaultReportErrorToUserBriefly;
     _ready.dispose();
     _ready = ValueNotifier(false);
   }
@@ -92,9 +96,44 @@ class ZulipApp extends StatefulWidget {
   /// Useful in tests.
   final List<NavigatorObserver>? navigatorObservers;
 
+  static int _snackBarCount = 0;
+
+  static void _reportErrorToUserBriefly(String? message, {String? details}) {
+    assert(_ready.value);
+
+    if (message == null) {
+      if (_snackBarCount == 0) return;
+      assert(_snackBarCount > 0);
+      // The snack bar API only exposes ways to hide ether the current snack
+      // bar or all of them.
+      //
+      // To reduce the possibility of hiding snack bars not created by this
+      // helper, only clear when there are known active snack bars.
+      scaffoldMessenger!.clearSnackBars();
+      return;
+    }
+
+    final localizations = ZulipLocalizations.of(navigatorKey.currentContext!);
+    final newSnackBar = scaffoldMessenger!.showSnackBar(
+      snackBarAnimationStyle: AnimationStyle(
+        duration: const Duration(milliseconds: 200),
+        reverseDuration: const Duration(milliseconds: 50)),
+      SnackBar(
+        content: Text(message),
+        action: (details == null) ? null : SnackBarAction(
+          label: localizations.snackBarDetails,
+          onPressed: () => showErrorDialog(context: navigatorKey.currentContext!,
+            title: localizations.errorDialogTitle,
+            message: details))));
+
+    _snackBarCount++;
+    newSnackBar.closed.whenComplete(() => _snackBarCount--);
+  }
+
   void _declareReady() {
     assert(navigatorKey.currentContext != null);
     _ready.value = true;
+    reportErrorToUserBriefly = _reportErrorToUserBriefly;
   }
 
   @override

test/widgets/app_test.dart

@@ -1,6 +1,7 @@
 import 'package:checks/checks.dart';
 import 'package:flutter/material.dart';
 import 'package:flutter_test/flutter_test.dart';
+import 'package:zulip/log.dart';
 import 'package:zulip/model/database.dart';
 import 'package:zulip/widgets/app.dart';
 import 'package:zulip/widgets/inbox.dart';
@@ -10,6 +11,7 @@ import '../example_data.dart' as eg;
 import '../flutter_checks.dart';
 import '../model/binding.dart';
 import '../test_navigation.dart';
+import 'dialog_checks.dart';
 import 'page_checks.dart';
 import 'test_app.dart';
 
@@ -169,5 +171,97 @@ void main() {
       check(ZulipApp.scaffoldMessenger).isNotNull();
       check(ZulipApp.ready).value.isTrue();
     });
+
+    const message = 'test error message';
+    const details = 'error details';
+
+    Finder findSnackBarByText(String text) => find.descendant(
+      of: find.byType(SnackBar),
+      matching: find.text(text));
+
+    testWidgets('reportErrorToUserBriefly with details', (tester) async {
+      addTearDown(testBinding.reset);
+      await tester.pumpWidget(const ZulipApp());
+
+      // Prior to app startup, reportErrorToUserBriefly only logs.
+      reportErrorToUserBriefly(message, details: details);
+      check(ZulipApp.ready).value.isFalse();
+      await tester.pump();
+      check(findSnackBarByText(message).evaluate()).isEmpty();
+      check(find.byType(AlertDialog).evaluate()).isEmpty();
+
+      check(ZulipApp.ready).value.isTrue();
+      // After app startup, reportErrorToUserBriefly displays a SnackBar.
+      reportErrorToUserBriefly(message, details: details);
+      await tester.pumpAndSettle();
+      check(findSnackBarByText(message).evaluate()).single;
+      check(find.byType(AlertDialog).evaluate()).isEmpty();
+
+      // Open the error details dialog.
+      await tester.tap(find.text('Details'));
+      await tester.pumpAndSettle();
+      check(findSnackBarByText(message).evaluate()).isEmpty();
+      checkErrorDialog(tester, expectedTitle: 'Error', expectedMessage: details);
+    });
+
+    Future<void> prepareSnackBarWithDetails(WidgetTester tester) async {
+      addTearDown(testBinding.reset);
+      await tester.pumpWidget(const ZulipApp());
+      await tester.pump();
+      check(ZulipApp.ready).value.isTrue();
+
+      reportErrorToUserBriefly(message, details: details);
+      await tester.pumpAndSettle();
+      check(findSnackBarByText(message).evaluate()).single;
+    }
+
+    testWidgets('reportErrorToUser dismissing SnackBar', (tester) async {
+      await prepareSnackBarWithDetails(tester);
+
+      // Dismissing the SnackBar.
+      reportErrorToUserBriefly(null);
+      await tester.pumpAndSettle();
+      check(findSnackBarByText(message).evaluate()).isEmpty();
+
+      // Verify that the SnackBar would otherwise stay when not dismissed.
+      reportErrorToUserBriefly(message, details: details);
+      await tester.pumpAndSettle();
+      check(findSnackBarByText(message).evaluate()).single;
+      await tester.pumpAndSettle();
+      check(findSnackBarByText(message).evaluate()).single;
+    });
+
+    testWidgets('reportErrorToUserBriefly(null) does not dismiss dialog', (tester) async {
+      await prepareSnackBarWithDetails(tester);
+
+      // Open the error details dialog.
+      await tester.tap(find.text('Details'));
+      await tester.pumpAndSettle();
+      check(findSnackBarByText(message).evaluate()).isEmpty();
+      checkErrorDialog(tester, expectedTitle: 'Error', expectedMessage: details);
+
+      // The dialog should not get dismissed.
+      reportErrorToUserBriefly(null);
+      await tester.pumpAndSettle();
+      checkErrorDialog(tester, expectedTitle: 'Error', expectedMessage: details);
+    });
+
+    testWidgets('reportErrorToUserBriefly(null) does not dismiss unrelated SnackBar', (tester) async {
+      await prepareSnackBarWithDetails(tester);
+
+      // Dismissing the SnackBar.
+      reportErrorToUserBriefly(null);
+      await tester.pumpAndSettle();
+      check(findSnackBarByText(message).evaluate()).isEmpty();
+
+      // Unrelated SnackBars should not be dismissed.
+      ZulipApp.scaffoldMessenger!.showSnackBar(
+        const SnackBar(content: Text ('unrelated')));
+      await tester.pumpAndSettle();
+      check(findSnackBarByText('unrelated').evaluate()).single;
+      reportErrorToUserBriefly(null);
+      await tester.pumpAndSettle();
+      check(findSnackBarByText('unrelated').evaluate()).single;
+    });
   });
 }