Merge pull request #374 from Workiva/3.1.0/error-boundary-logging

[3.1.0] CPLAT-7837 Add error logging to ErrorBoundary

Author: rmconsole5-wk

lib/src/component/error_boundary_mixins.dart

@@ -1,10 +1,14 @@
 import 'dart:async';
 
+import 'package:logging/logging.dart';
 import 'package:meta/meta.dart';
 import 'package:over_react/over_react.dart';
 
 part 'error_boundary_mixins.over_react.g.dart';
 
+@visibleForTesting
+const String defaultErrorBoundaryLoggerName = 'over_react.ErrorBoundary';
+
 /// A props mixin you can use to implement / extend from the behaviors of an [ErrorBoundary]
 /// within a custom component.
 ///
@@ -83,6 +87,22 @@ abstract class _$ErrorBoundaryPropsMixin implements UiProps {
   ///
   /// > Default: `const Duration(seconds: 5)`
   Duration identicalErrorFrequencyTolerance;
+
+  /// The name to use when the component's logger logs an error via [ErrorBoundaryComponent.componentDidCatch].
+  ///
+  /// Not used if a custom [logger] is specified.
+  ///
+  /// > Default: 'over_react.ErrorBoundary'
+  String loggerName;
+
+  /// Whether errors caught by this [ErrorBoundary] should be logged using a [Logger].
+  ///
+  /// > Default: `true`
+  bool shouldLogErrors;
+
+  /// An optional custom logger instance that will be used to log errors caught by
+  /// this [ErrorBoundary] when [shouldLogErrors] is true.
+  Logger logger;
 }
 
 /// A state mixin you can use to implement / extend from the behaviors of an [ErrorBoundary]
@@ -143,6 +163,8 @@ mixin ErrorBoundaryMixin<T extends ErrorBoundaryPropsMixin, S extends ErrorBound
   @override
   Map get defaultProps => (newProps()
     ..identicalErrorFrequencyTolerance = Duration(seconds: 5)
+    ..loggerName = defaultErrorBoundaryLoggerName
+    ..shouldLogErrors = true
   );
 
   @override
@@ -233,6 +255,8 @@ mixin ErrorBoundaryMixin<T extends ErrorBoundaryPropsMixin, S extends ErrorBound
   //           [2.2.2] Since we should __never__ throw an error from our... uh... error boundary,
   //                   wrap in a try catch just in case `findDomNode` throws as a result of the
   //                   wrapped react tree rendering a string instead of a composite or dom component.
+  //
+  // [3] Log the caught error using a logger if `props.shouldLogErrors` is true.
   // ---------------------------------------------- /\ ----------------------------------------------
 
   String _domAtTimeOfError;
@@ -246,6 +270,7 @@ mixin ErrorBoundaryMixin<T extends ErrorBoundaryPropsMixin, S extends ErrorBound
     if (props.fallbackUIRenderer != null) {
       _lastError = error;
       _lastErrorInfo = info;
+      _logErrorCaughtByErrorBoundary(error, info); // [3]
       return;
     }
     // ----- [2] ----- //
@@ -261,9 +286,12 @@ mixin ErrorBoundaryMixin<T extends ErrorBoundaryPropsMixin, S extends ErrorBound
         if (props.onComponentIsUnrecoverable != null) { // [2.2.1]
           props.onComponentIsUnrecoverable(error, info);
         }
+
+        _logErrorCaughtByErrorBoundary(error, info, isRecoverable: false); // [3]
       } else {
         _lastError = error;
         _lastErrorInfo = info;
+        _logErrorCaughtByErrorBoundary(error, info); // [3]
       }
 
       setState(newState()
@@ -311,6 +339,27 @@ mixin ErrorBoundaryMixin<T extends ErrorBoundaryPropsMixin, S extends ErrorBound
     _identicalErrorTimer?.cancel();
     _identicalErrorTimer = null;
   }
