[Feature] - Added a SingleShot golden scene for less verbose tests with a single golden image (Resolves #27) (#33)

matthew-carroll · web-flow · commit 9f7f6b5053ab · 2025-06-08T13:02:34.000-07:00
diff --git a/analysis_options.yaml b/analysis_options.yaml
@@ -2,3 +2,7 @@ include: package:flutter_lints/flutter.yaml
 
 # Additional information about this file can be found at
 # https://dart.dev/guides/language/analysis-options
+
+linter:
+  rules:
+    - always_use_package_imports
diff --git a/lib/flutter_test_goldens.dart b/lib/flutter_test_goldens.dart
@@ -10,5 +10,6 @@ export 'src/scenes/film_strip.dart';
 export 'src/scenes/gallery.dart';
 export 'src/scenes/golden_scene.dart';
 export 'src/scenes/scene_layout.dart';
+export 'src/scenes/single_shot.dart';
 export 'src/logging.dart';
 export 'src/test_runners.dart';
diff --git a/lib/src/scenes/gallery.dart b/lib/src/scenes/gallery.dart
@@ -4,9 +4,10 @@ import 'dart:math';
 import 'dart:typed_data';
 import 'dart:ui' as ui;
 
-import 'package:flutter/material.dart' hide Image;
 import 'package:flutter/material.dart' as m;
+import 'package:flutter/material.dart' hide Image;
 import 'package:flutter_test/flutter_test.dart';
+import 'package:flutter_test_goldens/golden_bricks.dart';
 import 'package:flutter_test_goldens/src/flutter/flutter_test_extensions.dart';
 import 'package:flutter_test_goldens/src/goldens/golden_camera.dart';
 import 'package:flutter_test_goldens/src/goldens/golden_collections.dart';
@@ -15,9 +16,11 @@ import 'package:flutter_test_goldens/src/goldens/golden_rendering.dart';
 import 'package:flutter_test_goldens/src/goldens/golden_scenes.dart';
 import 'package:flutter_test_goldens/src/goldens/pixel_comparisons.dart';
 import 'package:flutter_test_goldens/src/logging.dart';
+import 'package:flutter_test_goldens/src/scenes/golden_files.dart';
 import 'package:flutter_test_goldens/src/scenes/golden_scene.dart';
 import 'package:flutter_test_goldens/src/scenes/scene_layout.dart';
 import 'package:image/image.dart';
+import 'package:path/path.dart';
 import 'package:qr_bar_code/code/code.dart';
 
 /// A golden builder that builds independent widget tree UIs and then either
@@ -26,20 +29,25 @@ import 'package:qr_bar_code/code/code.dart';
 class Gallery {
   Gallery(
     this._tester, {
-    required String sceneName,
+    Directory? directory,
+    required String fileName,
+    required String sceneDescription,
     required SceneLayout layout,
     GalleryItemScaffold itemScaffold = defaultGalleryItemScaffold,
     GalleryItemDecorator? itemDecorator,
     Widget? goldenBackground,
     m.Color qrCodeColor = m.Colors.black,
     m.Color qrCodeBackgroundColor = m.Colors.white,
-  })  : _sceneName = sceneName,
+  })  : _fileName = fileName,
+        _sceneDescription = sceneDescription,
         _layout = layout,
         _itemScaffold = itemScaffold,
         _itemDecorator = itemDecorator,
         _goldenBackground = goldenBackground,
         _qrCodeColor = qrCodeColor,
-        _qrCodeBackgroundColor = qrCodeBackgroundColor;
+        _qrCodeBackgroundColor = qrCodeBackgroundColor {
+    _directory = directory ?? defaultGoldenDirectory;
+  }
 
   final WidgetTester _tester;
 
