Splitting golden file versioning out as an argument of matchesGoldenFile (#33880)

* Splitting golden file versioning out as an argument of matchesGoldenFile

* Fixing description implementation.

* Removing unused imports

* Removing unused import

* Review feedback

packages/flutter/test/cupertino/date_picker_test.dart

@@ -843,7 +843,10 @@ void main() {
 
       await expectLater(
         find.byType(CupertinoDatePicker),
-        matchesGoldenFile('date_picker_test.datetime.initial.1.png'),
+        matchesGoldenFile(
+          'date_picker_test.datetime.initial.png',
+          version: 1,
+        ),
         skip: !isLinux
       );
 
@@ -853,7 +856,10 @@ void main() {
 
       await expectLater(
         find.byType(CupertinoDatePicker),
-        matchesGoldenFile('date_picker_test.datetime.drag.1.png'),
+        matchesGoldenFile(
+          'date_picker_test.datetime.drag.png',
+          version: 1,
+        ),
         skip: !isLinux
       );
     });

packages/flutter/test/cupertino/nav_bar_test.dart

@@ -799,7 +799,10 @@ void main() {
 
       await expectLater(
         find.byType(RepaintBoundary).last,
-        matchesGoldenFile('nav_bar_test.standard_title.1.png'),
+        matchesGoldenFile(
+          'nav_bar_test.standard_title.png',
+          version: 1,
+        ),
       );
     },
     // TODO(xster): remove once https://github.com/flutter/flutter/issues/17483
@@ -833,7 +836,10 @@ void main() {
 
       await expectLater(
         find.byType(RepaintBoundary).last,
-        matchesGoldenFile('nav_bar_test.large_title.1.png'),
+        matchesGoldenFile(
+          'nav_bar_test.large_title.png',
+          version: 1,
+        ),
       );
     },
     // TODO(xster): remove once https://github.com/flutter/flutter/issues/17483

packages/flutter/test/cupertino/segmented_control_test.dart

@@ -1412,7 +1412,10 @@ void main() {
 
     await expectLater(
       find.byType(RepaintBoundary),
-      matchesGoldenFile('segmented_control_test.0.0.png'),
+      matchesGoldenFile(
+        'segmented_control_test.0.png',
+        version: 0,
+      ),
     );
   }, skip: !isLinux);
 
@@ -1450,7 +1453,10 @@ void main() {
 
     await expectLater(
       find.byType(RepaintBoundary),
-      matchesGoldenFile('segmented_control_test.1.0.png'),
+      matchesGoldenFile(
+        'segmented_control_test.1.png',
+        version: 0,
+      ),
     );
   }, skip: !isLinux);
 }

packages/flutter/test/cupertino/text_field_test.dart

@@ -373,7 +373,10 @@ void main() {
 
     await expectLater(
       find.byKey(const ValueKey<int>(1)),
-      matchesGoldenFile('text_field_cursor_test.cupertino.0.2.png'),
+      matchesGoldenFile(
+        'text_field_cursor_test.cupertino.0.png',
+        version: 2,
+      ),
     );
   }, skip: !isLinux);
 
@@ -403,7 +406,10 @@ void main() {
     debugDefaultTargetPlatformOverride = null;
     await expectLater(
       find.byKey(const ValueKey<int>(1)),
-      matchesGoldenFile('text_field_cursor_test.cupertino.1.2.png'),
+      matchesGoldenFile(
+        'text_field_cursor_test.cupertino.1.png',
+        version: 2,
+      ),
     );
   }, skip: !isLinux);
 
@@ -2675,7 +2681,10 @@ void main() {
 
     await expectLater(
       find.byType(CupertinoTextField),
-      matchesGoldenFile('text_field_test.disabled.0.png'),
+      matchesGoldenFile(
+        'text_field_test.disabled.png',
+        version: 0,
+      ),
       skip: !isLinux,
     );
   });

packages/flutter/test/material/bottom_app_bar_test.dart

@@ -2,8 +2,6 @@
 // Use of this source code is governed by a BSD-style license that can be
 // found in the LICENSE file.
 
-import 'dart:io';
-
 import 'package:flutter_test/flutter_test.dart';
 import 'package:flutter/material.dart';
 import 'package:flutter/rendering.dart';
@@ -73,15 +71,21 @@ void main() {
     await pump(FloatingActionButtonLocation.endDocked);
     await expectLater(
       find.byKey(key),
-      matchesGoldenFile('bottom_app_bar.custom_shape.1.png'),
-      skip: !Platform.isLinux,
+      matchesGoldenFile(
+        'bottom_app_bar.custom_shape.1.png',
+        version: null,
+      ),
+      skip: !isLinux,
     );
     await pump(FloatingActionButtonLocation.centerDocked);
     await tester.pumpAndSettle();
     await expectLater(
       find.byKey(key),
-      matchesGoldenFile('bottom_app_bar.custom_shape.2.png'),
-      skip: !Platform.isLinux,
+      matchesGoldenFile(
+        'bottom_app_bar.custom_shape.2.png',
+        version: null,
+      ),
+      skip: !isLinux,
     );
   }, skip: isBrowser);
 

packages/flutter/test/material/bottom_app_bar_theme_test.dart

@@ -80,7 +80,10 @@ void main() {
 
     await expectLater(
       find.byKey(_painterKey),
-      matchesGoldenFile('bottom_app_bar_theme.custom_shape.png'),
+      matchesGoldenFile(
+        'bottom_app_bar_theme.custom_shape.png',
+        version: null,
+      ),
       skip: !isLinux,
     );
   }, skip: isBrowser);