+
+  String get _loggerName {
+    if (props.logger != null) return props.logger.name;
+
+    return props.loggerName ?? defaultErrorBoundaryLoggerName;
+  }
+
+  // ----- [3] ----- //
+  void _logErrorCaughtByErrorBoundary(
+    /*Error|Exception*/ dynamic error,
+    ReactErrorInfo info, {
+    bool isRecoverable = true,
+  }) {
+    if (!props.shouldLogErrors) return;
+
+    String message = isRecoverable
+        ? 'An error was caught by an ErrorBoundary: \nInfo: ${info.componentStack}'
+        : 'An unrecoverable error was caught by an ErrorBoundary (attempting to remount it was unsuccessful): \nInfo: ${info.componentStack}';
+
+    (props.logger ?? Logger(_loggerName)).severe(message, error, info.dartStackTrace);
+  }
 }
 
 /// A MapView with the typed getters/setters for [ErrorBoundaryPropsMixin].

lib/src/component/error_boundary_mixins.over_react.g.dart

@@ -1,4 +1,5 @@
 import 'dart:html';
+import 'package:logging/logging.dart';
 import 'package:over_react/over_react.dart';
 import 'package:over_react_test/over_react_test.dart';
 import 'package:test/test.dart';
@@ -704,6 +705,164 @@ void sharedErrorBoundaryTests(BuilderOnlyUiFactory builder) {
     });
   });
 
