Added a gallery builder to go along with the film strip builder.

Author: matthew-carroll

README.md

@@ -2,6 +2,53 @@
 A toolkit for writing golden tests.
 
 ## Getting Started
+The following shows an example of how to define a golden test that captures
+a variety of independent UIs as a gallery.
+
+```dart
+testGoldenSceneOnMac("extended floating action button gallery", (tester) async {
+    await Gallery(
+      tester,
+      itemDecorator: (context, child) {
+        return FlutterWidgetScaffold(
+          child: child,
+        );
+      },
+      items: [
+        GalleryItem.withWidget(
+          id: "1",
+          description: "Icon + Text",
+          child: FloatingActionButton.extended(
+            icon: Icon(Icons.edit),
+            label: Text("Hello"),
+            onPressed: () {},
+          ),
+        ),
+        GalleryItem.withWidget(
+          id: "2",
+          description: "Icon",
+          child: FloatingActionButton.extended(
+            icon: Icon(Icons.edit),
+            label: Text(""),
+            onPressed: () {},
+          ),
+        ),
+        GalleryItem.withWidget(
+          id: "3",
+          description: "Text",
+          child: FloatingActionButton.extended(
+            label: Text("Hello"),
+            onPressed: () {},
+          ),
+        ),
+      ],
+    ).renderOrCompareGolden(
+      goldenName: "button_extended_fab_gallery",
+      layout: SceneLayout.row,
+    );
+});
+```
+
 The following shows an example of how to define a golden test that captures
 screenshots over time, placing all of them in a single scene file.
 