packages/flutter/test/material/bottom_navigation_bar_test.dart

@@ -1434,7 +1434,10 @@ void main() {
       await tester.pump(const Duration(milliseconds: 30));
       await expectLater(
         find.byType(BottomNavigationBar),
-        matchesGoldenFile('bottom_navigation_bar.shifting_transition.$pump.2.png'),
+        matchesGoldenFile(
+          'bottom_navigation_bar.shifting_transition.$pump.png',
+          version: 2,
+        ),
         skip: !isLinux,
       );
     }

packages/flutter/test/material/card_theme_test.dart

@@ -137,7 +137,10 @@ void main() {
 
     await expectLater(
       find.byKey(painterKey),
-      matchesGoldenFile('card_theme.custom_shape.png'),
+      matchesGoldenFile(
+        'card_theme.custom_shape.png',
+        version: null,
+      ),
       skip: !isLinux,
     );
   },  skip: isBrowser);

packages/flutter/test/material/dialog_theme_test.dart

@@ -130,7 +130,10 @@ void main() {
 
     await expectLater(
       find.byKey(_painterKey),
-      matchesGoldenFile('dialog_theme.dialog_with_custom_border.png'),
+      matchesGoldenFile(
+        'dialog_theme.dialog_with_custom_border.png',
+        version: null,
+      ),
       skip: !isLinux,
     );
   }, skip: isBrowser);

packages/flutter/test/material/dropdown_test.dart

@@ -140,7 +140,10 @@ void main() {
     assert(tester.renderObject(buttonFinder).attached);
     await expectLater(
       find.ancestor(of: buttonFinder, matching: find.byType(RepaintBoundary)).first,
-      matchesGoldenFile('dropdown_test.default.0.png'),
+      matchesGoldenFile(
+        'dropdown_test.default.png',
+        version: 0,
+      ),
       skip: !isLinux,
     );
   }, skip: isBrowser);
@@ -153,7 +156,10 @@ void main() {
     assert(tester.renderObject(buttonFinder).attached);
     await expectLater(
       find.ancestor(of: buttonFinder, matching: find.byType(RepaintBoundary)).first,
-      matchesGoldenFile('dropdown_test.expanded.0.png'),
+      matchesGoldenFile(
+        'dropdown_test.expanded.png',
+        version: 0,
+      ),
       skip: !isLinux,
     );
   }, skip: isBrowser);

packages/flutter/test/material/floating_action_button_test.dart

@@ -736,7 +736,10 @@ void main() {
     await tester.pump(const Duration(milliseconds: 1000));
     await expectLater(
       find.byKey(key),
-      matchesGoldenFile('floating_action_button_test.clip.2.png'), // .clip.1.png is obsolete and can be removed
+      matchesGoldenFile(
+        'floating_action_button_test.clip.png',
+        version: 2,
+      ),
       skip: !isLinux,
     );
   });

packages/flutter/test/material/input_decorator_test.dart

@@ -2030,14 +2030,20 @@ void main() {
       await tester.pumpWidget(buildFrame(TextDirection.ltr));
       await expectLater(
         find.byType(InputDecorator),
-        matchesGoldenFile('input_decorator.outline_icon_label.ltr.png'),
+        matchesGoldenFile(
+          'input_decorator.outline_icon_label.ltr.png',
+          version: null,
+        ),
         skip: !isLinux,
       );
 
       await tester.pumpWidget(buildFrame(TextDirection.rtl));
       await expectLater(
         find.byType(InputDecorator),
-        matchesGoldenFile('input_decorator.outline_icon_label.rtl.png'),
+        matchesGoldenFile(
+          'input_decorator.outline_icon_label.rtl.png',
+          version: null,
+        ),
         skip: !isLinux,
       );
     },

packages/flutter/test/material/material_test.dart

@@ -616,7 +616,10 @@ void main() {
 
       await expectLater(
         find.byKey(painterKey),
-        matchesGoldenFile('material.border_paint_above.png'),
+        matchesGoldenFile(
+          'material.border_paint_above.png',
+          version: null,
+        ),
         skip: !isLinux,
       );
     }, skip: isBrowser);
@@ -657,7 +660,10 @@ void main() {
 
       await expectLater(
         find.byKey(painterKey),
-        matchesGoldenFile('material.border_paint_below.png'),
+        matchesGoldenFile(
+          'material.border_paint_below.png',
+          version: null,
+        ),
         skip: !isLinux,
       );
     }, skip: isBrowser);

packages/flutter/test/material/radio_test.dart

@@ -276,7 +276,10 @@ void main() {
     await tester.pumpAndSettle();
     await expectLater(
       find.byKey(painterKey),
-      matchesGoldenFile('radio.ink_ripple.png'),
+      matchesGoldenFile(
+        'radio.ink_ripple.png',
+        version: null,
+      ),
       skip: !isLinux,
     );
   }, skip: isBrowser);

packages/flutter/test/material/tab_bar_theme_test.dart

@@ -267,7 +267,10 @@ void main() {
 
     await expectLater(
       find.byKey(_painterKey),
-      matchesGoldenFile('tab_bar_theme.tab_indicator_size_tab.png'),
+      matchesGoldenFile(
+        'tab_bar_theme.tab_indicator_size_tab.png',
+        version: null,
+      ),
       skip: !isLinux,
     );
   }, skip: isBrowser);
@@ -279,7 +282,10 @@ void main() {
 
     await expectLater(
       find.byKey(_painterKey),
-      matchesGoldenFile('tab_bar_theme.tab_indicator_size_label.png'),
+      matchesGoldenFile(
+        'tab_bar_theme.tab_indicator_size_label.png',
+        version: null,
+      ),
       skip: !isLinux,
     );
   }, skip: isBrowser);
