[FEATURE][BUG]: Fixes and improvements when using with follow_the_leader package (#63)

* FIX: Make use of given spacing in GridGoldenSceneLayout
* FIX/ADJUSTMENT: Don't paint to Canvas before taking photo with FlutterCamera - this broke nuanced render object and layer behavior in follow_the_leader. Instead, use toImageSync() on the existing RepaintBoundary.
* ADJUSTMENT: Changed GridSceneLayout to use default item decorator and background to match existing behavior of FlexSceneLayout.
* FEATURE: Add itemSetup to Gallery so that a single setup can be applied to all items.
* ADJUSTMENT: When a Gallery is given item constraints, it now sets its physicalSize to match the max bounds.
* FEATURE: Timeline now accepts a desired windowSize which it applies to the physicalSize in the test.
* ADJUSTMENT: Changed the existing "minimal" Timeline itemScaffold to become the "standard" one, and then created a true "minimal" itemScaffold that makes no decisions about theme, background color, or padding.
* ADJUSTMENT: Renamed "pump" method in Timeline to say "builder" because that's more of what it is.

Author: matthew-carroll

doc/marketing_goldens/shadcn_test_tools.dart

@@ -57,9 +57,9 @@ class ShadcnSingleShotSceneLayout implements SceneLayout {
   Widget build(
     WidgetTester tester,
     BuildContext context,
-    Map<GoldenSceneScreenshot, GlobalKey<State<StatefulWidget>>> goldens,
+    SceneLayoutContent content,
   ) {
-    final golden = goldens.entries.first;
+    final golden = content.goldens.entries.first;
 
     return DefaultTextStyle(
       style: GoldenSceneTheme.current.defaultTextStyle.copyWith(
@@ -129,9 +129,9 @@ class ShadcnGalleryLayout implements SceneLayout {
   Widget build(
     WidgetTester tester,
     BuildContext context,
-    Map<GoldenSceneScreenshot, GlobalKey<State<StatefulWidget>>> goldens,
+    SceneLayoutContent content,
   ) {
-    final entries = goldens.entries.toList();
+    final entries = content.goldens.entries.toList();
 
     return DefaultTextStyle(
       style: GoldenSceneTheme.current.defaultTextStyle.copyWith(

doc/website/source/index.md

@@ -12,7 +12,7 @@ how we solve them.
 
  * **Failure Files:** Flutter spreads a single test failure across four different files.
    It's frustrating to have to open up multiple files to cross reference. With
-   `flutter_test_goldes`, your failure output is painted to a single file for easy review.
+   `flutter_test_goldens`, your failure output is painted to a single file for easy review.
  * **Widget Galleries:** Flutter developers often want to verify multiple configurations
    of a single widget, or multiple related widgets, at the same time. With
    `flutter_test_goldens`, you can easily paint a variety of widgets into a gallery,

doc/website/source/styles/docs_page_layout.scss

@@ -265,13 +265,15 @@ main.page-content {
     margin-bottom: 1.5em;
   }
 
-  code {
-    padding: 3px 6px;
-    background: #7f00a6;
-    border: 1px solid #a218cc;
-    border-radius: 4px;
-
-    color: WHITE;
+  p, li > {
+    code {
+      padding: 3px 6px;
+      background: #7f00a6;
+      border: 1px solid #a218cc;
+      border-radius: 4px;
+
+      color: WHITE;
+    }
   }
 
   li {

lib/src/flutter/flutter_camera.dart

@@ -34,17 +34,7 @@ class FlutterCamera {
       );
     }
 
-    final pictureRecorder = PictureRecorder();
-    final canvas = Canvas(pictureRecorder);
-    final screenSize = fullscreenRenderObject.size;
-
-    final paintingContext = TestRecordingPaintingContext(canvas);
-    fullscreenRenderObject.paint(paintingContext, Offset.zero);
-
-    final fullscreenPhoto = await pictureRecorder.endRecording().toImage(
-          screenSize.width.round(),
-          screenSize.height.round(),
-        );
+    final fullscreenPhoto = fullscreenRenderObject.toImageSync();
 
     final contentFinder = finder ?? find.byType(GoldenImageBounds);
     expect(finder, findsOne);

lib/src/flutter/flutter_golden_matcher.dart

@@ -1,5 +1,4 @@
 import 'dart:io';
-import 'dart:typed_data';
 
 import 'package:flutter/foundation.dart';
 import 'package:flutter_test/flutter_test.dart';

lib/src/scenes/failure_scene.dart

@@ -186,7 +186,7 @@ Future<(Image, FailureSceneMetadata)> _layoutFailureScene(
             return layout.build(
               tester,
               context,
-              renderablePhotos,
+              SceneLayoutContent(goldens: renderablePhotos),
             );
           },
         ),

lib/src/scenes/gallery.dart

@@ -32,12 +32,14 @@ class Gallery {
     BoxConstraints? itemConstraints,
     Finder? itemBoundsFinder,
     required SceneLayout layout,
+    GoldenSetup? itemSetup,
   })  : _fileName = fileName,
         _sceneDescription = sceneDescription,
         _itemScaffold = itemScaffold,
         _itemConstraints = itemConstraints,
         _itemBoundsFinder = itemBoundsFinder,
-        _layout = layout {
+        _layout = layout,
+        _itemSetup = itemSetup {
     _directory = directory ?? GoldenSceneTheme.current.directory;
   }
 
@@ -84,6 +86,12 @@ class Gallery {
   /// 3. `find.byType(GoldenImageBounds)`.
   final Finder? _itemBoundsFinder;
 
+  /// An optional setup method that runs after pumping an item's tree, and just before the
+  /// item is screenshotted.
+  ///
+  /// This setup runs for every item in the scene unless an individual item overrides it.
+  final GoldenSetup? _itemSetup;
+
   /// Requests for all screenshots within this scene, by their ID.
   final _requests = <String, GalleryGoldenRequest>{};
 
@@ -329,6 +337,14 @@ class Gallery {
       final previousPlatform = debugDefaultTargetPlatformOverride;
       debugDefaultTargetPlatformOverride = item.platform ?? previousPlatform;
 
+      if (itemConstraints != null && itemConstraints.hasBoundedWidth && itemConstraints.hasBoundedHeight) {
+        // Some tests may want to control the size of the window. If we're given bounded
+        // constraints, make the window the biggest allowable size.
+        final previousSize = tester.view.physicalSize;
+        tester.view.physicalSize = itemConstraints.biggest;
+        addTearDown(() => tester.view.physicalSize = previousSize);
+      }
+
       if (item.pumper != null) {
         // Defer to the `pumper` to pump the entire widget tree for this gallery item.
         await item.pumper!.call(tester, itemScaffold, item.description);
@@ -353,7 +369,7 @@ class Gallery {
       }
 
       // Run the item's setup function, if there is one.
-      await item.setup?.call(tester);
+      await (item.setup ?? _itemSetup)?.call(tester);
 
       // Take a screenshot.
       expect(item.boundsFinder, findsOne);
@@ -476,8 +492,11 @@ Image.memory(
     SceneLayout layout,
     Map<String, GoldenSceneScreenshot> goldenScreenshots,
   ) async {
-    final goldensAndGlobalKeys = Map<GoldenSceneScreenshot, GlobalKey>.fromEntries(
-      goldenScreenshots.entries.map((entry) => MapEntry(entry.value, GlobalKey())),
+    final content = SceneLayoutContent(
+      description: _sceneDescription,
+      goldens: Map<GoldenSceneScreenshot, GlobalKey>.fromEntries(
+        goldenScreenshots.entries.map((entry) => MapEntry(entry.value, GlobalKey())),
+      ),
     );
 
     // Layout the gallery scene with the new goldens, check the intrinsic size of the
@@ -487,13 +506,13 @@ Image.memory(
     // a corresponding `GlobalKey` already in the tree. Therefore, this layout pass inserts a
     // `GlobalKey` for every golden screenshot that we want to render.
     await tester.pumpWidgetAndAdjustWindow(
-      _buildGalleryLayout(tester, goldensAndGlobalKeys),
+      _buildGalleryLayout(tester, content),
     );
 
     // Use Flutter's `precacheImage()` mechanism to get each golden screenshot bitmap to
     // render in this widget test.
     await tester.runAsync(() async {
-      for (final entry in goldensAndGlobalKeys.entries) {
+      for (final entry in content.goldens.entries) {
         await precacheImage(
           MemoryImage(entry.key.pngBytes),
           tester.element(find.byKey(entry.value)),
@@ -506,21 +525,21 @@ Image.memory(
     return GoldenSceneMetadata(
       description: _sceneDescription,
       images: [
-        for (final golden in goldensAndGlobalKeys.keys)
+        for (final golden in content.goldens.keys)
           GoldenImageMetadata(
             id: golden.id,
             metadata: golden.metadata,
-            topLeft: (goldensAndGlobalKeys[golden]!.currentContext!.findRenderObject() as RenderBox)
-                .localToGlobal(Offset.zero),
-            size: goldensAndGlobalKeys[golden]!.currentContext!.size!,
+            topLeft:
+                (content.goldens[golden]!.currentContext!.findRenderObject() as RenderBox).localToGlobal(Offset.zero),
+            size: content.goldens[golden]!.currentContext!.size!,
           ),
       ],
     );
   }
 
-  Widget _buildGalleryLayout(WidgetTester tester, Map<GoldenSceneScreenshot, GlobalKey> candidatesAndGlobalKeys) {
+  Widget _buildGalleryLayout(WidgetTester tester, SceneLayoutContent content) {
     return Builder(builder: (context) {
-      return _layout.build(tester, context, candidatesAndGlobalKeys);
+      return _layout.build(tester, context, content);
     });
   }