@@ -34,7 +81,7 @@ testGoldenSceneOnMac("elevated button interactions", (tester) async {
         // an existing scene file.
         .renderOrCompareGolden(
           goldenName: "button_elevated_interactions",
-          layout: FilmStripLayout.row,
+          layout: SceneLayout.row,
         );
 });
 ```

lib/flutter_test_goldens.dart

@@ -1,12 +1,12 @@
 export 'src/flutter/flutter_test_extensions.dart';
 export 'src/fonts/fonts.dart';
-export 'src/galleries/film_strip.dart';
-export 'src/galleries/gallery.dart';
 export 'src/goldens/golden_camera.dart';
 export 'src/goldens/golden_collections.dart';
 export 'src/goldens/golden_comparisons.dart';
 export 'src/goldens/golden_rendering.dart';
 export 'src/goldens/golden_scenes.dart';
 export 'src/qr_codes/qr_code_image_scanning.dart';
+export 'src/scenes/film_strip.dart';
+export 'src/scenes/golden_scene.dart';
 export 'src/logging.dart';
 export 'src/test_runners.dart';

lib/src/goldens/pixel_comparisons.dart

@@ -0,0 +1,45 @@
+import 'package:flutter/material.dart' as m;
+import 'package:image/image.dart';
+
+double calculateColorMismatchPercent(Color c1, Color c2) {
+  final doLog = false; //c1.r == 255; //c1.r != c1.g;
+  final color1 = m.Color.fromARGB(255, c1.r.toInt(), c1.g.toInt(), c1.b.toInt());
+  final hsv1 = m.HSVColor.fromColor(color1);
+
+  final color2 = m.Color.fromARGB(255, c2.r.toInt(), c2.g.toInt(), c2.b.toInt());
+  final hsv2 = m.HSVColor.fromColor(color2);
+
+  // Calculate per-component difference.
+  var deltaHue = (hsv2.hue - hsv1.hue).abs();
+  final deltaSaturation = (hsv2.saturation - hsv2.saturation).abs();
+  final deltaValue = (hsv2.value - hsv1.value).abs();
+
+  // Handle hue circularity (i.e., fact that 360 degrees go back to 0 degrees)
+  deltaHue = deltaHue > 180 ? 360 - deltaHue : deltaHue;
+
+  // Normalize each component difference.
+  deltaHue = deltaHue / 180;
+  // Other components are already in range [0, 1].
+
+  // Combine components instead single distance value.
+  //
+  // The difference formula is arbitrary, but the goal is to draw attention to differences that are likely
+  // to be important, which means reducing differences between things that aren't. In this equation we treat
+  // the value difference as the most important, such that black vs white goes directly to the max. Assuming
+  // the difference in value doesn't eat up all the difference, the hue is then given 3 times the
+  // weight of the saturation difference.
+  //
+  // This formula can easily exceed the max value of `1.0` so it's clamped. This means that many different
+  // color variations will all be at the highest intensity, but that's OK, be there is more than one color
+  // difference that's worthy of attention.
+  final difference = (deltaValue + ((deltaHue * 3) + deltaSaturation) / 4).clamp(0.0, 1.0);
+  if (doLog) {
+    print(
+        "Color 1 - red: ${c1.r}, green: ${c1.g}, blue: ${c1.b} - h: ${hsv1.hue}, s: ${hsv1.saturation}, v: ${hsv1.value}");
+    print(
+        "Color 2 - red: ${c2.r}, green: ${c2.g}, blue: ${c2.b} - h: ${hsv2.hue}, s: ${hsv2.saturation}, v: ${hsv2.value}");
+    print("Difference: $difference");
+  }
+
+  return difference;
+}

lib/src/logging.dart

@@ -1,16 +1,18 @@
 import 'package:logging/logging.dart';
 
+export 'package:logging/logging.dart' show Level;
+
 /// Loggers for Flutter Test Goldens (FTG).
 abstract class FtgLog {
   static final pipeline = Logger('ftg.pipeline');
 
   static final _activeLoggers = <Logger>{};
 
-  static void initAllLogs(Level level) {
-    initLoggers(level, {Logger.root});
+  static void initAllLogs([Level? level = Level.ALL]) {
+    initLoggers({Logger.root}, level);
   }
 
-  static void initLoggers(Level level, Set<Logger> loggers) {
+  static void initLoggers(Set<Logger> loggers, [Level? level = Level.ALL]) {
     hierarchicalLoggingEnabled = true;
 
     for (final logger in loggers) {

lib/src/galleries/film_strip.dart renamed to lib/src/scenes/film_strip.dart

@@ -8,13 +8,15 @@ import 'package:flutter/material.dart' hide Image;
 import 'package:flutter/material.dart' as m;
 import 'package:flutter_test/flutter_test.dart';
 import 'package:flutter_test_goldens/src/flutter/flutter_test_extensions.dart';
-import 'package:flutter_test_goldens/src/galleries/gallery.dart';
 import 'package:flutter_test_goldens/src/goldens/golden_camera.dart';
 import 'package:flutter_test_goldens/src/goldens/golden_collections.dart';
 import 'package:flutter_test_goldens/src/goldens/golden_comparisons.dart';
 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_scene.dart';
+import 'package:flutter_test_goldens/src/scenes/scene_layout.dart';
 import 'package:image/image.dart';
 import 'package:qr_bar_code/code/code.dart';
 
@@ -119,7 +121,7 @@ class FilmStrip {
 
   Future<void> renderOrCompareGolden({
     required String goldenName,
-    required FilmStripLayout layout,
+    required SceneLayout layout,
     Widget? goldenBackground,
     m.Color qrCodeColor = m.Colors.black,
     m.Color qrCodeBackgroundColor = m.Colors.white,
@@ -231,7 +233,7 @@ class FilmStrip {
   Future<GoldenSceneMetadata> _layoutPhotos(
     List<GoldenPhoto> photos,
     Map<GoldenPhoto, (Uint8List, GlobalKey)> renderablePhotos,
-    FilmStripLayout layout, {
+    SceneLayout layout, {
     Widget? goldenBackground,
     Widget? qrCode,
     required m.Color qrCodeBackgroundColor,
@@ -242,9 +244,9 @@ class FilmStrip {
 
     late final Axis filmStripDirection;
     switch (layout) {
-      case FilmStripLayout.row:
+      case SceneLayout.row:
         filmStripDirection = Axis.horizontal;
-      case FilmStripLayout.column:
+      case SceneLayout.column:
         filmStripDirection = Axis.vertical;
     }
 
@@ -311,7 +313,7 @@ class FilmStrip {
             mainAxisSize: MainAxisSize.min,
             crossAxisAlignment: CrossAxisAlignment.stretch,
             children: [
-              GoldenGallery(
+              GoldenScene(
                 key: galleryKey,
                 direction: filmStripDirection,
                 renderablePhotos: renderablePhotos,
@@ -434,7 +436,7 @@ class FilmStrip {
               failureImage.setPixel(x, maxHeight + y, absoluteDiffColor);
 
               // Paint this pixel in the relative severity diff image.
-              final mismatchPercent = _calculateColorMismatchPercent(goldenPixel, screenshotPixel);
+              final mismatchPercent = calculateColorMismatchPercent(goldenPixel, screenshotPixel);
               final yellowAmount = ui.lerpDouble(0.2, 1.0, mismatchPercent)!;
               failureImage.setPixel(
                 goldenWidth + x,
@@ -456,49 +458,6 @@ class FilmStrip {
       FtgLog.pipeline.info("No golden mismatches found");
     }
   }
-
-  double _calculateColorMismatchPercent(Color c1, Color c2) {
-    final doLog = false; //c1.r == 255; //c1.r != c1.g;
-    final color1 = m.Color.fromARGB(255, c1.r.toInt(), c1.g.toInt(), c1.b.toInt());
-    final hsv1 = m.HSVColor.fromColor(color1);
-
-    final color2 = m.Color.fromARGB(255, c2.r.toInt(), c2.g.toInt(), c2.b.toInt());
-    final hsv2 = m.HSVColor.fromColor(color2);
-
-    // Calculate per-component difference.
-    var deltaHue = (hsv2.hue - hsv1.hue).abs();
-    final deltaSaturation = (hsv2.saturation - hsv2.saturation).abs();
-    final deltaValue = (hsv2.value - hsv1.value).abs();
-
-    // Handle hue circularity (i.e., fact that 360 degrees go back to 0 degrees)
-    deltaHue = deltaHue > 180 ? 360 - deltaHue : deltaHue;
-
-    // Normalize each component difference.
-    deltaHue = deltaHue / 180;
-    // Other components are already in range [0, 1].
-
-    // Combine components instead single distance value.
-    //
-    // The difference formula is arbitrary, but the goal is to draw attention to differences that are likely
-    // to be important, which means reducing differences between things that aren't. In this equation we treat
-    // the value difference as the most important, such that black vs white goes directly to the max. Assuming
-    // the difference in value doesn't eat up all the difference, the hue is then given 3 times the
-    // weight of the saturation difference.
-    //
-    // This formula can easily exceed the max value of `1.0` so it's clamped. This means that many different
-    // color variations will all be at the highest intensity, but that's OK, be there is more than one color
-    // difference that's worthy of attention.
-    final difference = (deltaValue + ((deltaHue * 3) + deltaSaturation) / 4).clamp(0.0, 1.0);
-    if (doLog) {
-      print(
-          "Color 1 - red: ${c1.r}, green: ${c1.g}, blue: ${c1.b} - h: ${hsv1.hue}, s: ${hsv1.saturation}, v: ${hsv1.value}");
-      print(
-          "Color 2 - red: ${c2.r}, green: ${c2.g}, blue: ${c2.b} - h: ${hsv2.hue}, s: ${hsv2.saturation}, v: ${hsv2.value}");
-      print("Difference: $difference");
-    }
-
-    return difference;
-  }
 }
 
 class _FilmStripSetup {
@@ -532,8 +491,3 @@ class FilmStripTestContext {
 
   final scratchPad = <String, dynamic>{};
 }
-
-enum FilmStripLayout {
-  row,
-  column;
-}