@@ -296,7 +302,10 @@ void main() {
 
     await expectLater(
       find.byKey(_painterKey),
-      matchesGoldenFile('tab_bar_theme.custom_tab_indicator.png'),
+      matchesGoldenFile(
+        'tab_bar_theme.custom_tab_indicator.png',
+        version: null,
+      ),
       skip: !isLinux,
     );
   }, skip: isBrowser);
@@ -313,7 +322,10 @@ void main() {
 
     await expectLater(
       find.byKey(_painterKey),
-      matchesGoldenFile('tab_bar_theme.beveled_rect_indicator.png'),
+      matchesGoldenFile(
+        'tab_bar_theme.beveled_rect_indicator.png',
+        version: null,
+      ),
       skip: !isLinux,
     );
   }, skip: isBrowser);

packages/flutter/test/material/text_field_test.dart

@@ -408,7 +408,10 @@ void main() {
 
     await expectLater(
       find.byKey(const ValueKey<int>(1)),
-      matchesGoldenFile('text_field_cursor_test.material.0.0.png'),
+      matchesGoldenFile(
+        'text_field_cursor_test.material.0.png',
+        version: 0,
+      ),
     );
   }, skip: !isLinux);
 
@@ -437,7 +440,10 @@ void main() {
     debugDefaultTargetPlatformOverride = null;
     await expectLater(
       find.byKey(const ValueKey<int>(1)),
-      matchesGoldenFile('text_field_cursor_test.material.1.0.png'),
+      matchesGoldenFile(
+        'text_field_cursor_test.material.1.png',
+        version: 0,
+      ),
     );
   }, skip: !isLinux);
 
@@ -488,7 +494,10 @@ void main() {
     await expectLater(
       // The toolbar exists in the Overlay above the MaterialApp.
       find.byType(Overlay),
-      matchesGoldenFile('text_field_opacity_test.0.2.png'),
+      matchesGoldenFile(
+        'text_field_opacity_test.0.png',
+        version: 2,
+      ),
       skip: !isLinux,
     );
   }, skip: isBrowser);

packages/flutter/test/painting/continous_rectangle_border_test.dart

@@ -71,7 +71,10 @@ void main() {
 
     await expectLater(
       find.byType(RepaintBoundary),
-      matchesGoldenFile('continuous_rectangle_border.golden_test_even_radii.png'),
+      matchesGoldenFile(
+        'continuous_rectangle_border.golden_test_even_radii.png',
+        version: null,
+      ),
       skip: !isLinux,
     );
   }, skip: isBrowser);
@@ -93,7 +96,10 @@ void main() {
 
     await expectLater(
       find.byType(RepaintBoundary),
-      matchesGoldenFile('continuous_rectangle_border.golden_test_varying_radii.png'),
+      matchesGoldenFile(
+        'continuous_rectangle_border.golden_test_varying_radii.png',
+        version: null,
+      ),
       skip: !isLinux,
     );
   }, skip: isBrowser);
@@ -112,7 +118,10 @@ void main() {
 
     await expectLater(
       find.byType(RepaintBoundary),
-      matchesGoldenFile('continuous_rectangle_border.golden_test_large_radii.png'),
+      matchesGoldenFile(
+        'continuous_rectangle_border.golden_test_large_radii.png',
+        version: null,
+      ),
       skip: !isLinux,
     );
   }, skip: isBrowser);

packages/flutter/test/rendering/localized_fonts_test.dart

@@ -49,7 +49,10 @@ void main() {
 
       await expectLater(
         find.byType(RichText),
-        matchesGoldenFile('localized_fonts.rich_text.styled_text_span.png'),
+        matchesGoldenFile(
+          'localized_fonts.rich_text.styled_text_span.png',
+          version: null,
+        ),
       );
     },
     skip: !isLinux,
@@ -101,7 +104,10 @@ void main() {
 
       await expectLater(
         find.byType(Row),
-        matchesGoldenFile('localized_fonts.text_ambient_locale.chars.png'),
+        matchesGoldenFile(
+          'localized_fonts.text_ambient_locale.chars.png',
+          version: null,
+        ),
       );
     },
     skip: !isLinux,
@@ -145,7 +151,10 @@ void main() {
 
       await expectLater(
         find.byType(Row),
-        matchesGoldenFile('localized_fonts.text_explicit_locale.chars.png'),
+        matchesGoldenFile(
+          'localized_fonts.text_explicit_locale.chars.png',
+          version: null,
+        ),
       );
     },
     skip: !isLinux,

packages/flutter/test/widgets/backdrop_filter_test.dart

@@ -43,7 +43,10 @@ void main() {
     );
     await expectLater(
       find.byType(RepaintBoundary).first,
-      matchesGoldenFile('backdrop_filter_test.cull_rect.1.png'),
+      matchesGoldenFile(
+        'backdrop_filter_test.cull_rect.png',
+        version: 1,
+      ),
       skip: !isLinux,
     );
   }, skip: isBrowser);

packages/flutter/test/widgets/clip_test.dart

@@ -356,7 +356,10 @@ void main() {
     );
     await expectLater(
       find.byType(RepaintBoundary).first,
-      matchesGoldenFile('clip.ClipRect.1.png'),
+      matchesGoldenFile(
+        'clip.ClipRect.png',
+        version: 1,
+      ),
     );
   }, skip: isBrowser);
 
