Refactor core uses of FlutterError. #30983

jacob314 · 2019-04-12T21:29:41Z

Description

Make FlutterError objects more structured so they can be displayed better in debugging tools such as Dart DevTools.

Related Issues

Tests

Most tests pass as is as the text output does not change as the refactor does not break existing text based error displays.

New test cases are added in flutter_test to verify the structure is maintained and new tests are added to diagnostics_test.dart to verify that the additional text formatting logic works as expected.
Other test cases are updated for cases where the output changed in way that is minor and either completely neutral or positive.

Checklist

Before you create this PR confirm that it meets all requirements listed below by checking the relevant checkboxes ([x]). This will ensure a smooth and quick review process.

I read the [Contributor Guide] and followed the process outlined there for submitting PRs.
I signed the [CLA].
I read and followed the [Flutter Style Guide], including [Features we expect every widget to implement].
I updated/added relevant documentation (doc comments with ///).
All existing and new tests are passing.
The analyzer (flutter analyze --flutter-repo) does not report any problems on my PR.
I am willing to follow-up on review comments in a timely manner.

Breaking Change

Does your PR require Flutter developers to manually update their apps to accommodate your change?

Yes, this is a breaking change (Please read [Handling breaking changes]). https://groups.google.com/forum/#!topic/flutter-announce/hp1RNIgej38
No, this is not a breaking change.

jacob314 · 2019-04-12T23:34:28Z

This CL has only the core changes for the FlutterError refactor. Follow up CLs apply the refactor to more places. The diff is still large but take heart that a lot of the additions are just the text rendering logic and golden style tests in diagnosticable.dart.

Two follow up CLs will apply the refactor to more places.

pq

Couple of nits but looking great. 👍

pq · 2019-04-14T14:16:22Z

packages/flutter/lib/src/foundation/assertions.dart

+/// include hash codes.
+///
+/// A [FlutterError] must start with an [ErrorSummary] and may not contain
+/// multiple summaries.


I think this line needs updating?

Sorry can you clarify what about this line should be updated? It is still technically correct that every FlutterError starts with an ErrorSummary although sometimes the ErrorSummary is inferred parsing the text of the message.

Sorry, I wasn't clear. I just wondered if you wanted to remove the reference to the ErrorSummary type in favor of a string since that's what folks will be passing in. A not really so no worries either way!

packages/flutter/lib/src/foundation/assertions.dart

packages/flutter/lib/src/widgets/widget_inspector.dart

pq · 2019-04-14T14:26:36Z

packages/flutter/lib/src/widgets/widget_inspector.dart

@@ -1563,7 +1628,7 @@ mixin WidgetInspectorService {

  List<Object> _getProperties(String diagnosticsNodeId, String groupName) {
    final DiagnosticsNode node = toObject(diagnosticsNodeId);
-    return _nodesToJson(node == null ? const <DiagnosticsNode>[] : node.getProperties(), _SerializeConfig(groupName: groupName));
+    return _nodesToJson(node == null ? const <DiagnosticsNode>[] : node.getProperties(), _SerializeConfig(groupName: groupName), parent: null);


Should parent be node?

goderbauer

Looked at the stuff in foundation. Seems mostly fine with some nits.

goderbauer · 2019-04-18T00:29:54Z

packages/flutter/lib/src/foundation/assertions.dart

+  ///
+  /// {@tool sample}
+  /// ```dart
+  /// _ErrorDiagnostic('Element $element must be $color')


I don't see this _ErrorDiagnostic constructor defined anywhere? Is this supposed to be a placeholder for ErrorSummary, ErrorDetails or ErrorHint?

Might be worthwhile to point that out or use a concrete example.

I went ahead and added a default constructor for this class.

goderbauer · 2019-04-18T00:33:30Z

packages/flutter/lib/src/foundation/assertions.dart

+/// and other callbacks that collect information describing an error.
+typedef InformationCollector = Iterable<DiagnosticsNode> Function();
+
+class _ErrorDiagnostic extends DiagnosticsProperty<List<Object>> {


Should this be an abstract class? Or is it intended to be instantiated directly?

I've marked it as abstract to clarify that.

goderbauer · 2019-04-18T00:36:12Z

packages/flutter/lib/src/foundation/assertions.dart

+///   information, etc.
+/// * [FlutterError], which is the most common place to use an [ErrorHint].
+class ErrorHint extends _ErrorDiagnostic {
+  /// A lint enforces that this constructor can only be called with a string


Why's this not a limitation for the other Error* classes?

The limitation should apply to all these classes. Updated the documentation in all 3 similar classes to reflect that.

goderbauer · 2019-04-18T00:37:18Z

packages/flutter/lib/src/foundation/assertions.dart

+
+  /// Returns a short (one line) description of the problem that was detected.
+  ///
+  /// If the exception contains an [ErrorSummary] that summary is used otherwise


not 100% sure: Should there be some kind of punctuation before otherwise?

added a comma

goderbauer · 2019-04-18T00:41:06Z

packages/flutter/lib/src/foundation/diagnostics.dart

+  /// Render the tree on a single line without showing children.
+  ///
+  /// See also:
+  ///  * [FlutterErrorDetails], which uses this style to display the header


nit: missing blank line after "See also:"

goderbauer · 2019-04-18T00:42:04Z

packages/flutter/lib/src/foundation/diagnostics.dart

+  ///    describing the context where an error occurred.
+  headerLine,
+
+  /// Render the tree on a single line with the name and value on separate


This seems oxymoronic. How can it be a single line if name and value are presented on separate lines, which makes it at least two lines?

yes that is a bad name.
some alternate ideas:

whitespaceNoChildren <-- that is what it is

errorProperty <-- that is what it is for.

Fixed this. I've renamed this to errorProperty as that is what it is.

goderbauer · 2019-04-18T00:44:29Z

packages/flutter/lib/src/foundation/diagnostics.dart

@@ -178,6 +235,13 @@ class TextTreeConfiguration {
  /// Prefix to add to the first line to display a child with this style.
  final String prefixLineOne;

+  /// Similar to prefixLineOne but applies even when this is the root node in


It's unclear for me what this does based on the description.

Updated the comment and moved this next to the related afterName property.

goderbauer · 2019-04-18T00:47:36Z

packages/flutter/lib/src/foundation/diagnostics.dart

@@ -495,6 +638,41 @@ final TextTreeConfiguration whitespaceTextConfiguration = TextTreeConfiguration(
  isBlankLineBetweenPropertiesAndChildren: false,
 );

+/// Whitespace only configuration where children are consistently indented


Where are the two spaces coming from? The example below shows everything at the same indentation.

There is no indentation. Clearly I started with the comment from the whitespace style and failed to update it.

The comment was wrong. Fixed it. All the example diagrams were carefully constructed but some comments were out of sync with the content.

goderbauer · 2019-04-18T00:48:33Z

packages/flutter/lib/src/foundation/diagnostics.dart

+  prefixOtherLinesRootNode: '',
+);
+
+/// Render a node as a single line omitting children styling the node like it is


Can this be broken up in more than one runaway sentence to make it clearer what this does?

I've instead eliminated this style as the cases it was helping with are now handled by ErrorDescription instead which allows concatenating together strings and values to look like a header.

goderbauer · 2019-04-18T00:49:16Z

packages/flutter/lib/src/foundation/diagnostics.dart

  propertyPrefixIfChildren: '',
  propertyPrefixNoChildren: '',
  linkCharacter: '',
  prefixOtherLinesRootNode: '',
 );
+/// Render a node as a single line omitting children.


The example below has two lines?

Done. Updated the description and renamed to
errorProperty

Updated the description to match the example.

InMatrix · 2019-04-18T19:23:43Z

dev/integration_tests/image_loading/lib/main.dart

@@ -16,7 +16,7 @@ void main() {
    handleUncaughtError:(Zone zone, ZoneDelegate delegate, Zone parent, Object error, StackTrace stackTrace) {
    FlutterError.reportError(FlutterErrorDetails(
      exception: error,
-      context: 'In the Zone handleUncaughtError handler',
+      context: ErrorDescription('In the Zone handleUncaughtError handler'),


I don't understand what this message is saying, but since it's the same as it was before. Let's land it for now and revise later.

I'm putting together a list of burndown errors to go after after this CL lands. I've added this to the list.

the context is just telling you where the error occurred, not what the error is (that's error).

correct. Removed this one from the burndown list.

InMatrix · 2019-04-18T19:31:57Z

packages/flutter/lib/src/foundation/assertions.dart

+/// An [ErrorHint] provides specific, non-obvious advice that may be applicable.
+///
+/// If your message provides obvious advice that is always applicable it is an
+/// [ErrorDescription] not a hint.


If the advice is obvious from the summary/description of the error, it probably should not be included in the message? I feel this line is a bit extranous.

I do like having the advice duplicated here as a reminder to only use hints for things that meet the fairly narrow charter of what a hint is.

InMatrix · 2019-04-18T19:36:30Z

packages/flutter/lib/src/foundation/change_notifier.dart

+                'The $runtimeType sending notification was',
+                this,
+                style: DiagnosticsTreeStyle.errorProperty,
+              );


What would be the ErrorSummary for this error, since it's not specified?

The exception is the piece that is expected to contain an ErrorSummary.
If the exception is a FlutterError we have assertions if it doesn't have an ErrorSummary.
We could be smart and if the exception is just a String, treat that String as an ErrorSummary.

InMatrix · 2019-04-18T19:46:38Z

packages/flutter/lib/src/rendering/box.dart

@@ -524,27 +527,27 @@ class BoxConstraints extends Constraints {
        } else {
          whichFields = affectedFieldsList.single;
        }
-        throwError('BoxConstraints has ${affectedFieldsList.length == 1 ? 'a NaN value' : 'NaN values' } in $whichFields.');
+        throwError(ErrorSummary('BoxConstraints has ${affectedFieldsList.length == 1 ? 'a NaN value' : 'NaN values' } in $whichFields.'));


Maybe we should spell out 'NaN' to make the message more beginner friendly.

Added that to the list of items to cleanup with a followup CL.

InMatrix · 2019-04-18T19:49:07Z

packages/flutter/lib/src/rendering/box.dart

        if (owner != null && owner.debugDoingLayout)
-          hint = 'Only the object itself can set its size. It is a contract violation for other objects to set it.';
+          information.add(ErrorHint('Only the object itself can set its size. It is a contract violation for other objects to set it.'));


This one looks more like a description. It backs up the previous statement. A hint should suggest a specific way to get out of the error state.

Agreed. I was on the fence about that one. I only had it as a "hint" as the variable name was called "hint" in the previous code.
While auditing this myself I set this as a ErrorDescription and then moved it back to a hint.

InMatrix · 2019-04-18T19:57:21Z

packages/flutter/lib/src/rendering/box.dart

+          ErrorHint(
+            'This probably means that it is a render object that tries to be '
+            'as big as possible, but it was put inside another render object '
+            'that allows its children to pick their own size.'


This looks like an ErrorDescription, too. To add a hint, what advice could we give someone who runs into this error? Would something like "try giving a finite size to the render object [link to documentation]" be useful as a hint here?

Switched to a description. Added to my list of things that could be nice to have a hint.

InMatrix · 2019-04-18T20:00:36Z

packages/flutter/lib/src/rendering/box.dart

-          '$runtimeType object was given an infinite size during layout.\n'
+        final List<DiagnosticsNode> errorParts = <DiagnosticsNode>[];
+        errorParts.add(ErrorSummary('$runtimeType object was given an infinite size during layout.'));
+        errorParts.add(ErrorHint(
          'This probably means that it is a render object that tries to be '
          'as big as possible, but it was put inside another render object '


I noticed this message is the same as the one in L1732. I'm not sure if this is a problem or not. Please see my comment there about whether this qualifies as a hint.

Downgraded this one as well.

also noted that it would be nice to dedupe the text.

InMatrix · 2019-04-18T20:02:47Z

packages/flutter/lib/src/rendering/box.dart

+        errorParts.addAll(information);
+        errorParts.add(DiagnosticsProperty<BoxConstraints>('The constraints that applied to the $runtimeType were', constraints, style: DiagnosticsTreeStyle.errorProperty));
+        errorParts.add(DiagnosticsProperty<Size>('The exact size it was given was', _size, style: DiagnosticsTreeStyle.errorProperty));
+        errorParts.add(ErrorHint('See https://flutter.io/layout/ for more information.'));


This is very clearly a hint, though probably not specific enough. The new canonical URL for this doc is https://flutter.dev/docs/development/ui/layout/box-constraints.

updated the doc link. done.

InMatrix · 2019-04-18T20:12:27Z

packages/flutter/lib/src/rendering/box.dart

-          'your fault. Contact support: https://github.com/flutter/flutter/issues/new?template=BUG.md'
-        );
+        throw FlutterError.fromParts(<DiagnosticsNode>[
+          ErrorSummary('$runtimeType does not meet its constraints.'),


A side question: will the user be able to locate this particular widget in their code, especially when there are many instances of this type?

They will be as soon as the kernel transformer for ErrorSummary is enabled, click on the type name in the UI will lead you to the RenderObject matching the type in the inspector.

Sounds good

InMatrix · 2019-04-18T20:17:41Z

packages/flutter/lib/src/rendering/debug_overflow_indicator.dart

@@ -232,18 +239,22 @@ mixin DebugOverflowIndicatorMixin on RenderObject {
        overflows[overflows.length - 1] = 'and ${overflows[overflows.length - 1]}';
        overflowText = overflows.join(', ');
    }
+    // TODO(jacobr): add the overflows in pixels as structured data so they can
+    // be visualized in debugging tools.
    FlutterError.reportError(
      FlutterErrorDetailsForRendering(
        exception: 'A $runtimeType overflowed by $overflowText.',


Should this line be the error's summary?

Wow. We shouldn't have exceptions that are strings. @pq we should probably add a lint to catch this case although it is low priority because the good news is this is the only place in the framework where that mistake was made.

Fixed this to construct a proper FlutterError object with a summary. The reason for this bug is the Dart type system lacks a single base class for all exceptions.

InMatrix · 2019-04-18T20:19:14Z

packages/flutter/lib/src/rendering/debug_overflow_indicator.dart

+        'The edge of the $runtimeType that is '
+        'overflowing has been marked in the rendering with a yellow and black '
+        'striped pattern. This is usually caused by the contents being too big '
+        'for the $runtimeType.'


I'd consider this part as an ErrorDescription.

InMatrix · 2019-04-18T20:19:48Z

packages/flutter/lib/src/rendering/debug_overflow_indicator.dart

+        'is content that cannot be seen. If the content is legitimately bigger '
+        'than the available space, consider clipping it with a ClipRect widget '
+        'before putting it in the $runtimeType, or using a scrollable '
+        'container, like a ListView.'


I agree that this part is a hint.

InMatrix · 2019-04-18T20:29:29Z

packages/flutter/lib/src/rendering/flex.dart

+           ..add(ErrorHint(
+             'If none of the above helps enough to fix this problem, please don\'t hesitate to file a bug:\n'
+             '  https://github.com/flutter/flutter/issues/new?template=BUG.md'
+          )));


This last part is neither a hint nor a description, following our definitions. I suggest we treat this as a description for now to avoid drawing undeserving attention to it. We should probably track how often this error reporting link is collected, maybe we can set up a URL redirect via flutter.dev.

Agreed. Made it a description.

InMatrix · 2019-04-18T21:51:17Z

packages/flutter/lib/src/rendering/flex.dart

+          'The edge of the $runtimeType that is overflowing has been marked '
+          'in the rendering with a yellow and black striped pattern. This is '
+          'usually caused by the contents being too big for the $runtimeType. '
+          'Consider applying a flex factor (e.g. using an Expanded widget) to '


The hint starts from this line. I'd consider the three lines above it a description of the error.

InMatrix · 2019-04-18T21:55:49Z

packages/flutter/lib/src/rendering/sliver.dart

        if (owner != null && owner.debugDoingLayout)
-          hint = 'Only the object itself can set its geometry. It is a contract violation for other objects to set it.';
+          hint = ErrorHint('Only the object itself can set its geometry. It is a contract violation for other objects to set it.');


I'd consider this a description, since it's unclear what the user should try to resolve the error.

@Hixie it looks like you wrote the line that originally gave this the variable name hint.
Do you think it should be called a hint with the current definition of what a hint is?

To make it clearer what action to take we could write something a bit redundant like.
Look for where the geometry is being set outside outside the object refactor the logic to set the geometry from inside the object.
For now set this as an ErrorDescription as
hint = ErrorDescription(
is a great breadcrumb to later go back and cleanup ErrorDescription objects.

InMatrix · 2019-04-18T23:56:12Z

packages/flutter_test/lib/src/test_async_utils.dart

      if (collidingGuarder.className == null && collidingGuarder.methodName == 'expect') {
-        message.writeln(
+        information.add(ErrorHint(
          'If you are confident that all test APIs are being called using "await", and '
          'this expect() call is not being called at the top level but is itself being '
          'called from some sort of callback registered before the ${originalGuarder.methodName} '
          'method was called, then consider using expectSync() instead.'


I agree this is a hint.

InMatrix · 2019-04-19T00:01:49Z

Looks good to me. Thanks!

jacob314 · 2019-04-19T15:05:12Z

All comments have been addressed. Please take another look.
Thanks!

Hixie · 2019-04-19T23:37:20Z

packages/flutter/lib/src/foundation/assertions.dart

+// Examples can assume:
+// dynamic element;
+// dynamic color;
+// dynamic _ErrorDiagnostic;


this makes it visible to all dartdocs everywhere. Since the relevant class is private anyway, might be worth making it // docs instead of /// docs.

Done. Made the problem comment a // comment as it isn't for public docs anyway.

googlebot added the cla: yes label Apr 12, 2019

jacob314 force-pushed the structured_error_stripped branch from 1791396 to 2b717a3 Compare April 12, 2019 23:21

jacob314 requested review from goderbauer and pq April 12, 2019 23:30

jacob314 mentioned this pull request Apr 12, 2019

Refactor all uses of FlutterError. #30925

Closed

9 tasks

jacob314 force-pushed the structured_error_stripped branch 2 times, most recently from ff14f3f to 3439a0a Compare April 13, 2019 18:31

pq approved these changes Apr 14, 2019

View reviewed changes

goderbauer added the framework flutter/packages/flutter repository. See also f: labels. label Apr 15, 2019

jacob314 force-pushed the structured_error_stripped branch 5 times, most recently from 4bb7820 to 0cfbf7a Compare April 17, 2019 20:07

goderbauer reviewed Apr 18, 2019

View reviewed changes

jacob314 force-pushed the structured_error_stripped branch from 304560a to a5fd4c6 Compare April 18, 2019 17:50

InMatrix reviewed Apr 18, 2019

View reviewed changes

jacob314 force-pushed the structured_error_stripped branch from ff43c2d to ceed498 Compare April 19, 2019 15:04

InMatrix approved these changes Apr 19, 2019

View reviewed changes

Hixie reviewed Apr 19, 2019

View reviewed changes

Refactor core uses of FlutterError. #30983

Refactor core uses of FlutterError. #30983

Conversation

jacob314 commented Apr 12, 2019 • edited Loading

Description

Related Issues

Tests

Checklist

Breaking Change

jacob314 commented Apr 12, 2019

pq left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

goderbauer left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

InMatrix Apr 18, 2019 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

InMatrix Apr 18, 2019 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

InMatrix Apr 18, 2019 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

InMatrix Apr 18, 2019 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

jacob314 commented Apr 12, 2019 •

edited

Loading

InMatrix Apr 18, 2019 •

edited

Loading

InMatrix Apr 18, 2019 •

edited

Loading

InMatrix Apr 18, 2019 •

edited

Loading

InMatrix Apr 18, 2019 •

edited

Loading