@@ -54,9 +62,14 @@ class Gallery {
   /// All screenshots within this scene.
   final _items = <GalleryItem>[];
 
-  /// The name of the overall golden scene, which may includes many individual
-  /// goldens.
-  final String _sceneName;
+  /// The directory where the golden scene file will be saved.
+  late final Directory _directory;
+
+  /// The file name for the golden scene file, which will be saved in [_directory].
+  final String _fileName;
+
+  /// A human readable description of what's in this scene.
+  final String _sceneDescription;
 
   /// The layout to use to position all the items in this scene.
   final SceneLayout _layout;
@@ -78,6 +91,7 @@ class Gallery {
       GalleryItem.withWidget(
         id: id,
         description: description,
+        boundsFinder: boundsFinder,
         child: widget,
       ),
     );
@@ -96,6 +110,7 @@ class Gallery {
       GalleryItem.withBuilder(
         id: id,
         description: description,
+        boundsFinder: boundsFinder,
         builder: builder,
       ),
     );
@@ -130,6 +145,7 @@ class Gallery {
       GalleryItem.withPumper(
         id: id,
         description: description,
+        boundsFinder: boundsFinder,
         pumper: pumper,
       ),
     );
@@ -140,7 +156,7 @@ class Gallery {
   /// Either renders a new golden to a scene file, or compares new screenshots against an existing
   /// golden scene file.
   Future<void> renderOrCompareGolden() async {
-    FtgLog.pipeline.info("Rendering or comparing golden - $_sceneName");
+    FtgLog.pipeline.info("Rendering or comparing golden - $_sceneDescription");
 
     // Build each gallery item and screenshot it.
     final camera = GoldenCamera();
@@ -155,29 +171,25 @@ class Gallery {
         await _tester.pumpWidget(
           _itemScaffold(
             _tester,
-            GoldenImageBounds(
-              child: _itemDecorator != null
-                  ? _itemDecorator.call(
-                      _tester,
-                      Builder(builder: item.builder!),
-                    )
-                  : Builder(builder: item.builder!),
-            ),
+            _itemDecorator != null
+                ? _itemDecorator.call(
+                    _tester,
+                    Builder(builder: item.builder!),
+                  )
+                : Builder(builder: item.builder!),
           ),
         );
       } else {
         // Pump this gallery item, deferring to a `Widget` for the content.
         await _tester.pumpWidget(
           _itemScaffold(
             _tester,
-            GoldenImageBounds(
-              child: _itemDecorator != null
-                  ? _itemDecorator.call(
-                      _tester,
-                      item.child!,
-                    )
-                  : item.child!,
-            ),
+            _itemDecorator != null
+                ? _itemDecorator.call(
+                    _tester,
+                    item.child!,
+                  )
+                : item.child!,
           ),
         );
       }
@@ -237,15 +249,15 @@ class Gallery {
 
     await _tester.pumpAndSettle();
 
-    final goldenFileName = "$_sceneName.png";
+    final goldenFilePath = File("${_directory.path}$separator$_fileName.png");
     if (autoUpdateGoldenFiles) {
       // Generate new goldens.
       FtgLog.pipeline.finer("Doing golden generation - window height: ${_tester.view.physicalSize.height}");
-      await expectLater(find.byType(GoldenSceneBounds), matchesGoldenFile(goldenFileName));
+      await expectLater(find.byType(GoldenSceneBounds), matchesGoldenFile(goldenFilePath.path));
     } else {
       // Compare to existing goldens.
       FtgLog.pipeline.finer("Comparing existing goldens...");
-      await _compareGoldens(_tester, goldenFileName, find.byType(GoldenSceneBounds));
+      await _compareGoldens(_tester, goldenFilePath, find.byType(GoldenSceneBounds));
       FtgLog.pipeline.finer("Done comparing goldens for gallery");
     }
 
@@ -363,9 +375,9 @@ class Gallery {
     );
   }
 
-  Future<void> _compareGoldens(WidgetTester tester, String existingGoldenFileName, Finder goldenBounds) async {
+  Future<void> _compareGoldens(WidgetTester tester, File existingGoldenFileName, Finder goldenBounds) async {
     final testFileDirectory = (goldenFileComparator as LocalFileComparator).basedir.path;
-    final goldenFile = File("$testFileDirectory$existingGoldenFileName");
+    final goldenFile = File("$testFileDirectory${existingGoldenFileName.path}");
 
     if (!goldenFile.existsSync()) {
       // TODO: report error in structured way.
@@ -568,10 +580,21 @@ class GalleryItem {
   final Widget? child;
 }
 
+/// The ancestor widget tree for every item in a gallery, unless overridden by
+/// the gallery configuration.
 Widget defaultGalleryItemScaffold(WidgetTester tester, Widget content) {
   return MaterialApp(
     home: Scaffold(
-      body: content,
+      body: m.Builder(builder: (context) {
+        return DefaultTextStyle(
+          style: DefaultTextStyle.of(context).style.copyWith(
+                fontFamily: goldenBricks,
+              ),
+          child: Center(
+            child: GoldenImageBounds(child: content),
+          ),
+        );
+      }),
     ),
     debugShowCheckedModeBanner: false,
   );
diff --git a/lib/src/scenes/golden_files.dart b/lib/src/scenes/golden_files.dart
@@ -0,0 +1,7 @@
+import 'dart:io';
+
+/// The standard path to where goldens are saved.
+///
+/// The default path is a `/goldens/` directory, which sits in the same parent directory as
+/// the test file that's running the test.
+final defaultGoldenDirectory = Directory("./goldens/");
diff --git a/lib/src/scenes/single_shot.dart b/lib/src/scenes/single_shot.dart
@@ -0,0 +1,129 @@
+import 'dart:io';
+
+import 'package:flutter/material.dart' hide Image;
+import 'package:flutter_test/flutter_test.dart';
+import 'package:flutter_test_goldens/src/goldens/golden_rendering.dart';
+import 'package:flutter_test_goldens/src/scenes/gallery.dart';
+import 'package:flutter_test_goldens/src/scenes/golden_files.dart';
+import 'package:flutter_test_goldens/src/scenes/scene_layout.dart';
+
+/// A golden scene with a single golden image.
+class SingleShot {
+  /// Creates a [SingleShot] whose content is rendered by a given [widget].
+  SingleShot.fromWidget(
+    this._tester, {
+    Directory? directory,
+    required String fileName,
+    required String description,
+    GalleryItemScaffold itemScaffold = defaultGalleryItemScaffold,
+    GalleryItemDecorator? itemDecorator,
+    Finder? boundsFinder,
+    required Widget widget,
+  })  : _fileName = fileName,
+        _description = description,
+        _itemScaffold = itemScaffold,
+        _itemDecorator = itemDecorator,
+        _boundsFinder = boundsFinder ?? find.byType(GoldenImageBounds),
+        _widget = widget,
+        _builder = null,
+        _pumper = null {
+    _directory = directory ?? defaultGoldenDirectory;
+  }
+
+  /// Creates a [SingleShot] whose content is rendered by a given [builder].
+  SingleShot.fromBuilder(
+    this._tester, {
+    Directory? directory,
+    required String fileName,
+    required String description,
+    GalleryItemScaffold itemScaffold = defaultGalleryItemScaffold,
+    GalleryItemDecorator? itemDecorator,
+    Finder? boundsFinder,
+    required WidgetBuilder builder,
+  })  : _fileName = fileName,
+        _description = description,
+        _itemScaffold = itemScaffold,
+        _itemDecorator = itemDecorator,
+        _boundsFinder = boundsFinder ?? find.byType(GoldenImageBounds),
+        _builder = builder,
+        _widget = null,
+        _pumper = null {
+    _directory = directory ?? defaultGoldenDirectory;
+  }
+
+  /// Creates a [SingleShot] whose content is rendered by a given [pumper].
+  ///
+  /// This constructor is useful when a golden scene needs full control over the [WidgetTester],
+  /// and the call to [WidgetTester.pumpWidget].
+  SingleShot.fromPumper(
+    this._tester, {
+    Directory? directory,
+    required String fileName,
+    required String description,
+    GalleryItemScaffold itemScaffold = defaultGalleryItemScaffold,
+    GalleryItemDecorator? itemDecorator,
+    Finder? boundsFinder,
+    required GalleryItemPumper pumper,
+  })  : _fileName = fileName,
+        _description = description,
+        _itemScaffold = itemScaffold,
+        _itemDecorator = itemDecorator,
+        _boundsFinder = boundsFinder ?? find.byType(GoldenImageBounds),
+        _pumper = pumper,
+        _widget = null,
+        _builder = null {
+    _directory = directory ?? defaultGoldenDirectory;
+  }
+
+  final WidgetTester _tester;
+
+  /// The directory where the golden scene file will be saved.
+  late final Directory _directory;
+
+  /// The file name for the golden scene file, which will be saved in [_directory].
+  final String _fileName;
+
+  /// The name of the overall golden scene.
+  final String _description;
+
+  /// A scaffold built around each item in this scene.
+  ///
+  /// Defaults to [defaultGalleryItemScaffold].
+  final GalleryItemScaffold _itemScaffold;
+
+  /// A decoration applied to each item in this scene.
+  final GalleryItemDecorator? _itemDecorator;
+
+  /// [Finder] that locates the content that will be screenshotted in this golden scene.
+  final Finder _boundsFinder;
+
+  final GalleryItemPumper? _pumper;
+
+  final WidgetBuilder? _builder;
+
+  final Widget? _widget;
+
+  /// Either renders a new golden to a scene file, or compares new screenshots against an existing
+  /// golden scene file.
+  Future<void> renderOrCompareGolden() async {
+    final gallery = Gallery(
+      _tester,
+      directory: _directory,
+      fileName: _fileName,
+      sceneDescription: _description,
+      layout: SceneLayout.column,
+      itemScaffold: _itemScaffold,
+      itemDecorator: _itemDecorator,
+    );
+
+    if (_widget != null) {
+      gallery.itemFromWidget(id: "1", description: _description, widget: _widget, boundsFinder: _boundsFinder);
+    } else if (_builder != null) {
+      gallery.itemFromBuilder(id: "1", description: _description, builder: _builder, boundsFinder: _boundsFinder);
+    } else {
+      gallery.itemFromPumper(id: "1", description: _description, pumper: _pumper!, boundsFinder: _boundsFinder);
+    }
+
+    await gallery.renderOrCompareGolden();
+  }
+}
diff --git a/test_goldens/flutter/buttons/buttons_test.dart b/test_goldens/flutter/buttons/buttons_test.dart
@@ -164,9 +164,11 @@ void main() {
 
     await Gallery(
       tester,
-      sceneName: "button_extended_fab_gallery",
+      directory: Directory("."),
+      fileName: "button_extended_fab_gallery",
+      sceneDescription: "FAB Gallery",
       layout: SceneLayout.row,
-      itemDecorator: (context, child) {
+      itemScaffold: (context, child) {
         return FlutterWidgetScaffold(
           child: child,
         );
diff --git a/test_goldens/flutter/flutter_widget_scaffold.dart b/test_goldens/flutter/flutter_widget_scaffold.dart
@@ -20,11 +20,13 @@ class FlutterWidgetScaffold extends StatelessWidget {
       ),
       home: Scaffold(
         backgroundColor: const Color(0xFF222222),
-        body: GoldenSceneBounds(
-          key: goldenKey,
-          child: Padding(
-            padding: const EdgeInsets.all(48),
-            child: child,
+        body: Center(
+          child: GoldenImageBounds(
+            key: goldenKey,
+            child: Padding(
+              padding: const EdgeInsets.all(48),
+              child: child,
+            ),
           ),
         ),
       ),
diff --git a/test_goldens/scene_types/gallery_test.dart b/test_goldens/scene_types/gallery_test.dart
diff --git a/test_goldens/scene_types/single_shot_scene.png b/test_goldens/scene_types/single_shot_scene.png
diff --git a/test_goldens/scene_types/single_shot_test.dart b/test_goldens/scene_types/single_shot_test.dart