@@ -396,7 +399,10 @@ void main() {
     );
     await expectLater(
       find.byType(RepaintBoundary).first,
-      matchesGoldenFile('clip.ClipRectOverlay.1.png'),
+      matchesGoldenFile(
+        'clip.ClipRectOverlay.png',
+        version: 1,
+      ),
     );
   }, skip: isBrowser);
 
@@ -445,7 +451,10 @@ void main() {
     );
     await expectLater(
       find.byType(RepaintBoundary).first,
-      matchesGoldenFile('clip.ClipRRect.1.png'),
+      matchesGoldenFile(
+        'clip.ClipRRect.png',
+        version: 1,
+      ),
     );
   }, skip: isBrowser);
 
@@ -488,7 +497,10 @@ void main() {
     );
     await expectLater(
       find.byType(RepaintBoundary).first,
-      matchesGoldenFile('clip.ClipOval.1.png'),
+      matchesGoldenFile(
+        'clip.ClipOval.png',
+        version: 1,
+      ),
     );
   }, skip: isBrowser);
 
@@ -536,7 +548,10 @@ void main() {
     );
     await expectLater(
       find.byType(RepaintBoundary).first,
-      matchesGoldenFile('clip.ClipPath.1.png'),
+      matchesGoldenFile(
+        'clip.ClipPath.png',
+        version: 1,
+      ),
     );
   }, skip: isBrowser);
 
@@ -581,7 +596,10 @@ void main() {
     await tester.pumpWidget(genPhysicalModel(Clip.antiAlias));
     await expectLater(
       find.byType(RepaintBoundary).first,
-      matchesGoldenFile('clip.PhysicalModel.antiAlias.1.png'),
+      matchesGoldenFile(
+        'clip.PhysicalModel.antiAlias.png',
+        version: 1,
+      ),
     );
   }, skip: isBrowser);
 
@@ -589,7 +607,10 @@ void main() {
     await tester.pumpWidget(genPhysicalModel(Clip.hardEdge));
     await expectLater(
       find.byType(RepaintBoundary).first,
-      matchesGoldenFile('clip.PhysicalModel.hardEdge.1.png'),
+      matchesGoldenFile(
+        'clip.PhysicalModel.hardEdge.png',
+        version: 1,
+      ),
     );
   }, skip: isBrowser);
 
@@ -599,7 +620,10 @@ void main() {
     await tester.pumpWidget(genPhysicalModel(Clip.antiAliasWithSaveLayer));
     await expectLater(
       find.byType(RepaintBoundary).first,
-      matchesGoldenFile('clip.PhysicalModel.antiAliasWithSaveLayer.png'),
+      matchesGoldenFile(
+        'clip.PhysicalModel.antiAliasWithSaveLayer.png',
+        version: null,
+      ),
     );
   }, skip: isBrowser);
 
@@ -641,7 +665,10 @@ void main() {
     );
     await expectLater(
       find.byType(RepaintBoundary).first,
-      matchesGoldenFile('clip.PhysicalModel.default.1.png'),
+      matchesGoldenFile(
+        'clip.PhysicalModel.default.png',
+        version: 1,
+      ),
     );
   }, skip: isBrowser);
 
@@ -690,7 +717,10 @@ void main() {
     await tester.pumpWidget(genPhysicalShape(Clip.antiAlias));
     await expectLater(
       find.byType(RepaintBoundary).first,
-      matchesGoldenFile('clip.PhysicalShape.antiAlias.1.png'),
+      matchesGoldenFile(
+        'clip.PhysicalShape.antiAlias.png',
+        version: 1,
+      ),
     );
   }, skip: isBrowser);
 
@@ -698,7 +728,10 @@ void main() {
     await tester.pumpWidget(genPhysicalShape(Clip.hardEdge));
     await expectLater(
       find.byType(RepaintBoundary).first,
-      matchesGoldenFile('clip.PhysicalShape.hardEdge.1.png'),
+      matchesGoldenFile(
+        'clip.PhysicalShape.hardEdge.png',
+        version: 1,
+      ),
     );
   }, skip: isBrowser);
 
@@ -706,7 +739,10 @@ void main() {
     await tester.pumpWidget(genPhysicalShape(Clip.antiAliasWithSaveLayer));
     await expectLater(
       find.byType(RepaintBoundary).first,
-      matchesGoldenFile('clip.PhysicalShape.antiAliasWithSaveLayer.png'),
+      matchesGoldenFile(
+        'clip.PhysicalShape.antiAliasWithSaveLayer.png',
+        version: null,
+      ),
     );
   }, skip: isBrowser);
 
@@ -752,7 +788,10 @@ void main() {
     );
     await expectLater(
       find.byType(RepaintBoundary).first,
-      matchesGoldenFile('clip.PhysicalShape.default.1.png'),
+      matchesGoldenFile(
+        'clip.PhysicalShape.default.png',
+        version: 1,
+      ),
     );
   }, skip: isBrowser);
 

packages/flutter/test/widgets/editable_text_cursor_test.dart

@@ -90,7 +90,10 @@ void main() {
 
     await expectLater(
       find.byKey(const ValueKey<int>(1)),
-      matchesGoldenFile('editable_text_test.0.3.png'),
+      matchesGoldenFile(
+        'editable_text_test.0.png',
+        version: 3,
+      ),
     );
   }, skip: !isLinux);
 
@@ -141,7 +144,10 @@ void main() {
 
     await expectLater(
       find.byKey(const ValueKey<int>(1)),
-      matchesGoldenFile('editable_text_test.1.3.png'),
+      matchesGoldenFile(
+        'editable_text_test.1.png',
+        version: 3,
+      ),
     );
   }, skip: !isLinux);
 