+  group('logs errors using a `logger`', () {
+    List<Map<String, List>> calls;
+    List<LogRecord> logRecords;
+    const identicalErrorFrequencyToleranceInMs = 500;
+
+    // Cause an error to be thrown within a ReactJS lifecycle method
+    void triggerAComponentError() {
+      queryByTestId(jacket.getInstance(), 'flawedComponent_flawedButton').click();
+    }
+
+    void sharedSetup({String loggerName, bool shouldLogErrors = true, Logger customLogger}) {
+      calls = [];
+      jacket = mount(
+        (ErrorBoundary()
+          ..loggerName = loggerName
+          ..shouldLogErrors = shouldLogErrors
+          ..logger = customLogger
+          ..identicalErrorFrequencyTolerance = const Duration(milliseconds: identicalErrorFrequencyToleranceInMs)
+          ..onComponentDidCatch = (err, info) {
+            calls.add({'onComponentDidCatch': [err, info]});
+          }
+          ..onComponentIsUnrecoverable = (err, info) {
+            calls.add({'onComponentIsUnrecoverable': [err, info]});
+          }
+        )(Flawed()()),
+        attachedToDocument: true,
+      );
+
+      logRecords = [];
+      final subscription =
+          Logger(customLogger?.name ?? loggerName ?? defaultErrorBoundaryLoggerName).onRecord.listen(logRecords.add);
+      addTearDown(subscription.cancel);
+    }
+
+    tearDown(() {
+      logRecords = null;
+    });
+
+    test('when `props.shouldLogErrors` is false', () {
+      sharedSetup(shouldLogErrors: false);
+      triggerAComponentError();
+      expect(logRecords, isEmpty);
+    });
+
+    group('provided via `props.logger`', () {
+      test('', () {
+        sharedSetup(customLogger: Logger('myCustomLoggerLoggerName'));
+        triggerAComponentError();
+
+        expect(logRecords, hasLength(1));
+        expect(logRecords.single.level, Level.SEVERE);
+        expect(logRecords.single.loggerName, 'myCustomLoggerLoggerName');
+        expect(logRecords.single.error, calls.single['onComponentDidCatch'][0]);
+
+        ReactErrorInfo infoSentToCallback = calls.single['onComponentDidCatch'][1];
+        expect(logRecords.single.stackTrace, infoSentToCallback.dartStackTrace);
+        expect(logRecords.single.message, 'An error was caught by an ErrorBoundary:'
+            ' \nInfo: ${infoSentToCallback.componentStack}');
+      });
+
+      test('and `props.loggerName` is also set', () {
+        sharedSetup(loggerName: 'somethingElse', customLogger: Logger('myCustomLoggerLoggerName'));
+        triggerAComponentError();
+
+        expect(logRecords.single.loggerName, 'myCustomLoggerLoggerName');
+      });
+    });
+
+    group('when `props.loggerName` is not set', () {
+      setUp(sharedSetup);
+
+      test('and a component error is caught', () {
+        triggerAComponentError();
+
+        expect(logRecords, hasLength(1));
+        expect(logRecords.single.level, Level.SEVERE);
+        expect(logRecords.single.loggerName, defaultErrorBoundaryLoggerName);
+        expect(logRecords.single.error, calls.single['onComponentDidCatch'][0]);
+
+        ReactErrorInfo infoSentToCallback = calls.single['onComponentDidCatch'][1];
+        expect(logRecords.single.stackTrace, infoSentToCallback.dartStackTrace);
+        expect(logRecords.single.message, 'An error was caught by an ErrorBoundary:'
+            ' \nInfo: ${infoSentToCallback.componentStack}');
+      });
+
+      test('and an unrecoverable component error is caught', () async {
+        triggerAComponentError();
+        await Future.delayed(const Duration(milliseconds: identicalErrorFrequencyToleranceInMs ~/ 2));
+        triggerAComponentError();
+
+        expect(logRecords, hasLength(2));
+        expect(logRecords[1].level, Level.SEVERE);
+        expect(logRecords[1].loggerName, defaultErrorBoundaryLoggerName);
+        expect(logRecords[1].error, calls[2]['onComponentIsUnrecoverable'][0]);
+
+        ReactErrorInfo infoSentToCallback = calls[2]['onComponentIsUnrecoverable'][1];
+        expect(logRecords[1].stackTrace, infoSentToCallback.dartStackTrace);
+        expect(logRecords[1].message,
+            'An unrecoverable error was caught by an ErrorBoundary (attempting to remount it was unsuccessful):'
+            ' \nInfo: ${infoSentToCallback.componentStack}');
+      });
+
+      group('but then `props.loggerName` is set to a non-null value', () {
+        setUp(() {
+          Logger('myCustomErrorLoggerName').clearListeners();
+          jacket.rerender(
+            (ErrorBoundary()
+              ..loggerName = 'myCustomErrorLoggerName'
+              ..identicalErrorFrequencyTolerance = const Duration(milliseconds: identicalErrorFrequencyToleranceInMs)
+              ..onComponentDidCatch = (err, info) {
+                calls.add({'onComponentDidCatch': [err, info]});
+              }
+              ..onComponentIsUnrecoverable = (err, info) {
+                calls.add({'onComponentIsUnrecoverable': [err, info]});
+              }
+            )(Flawed()())
+          );
+          final subscription = Logger('myCustomErrorLoggerName').onRecord.listen(logRecords.add);
+          addTearDown(subscription.cancel);
+        });
+
+        test('and a component error is caught', () {
+          triggerAComponentError();
+
+          expect(logRecords.single.loggerName, 'myCustomErrorLoggerName');
+        });
+
+        group('and then to a null value', () {
+          setUp(() {
+            Logger(defaultErrorBoundaryLoggerName).clearListeners();
+            jacket.rerender(
+              (ErrorBoundary()
+                ..loggerName = null
+                ..identicalErrorFrequencyTolerance = const Duration(milliseconds: identicalErrorFrequencyToleranceInMs)
+                ..onComponentDidCatch = (err, info) {
+                  calls.add({'onComponentDidCatch': [err, info]});
+                }
+                ..onComponentIsUnrecoverable = (err, info) {
+                  calls.add({'onComponentIsUnrecoverable': [err, info]});
+                }
+              )(Flawed()())
+            );
+            final subscription = Logger(defaultErrorBoundaryLoggerName).onRecord.listen(logRecords.add);
+            addTearDown(subscription.cancel);
+          });
+
+          test('and a component error is caught', () {
+            triggerAComponentError();
+
+            expect(logRecords.single.loggerName, defaultErrorBoundaryLoggerName,
+                reason: 'The loggerName should fall back to `defaultErrorBoundaryLoggerName` '
+                        'if a consumer attempts to set it to null');
+          });
+        });
+      });
+    });
+  });
+
 //  group('throws a PropError when', () {
 //    test('more than one child is provided', () {
 //      expect(() => mount(builder()(dummyChild, dummyChild)),