@@ -747,7 +753,10 @@ void main() {
 
     await expectLater(
       find.byKey(const ValueKey<int>(1)),
-      matchesGoldenFile('editable_text_test.2.0.png'),
+      matchesGoldenFile(
+        'editable_text_test.2.png',
+        version: 0,
+      ),
     );
     debugDefaultTargetPlatformOverride = null;
   }, skip: !isLinux);

packages/flutter/test/widgets/invert_colors_test.dart

@@ -20,7 +20,10 @@ void main() {
 
     await expectLater(
       find.byType(RepaintBoundary),
-      matchesGoldenFile('invert_colors_test.0.png'),
+      matchesGoldenFile(
+        'invert_colors_test.0.png',
+        version: null,
+      ),
       skip: !isLinux,
     );
   }, skip: isBrowser);
@@ -39,7 +42,10 @@ void main() {
 
     await expectLater(
       find.byType(RepaintBoundary),
-      matchesGoldenFile('invert_colors_test.1.png'),
+      matchesGoldenFile(
+        'invert_colors_test.1.png',
+        version: null,
+      ),
       skip: !isLinux,
     );
   }, skip: isBrowser);

packages/flutter/test/widgets/list_wheel_scroll_view_test.dart

@@ -535,7 +535,10 @@ void main() {
 
       await expectLater(
         find.byKey(const Key('list_wheel_scroll_view')),
-        matchesGoldenFile('list_wheel_scroll_view.center_child.magnified.png'),
+        matchesGoldenFile(
+          'list_wheel_scroll_view.center_child.magnified.png',
+          version: null,
+        ),
         skip: !isLinux,
       );
     }, skip: isBrowser);
@@ -590,7 +593,10 @@ void main() {
 
       await expectLater(
         find.byKey(const Key('list_wheel_scroll_view')),
-        matchesGoldenFile('list_wheel_scroll_view.curved_wheel.left.png'),
+        matchesGoldenFile(
+          'list_wheel_scroll_view.curved_wheel.left.png',
+          version: null,
+        ),
         skip: !isLinux,
       );
     }, skip: isBrowser);

packages/flutter/test/widgets/opacity_test.dart

@@ -177,7 +177,10 @@ void main() {
     );
     await expectLater(
       find.byType(RepaintBoundary).first,
-      matchesGoldenFile('opacity_test.offset.1.png'),
+      matchesGoldenFile(
+        'opacity_test.offset.png',
+        version: 1,
+      ),
       skip: !isLinux,
     );
   }, skip: isBrowser);

packages/flutter/test/widgets/physical_model_test.dart

@@ -110,7 +110,10 @@ void main() {
     expect(exception.diagnostics.first.toString(), startsWith('A RenderFlex overflowed by '));
     await expectLater(
       find.byKey(key),
-      matchesGoldenFile('physical_model_overflow.png'),
+      matchesGoldenFile(
+        'physical_model_overflow.png',
+        version: null,
+      ),
       skip: !isLinux,
     );
   }, skip: isBrowser);

packages/flutter/test/widgets/shadow_test.dart

@@ -23,14 +23,20 @@ void main() {
     );
     await expectLater(
       find.byType(Container),
-      matchesGoldenFile('shadow.BoxDecoration.disabled.png'),
+      matchesGoldenFile(
+        'shadow.BoxDecoration.disabled.png',
+        version: null,
+      ),
     );
     debugDisableShadows = false;
     tester.binding.reassembleApplication();
     await tester.pump();
     await expectLater(
       find.byType(Container),
-      matchesGoldenFile('shadow.BoxDecoration.enabled.png'),
+      matchesGoldenFile(
+        'shadow.BoxDecoration.enabled.png',
+        version: null,
+      ),
       skip: !isLinux
     ); // shadows render differently on different platforms
     debugDisableShadows = true;
@@ -57,7 +63,10 @@ void main() {
       await tester.pumpWidget(build(elevation));
       await expectLater(
         find.byType(Container),
-        matchesGoldenFile('shadow.ShapeDecoration.$elevation.png'),
+        matchesGoldenFile(
+          'shadow.ShapeDecoration.$elevation.png',
+          version: null,
+        ),
       );
     }
     debugDisableShadows = true;
@@ -84,14 +93,20 @@ void main() {
     );
     await expectLater(
       find.byType(Container),
-      matchesGoldenFile('shadow.PhysicalModel.disabled.png'),
+      matchesGoldenFile(
+        'shadow.PhysicalModel.disabled.png',
+        version: null,
+      ),
     );
     debugDisableShadows = false;
     tester.binding.reassembleApplication();
     await tester.pump();
     await expectLater(
       find.byType(Container),
-      matchesGoldenFile('shadow.PhysicalModel.enabled.png'),
+      matchesGoldenFile(
+        'shadow.PhysicalModel.enabled.png',
+        version: null,
+      ),
       skip: !isLinux,
     ); // shadows render differently on different platforms
     debugDisableShadows = true;
@@ -122,7 +137,10 @@ void main() {
       await tester.pumpWidget(build(elevation.toDouble()));
       await expectLater(
         find.byType(Container),
-        matchesGoldenFile('shadow.PhysicalShape.$elevation.1.png'),
+        matchesGoldenFile(
+          'shadow.PhysicalShape.$elevation.png',
+          version: 1,
+        ),
       );
     }
     debugDisableShadows = true;

packages/flutter/test/widgets/text_golden_test.dart

@@ -30,7 +30,10 @@ void main() {
 
     await expectLater(
       find.byType(Container),
-      matchesGoldenFile('text_golden.Centered.png'),
+      matchesGoldenFile(
+        'text_golden.Centered.png',
+        version: null,
+      ),
     );
 
     await tester.pumpWidget(
@@ -54,7 +57,10 @@ void main() {
 
     await expectLater(
       find.byType(Container),
-      matchesGoldenFile('text_golden.Centered.wrap.png'),
+      matchesGoldenFile(
+        'text_golden.Centered.wrap.png',
+        version: null,
+      ),
     );
   }, skip: !isLinux);
 
@@ -85,7 +91,10 @@ void main() {
 
     await expectLater(
       find.byType(RepaintBoundary),
-      matchesGoldenFile('text_golden.Foreground.gradient.png'),
+      matchesGoldenFile(
+        'text_golden.Foreground.gradient.png',
+        version: null,
+      ),
     );
 
     await tester.pumpWidget(
@@ -107,7 +116,10 @@ void main() {
 
     await expectLater(
       find.byType(RepaintBoundary),
-      matchesGoldenFile('text_golden.Foreground.stroke.png'),
+      matchesGoldenFile(
+        'text_golden.Foreground.stroke.png',
+        version: null,
+      ),
     );
 
     await tester.pumpWidget(
@@ -130,7 +142,10 @@ void main() {
 
     await expectLater(
       find.byType(RepaintBoundary),
-      matchesGoldenFile('text_golden.Foreground.stroke_and_gradient.png'),
+      matchesGoldenFile(
+        'text_golden.Foreground.stroke_and_gradient.png',
+        version: null,
+      ),
     );
   }, skip: !isLinux);
 
@@ -180,7 +195,10 @@ void main() {
 
     await expectLater(
       find.byType(RepaintBoundary),
-      matchesGoldenFile('text_golden.Background.png'),
+      matchesGoldenFile(
+        'text_golden.Background.png',
+        version: null,
+      ),
     );
   }, skip: !isLinux);
 
@@ -216,7 +234,10 @@ void main() {
 
     await expectLater(
       find.byType(RepaintBoundary).first,
-      matchesGoldenFile('text_golden.Fade.1.png'),
+      matchesGoldenFile(
+        'text_golden.Fade.png',
+        version: 1,
+      ),
     );
   }, skip: !isLinux);
 
@@ -241,7 +262,10 @@ void main() {
     );
     await expectLater(
       find.byType(Container),
-      matchesGoldenFile('text_golden.StrutDefault.png'),
+      matchesGoldenFile(
+        'text_golden.StrutDefault.png',
+        version: null,
+      ),
     );
   }, skip: true); // Should only be on linux (skip: !isLinux).
                   // Disabled for now until font inconsistency is resolved.
@@ -269,7 +293,10 @@ void main() {
     );
     await expectLater(
       find.byType(Container),
-      matchesGoldenFile('text_golden.Strut.1.1.png'),
+      matchesGoldenFile(
+        'text_golden.Strut.1.png',
+        version: 1,
+      ),
     );
   }, skip: true); // Should only be on linux (skip: !isLinux).
                   // Disabled for now until font inconsistency is resolved.
@@ -298,7 +325,10 @@ void main() {
     );
     await expectLater(
       find.byType(Container),
-      matchesGoldenFile('text_golden.Strut.2.1.png'),
+      matchesGoldenFile(
+        'text_golden.Strut.2.png',
+        version: 1,
+      ),
     );
   }, skip: true); // Should only be on linux (skip: !isLinux).
                   // Disabled for now until font inconsistency is resolved.
@@ -350,7 +380,10 @@ void main() {
     );
     await expectLater(
       find.byType(Container),
-      matchesGoldenFile('text_golden.Strut.3.1.png'),
+      matchesGoldenFile(
+        'text_golden.Strut.3.png',
+        version: 1,
+      ),
     );
   }, skip: true); // Should only be on linux (skip: !isLinux).
                   // Disabled for now until font inconsistency is resolved.
@@ -386,7 +419,10 @@ void main() {
     );
     await expectLater(
       find.byType(Container),
-      matchesGoldenFile('text_golden.Strut.4.1.png'),
+      matchesGoldenFile(
+        'text_golden.Strut.4.png',
+        version: 1,
+      ),
     );
   }, skip: true); // Should only be on linux (skip: !isLinux).
                   // Disabled for now until font inconsistency is resolved.
@@ -438,7 +474,10 @@ void main() {
     );
     await expectLater(
       find.byType(Container),
-      matchesGoldenFile('text_golden.StrutForce.1.1.png'),
+      matchesGoldenFile(
+        'text_golden.StrutForce.1.png',
+        version: 1,
+      ),
     );
   }, skip: true); // Should only be on linux (skip: !isLinux).
                   // Disabled for now until font inconsistency is resolved.
@@ -477,7 +516,10 @@ void main() {
     );
     await expectLater(
       find.byType(Container),
-      matchesGoldenFile('text_golden.Decoration.1.0.png'),
+      matchesGoldenFile(
+        'text_golden.Decoration.1.png',
+        version: 0,
+      ),
     );
   }, skip: !isLinux); // Coretext uses different thicknesses for decoration
 
@@ -516,7 +558,10 @@ void main() {
     );
     await expectLater(
       find.byType(Container),
-      matchesGoldenFile('text_golden.DecorationThickness.1.0.png'),
+      matchesGoldenFile(
+        'text_golden.DecorationThickness.1.png',
+        version: 0,
+      ),
     );
   }, skip: !isLinux); // Coretext uses different thicknesses for decoration
 
@@ -610,7 +655,10 @@ void main() {
     );
     await expectLater(
       find.byType(Container),
-      matchesGoldenFile('text_golden.TextInlineWidget.1.1.png'),
+      matchesGoldenFile(
+        'text_golden.TextInlineWidget.1.png',
+        version: 1,
+      ),
     );
   }, skip: !isLinux); // Coretext uses different thicknesses for decoration
 
@@ -655,7 +703,10 @@ void main() {
     );
     await expectLater(
       find.byType(Container),
-      matchesGoldenFile('text_golden.TextInlineWidget.2.2.png'),
+      matchesGoldenFile(
+        'text_golden.TextInlineWidget.2.png',
+        version: 2,
+      ),
     );
   }, skip: !isLinux); // Coretext uses different thicknesses for decoration
 
@@ -784,7 +835,10 @@ void main() {
     );
     await expectLater(
       find.byType(Container),
-      matchesGoldenFile('text_golden.TextInlineWidgetNest.1.2.png'),
+      matchesGoldenFile(
+        'text_golden.TextInlineWidgetNest.1.png',
+        version: 2,
+      ),
     );
   }, skip: !isLinux); // Coretext uses different thicknesses for decoration
 
@@ -891,7 +945,10 @@ void main() {
     );
     await expectLater(
       find.byType(Container),
-      matchesGoldenFile('text_golden.TextInlineWidgetBaseline.1.1.png'),
+      matchesGoldenFile(
+        'text_golden.TextInlineWidgetBaseline.1.png',
+        version: 1,
+      ),
     );
   }, skip: !isLinux); // Coretext uses different thicknesses for decoration
 
@@ -998,7 +1055,10 @@ void main() {
     );
     await expectLater(
       find.byType(Container),
-      matchesGoldenFile('text_golden.TextInlineWidgetAboveBaseline.1.1.png'),
+      matchesGoldenFile(
+        'text_golden.TextInlineWidgetAboveBaseline.1.png',
+        version: 1,
+      ),
     );
   }, skip: !isLinux); // Coretext uses different thicknesses for decoration
 
@@ -1105,7 +1165,10 @@ void main() {
     );
     await expectLater(
       find.byType(Container),
-      matchesGoldenFile('text_golden.TextInlineWidgetBelowBaseline.1.1.png'),
+      matchesGoldenFile(
+        'text_golden.TextInlineWidgetBelowBaseline.1.png',
+        version: 1,
+      ),
     );
   }, skip: !isLinux); // Coretext uses different thicknesses for decoration
 
@@ -1212,7 +1275,10 @@ void main() {
     );
     await expectLater(
       find.byType(Container),
-      matchesGoldenFile('text_golden.TextInlineWidgetTop.1.1.png'),
+      matchesGoldenFile(
+        'text_golden.TextInlineWidgetTop.1.png',
+        version: 1,
+      ),
     );
   }, skip: !isLinux); // Coretext uses different thicknesses for decoration
 
@@ -1319,7 +1385,10 @@ void main() {
     );
     await expectLater(
       find.byType(Container),
-      matchesGoldenFile('text_golden.TextInlineWidgetMiddle.1.1.png'),
+      matchesGoldenFile(
+        'text_golden.TextInlineWidgetMiddle.1.png',
+        version: 1,
+      ),
     );
   }, skip: !isLinux); // Coretext uses different thicknesses for decoration
 }

packages/flutter_test/lib/src/matchers.dart

@@ -293,7 +293,7 @@ Matcher coversSameAreaAs(Path expectedPath, { @required Rect areaToCompare, int
   => _CoversSameAreaAs(expectedPath, areaToCompare: areaToCompare, sampleSize: sampleSize);
 
 /// Asserts that a [Finder], [Future<ui.Image>], or [ui.Image] matches the
-/// golden image file identified by [key].
+/// golden image file identified by [key], with an optional [version] number.
 ///
 /// For the case of a [Finder], the [Finder] must match exactly one widget and
 /// the rendered image of the first [RepaintBoundary] ancestor of the widget is
@@ -301,6 +301,11 @@ Matcher coversSameAreaAs(Path expectedPath, { @required Rect areaToCompare, int
 ///
 /// [key] may be either a [Uri] or a [String] representation of a URI.
 ///
+/// [version] is a number that can be used to differentiate historical golden
+/// files. This parameter is optional. Version numbers are used in golden file
+/// tests for package:flutter. You can learn more about these tests [here]
+/// (https://github.com/flutter/flutter/wiki/Writing-a-golden-file-test-for-package:flutter).
+///
 /// This is an asynchronous matcher, meaning that callers should use
 /// [expectLater] when using this matcher and await the future returned by
 /// [expectLater].
@@ -323,11 +328,11 @@ Matcher coversSameAreaAs(Path expectedPath, { @required Rect areaToCompare, int
 ///    verify that two different code paths create identical images.
 ///  * [flutter_test] for a discussion of test configurations, whereby callers
 ///    may swap out the backend for this matcher.
-AsyncMatcher matchesGoldenFile(dynamic key) {
+AsyncMatcher matchesGoldenFile(dynamic key, {int version}) {
   if (key is Uri) {
-    return _MatchesGoldenFile(key);
+    return _MatchesGoldenFile(key, version);
   } else if (key is String) {
-    return _MatchesGoldenFile.forStringPath(key);
+    return _MatchesGoldenFile.forStringPath(key, version);
   }
   throw ArgumentError('Unexpected type for golden file: ${key.runtimeType}');
 }
@@ -1672,11 +1677,12 @@ class _MatchesReferenceImage extends AsyncMatcher {
 }
 
 class _MatchesGoldenFile extends AsyncMatcher {
-  const _MatchesGoldenFile(this.key);
+  const _MatchesGoldenFile(this.key, this.version);
 
-  _MatchesGoldenFile.forStringPath(String path) : key = Uri.parse(path);
+  _MatchesGoldenFile.forStringPath(String path, this.version) : key = Uri.parse(path);
 
   final Uri key;
+  final int version;
 
   @override
   Future<String> matchAsync(dynamic item) async {
@@ -1696,6 +1702,8 @@ class _MatchesGoldenFile extends AsyncMatcher {
       imageFuture = _captureImage(elements.single);
     }
 
+    final Uri testNameUri = _getTestNameUri(key, version);
+
     final TestWidgetsFlutterBinding binding = TestWidgetsFlutterBinding.ensureInitialized();
     return binding.runAsync<String>(() async {
       final ui.Image image = await imageFuture;
@@ -1703,11 +1711,11 @@ class _MatchesGoldenFile extends AsyncMatcher {
       if (bytes == null)
         return 'could not encode screenshot.';
       if (autoUpdateGoldenFiles) {
-        await goldenFileComparator.update(key, bytes.buffer.asUint8List());
+        await goldenFileComparator.update(testNameUri, bytes.buffer.asUint8List());
         return null;
       }
       try {
-        final bool success = await goldenFileComparator.compare(bytes.buffer.asUint8List(), key);
+        final bool success = await goldenFileComparator.compare(bytes.buffer.asUint8List(), testNameUri);
         return success ? null : 'does not match';
       } on TestFailure catch (ex) {
         return ex.message;
@@ -1717,7 +1725,19 @@ class _MatchesGoldenFile extends AsyncMatcher {
 
   @override
   Description describe(Description description) =>
-      description.add('one widget whose rasterized image matches golden image "$key"');
+      description.add('one widget whose rasterized image matches golden image "${_getTestNameUri(key, version)}"');
+
+  Uri _getTestNameUri(Uri key, int version) {
+    return version == null ? key : Uri.parse(
+      key
+        .toString()
+        .splitMapJoin(
+          RegExp(r'.png'),
+          onMatch: (Match m) => '${'.' + version.toString() + m.group(0)}',
+          onNonMatch: (String n) => '$n'
+        )
+    );
+  }
 }
 
 class _MatchesSemanticsData extends Matcher {

packages/flutter_test/test/matchers_test.dart

@@ -326,6 +326,7 @@ void main() {
     });
 
     group('matches', () {
+
       testWidgets('if comparator succeeds', (WidgetTester tester) async {
         await tester.pumpWidget(boilerplate(const Text('hello')));
         final Finder finder = find.byType(Text);
@@ -334,6 +335,30 @@ void main() {
         expect(comparator.imageBytes, hasLength(greaterThan(0)));
         expect(comparator.golden, Uri.parse('foo.png'));
       });
+
+      testWidgets('Comparator succeeds incorporating version number', (WidgetTester tester) async {
+        await tester.pumpWidget(boilerplate(const Text('hello')));
+        final Finder finder = find.byType(Text);
+        await expectLater(finder, matchesGoldenFile(
+          'foo.png',
+          version: 1,
+        ));
+        expect(comparator.invocation, _ComparatorInvocation.compare);
+        expect(comparator.imageBytes, hasLength(greaterThan(0)));
+        expect(comparator.golden, Uri.parse('foo.1.png'));
+      });
+
+      testWidgets('Comparator succeeds with null version number', (WidgetTester tester) async {
+        await tester.pumpWidget(boilerplate(const Text('hello')));
+        final Finder finder = find.byType(Text);
+        await expectLater(finder, matchesGoldenFile(
+          'foo.png',
+          version: null,
+        ));
+        expect(comparator.invocation, _ComparatorInvocation.compare);
+        expect(comparator.imageBytes, hasLength(greaterThan(0)));
+        expect(comparator.golden, Uri.parse('foo.png'));
+      });
     });
 
     group('does not match', () {
@@ -388,6 +413,40 @@ void main() {
           expect(error.message, contains('too many widgets'));
         }
       });
+
+      testWidgets('Comparator failure incorporates version number', (WidgetTester tester) async {
+        comparator.behavior = _ComparatorBehavior.returnFalse;
+        await tester.pumpWidget(boilerplate(const Text('hello')));
+        final Finder finder = find.byType(Text);
+        try {
+          await expectLater(finder, matchesGoldenFile(
+            'foo.png',
+            version: 1,
+          ));
+          fail('TestFailure expected but not thrown');
+        } on TestFailure catch (error) {
+          expect(comparator.invocation, _ComparatorInvocation.compare);
+          expect(error.message, contains('does not match'));
+          expect(error.message, contains('foo.1.png'));
+        }
+      });
+
+      testWidgets('Comparator failure with null version number', (WidgetTester tester) async {
+        comparator.behavior = _ComparatorBehavior.returnFalse;
+        await tester.pumpWidget(boilerplate(const Text('hello')));
+        final Finder finder = find.byType(Text);
+        try {
+          await expectLater(finder, matchesGoldenFile(
+            'foo.png',
+            version: null,
+          ));
+          fail('TestFailure expected but not thrown');
+        } on TestFailure catch (error) {
+          expect(comparator.invocation, _ComparatorInvocation.compare);
+          expect(error.message, contains('does not match'));
+          expect(error.message, contains('foo.png'));
+        }
+      });
     });
 
     testWidgets('calls update on comparator if autoUpdateGoldenFiles is true', (WidgetTester tester) async {