Merge pull request #58 from eBay/feature/expose-device-size-api

Feature/expose device size api

Author: coreysprague

packages/golden_toolkit/CHANGELOG.md

@@ -29,6 +29,26 @@ Future releases will likely consolidate these APIs.
 
 Thanks to @christian-muertz for this enhancement.
 
+### Added additional utility functions for preparing for goldens
+
+Extracted out some public extension methods that were previously private implementation details of ```multiScreenGolden``` & ```screenMatchesGolden```
+
+Added the following extensions. These can be used with any vanilla golden assertions and do not require ```multiScreenGolden```, ```screenMatchesGolden```, or ```GoldenBuilder```.
+
+```dart
+// configures the simulated device to mirror the supplied device configuration (dimensions, pixel density, safe area, etc)
+tester.binding.applyDeviceOverrides(device);
+
+// resets any configuration applied by applyDeviceOverrides
+tester.binding.resetDeviceOverrides();
+
+// runs a block of code with the simulated device settings and automatically clears upon completion
+tester.binding.runWithDeviceOverrides(device, body: (){});
+
+// convenience helper for configurating the safe area... the built-in paddingTestValue is difficult to work with
+tester.binding.window.safeAreaTestValue = EdgeInsets.all(8);
+```
+
 ### Misc Changes
 
 A few API / parameters were marked as deprecated and will be removed in future releases.

packages/golden_toolkit/lib/golden_toolkit.dart

@@ -13,3 +13,4 @@ export 'src/font_loader.dart' show loadAppFonts;
 export 'src/golden_builder.dart';
 export 'src/multi_screen_golden.dart';
 export 'src/testing_tools.dart' hide compareWithGolden;
+export 'src/widget_tester_extensions.dart';

packages/golden_toolkit/lib/src/multi_screen_golden.dart

@@ -8,14 +8,13 @@
 
 //ignore_for_file: deprecated_member_use_from_same_package
 
-import 'dart:ui';
-
 import 'package:flutter/material.dart';
 import 'package:flutter_test/flutter_test.dart';
 
 import 'configuration.dart';
 import 'device.dart';
 import 'testing_tools.dart';
+import 'widget_tester_extensions.dart';
 
 Future<void> _twoPumps(Device device, WidgetTester tester) async {
   await tester.pump();
@@ -66,10 +65,12 @@ Future<void> multiScreenGolden(
   assert(devices?.isNotEmpty ?? false);
   final deviceSetupPump = deviceSetup ?? _twoPumps;
   for (final device in devices) {
-    await tester._applyDeviceOverrides(
+    await tester.binding.runWithDeviceOverrides(
       device,
-      overriddenHeight: overrideGoldenHeight,
-      operation: () async {
+      body: () async {
+        if (overrideGoldenHeight != null) {
+          await tester.binding.setSurfaceSize(Size(device.size.width, overrideGoldenHeight));
+        }
         await deviceSetupPump(device, tester);
         await compareWithGolden(
           tester,
@@ -86,53 +87,3 @@ Future<void> multiScreenGolden(
     );
   }
 }
-
-extension on WidgetTester {
-  Future<void> _applyDeviceOverrides(
-    Device device, {
-    double overriddenHeight,
-    Future<void> Function() operation,
-  }) async {
-    await binding.setSurfaceSize(Size(device.size.width, overriddenHeight ?? device.size.height));
-    binding.window.physicalSizeTestValue = device.size;
-    binding.window.devicePixelRatioTestValue = device.devicePixelRatio;
-    binding.window.textScaleFactorTestValue = device.textScale;
-    binding.window.paddingTestValue = _FakeWindowPadding(
-      bottom: device.safeArea.bottom,
-      left: device.safeArea.left,
-      right: device.safeArea.right,
-      top: device.safeArea.top,
-    );
-    binding.window.platformBrightnessTestValue = device.brightness;
-
-    await operation();
-
-    binding.window.clearDevicePixelRatioTestValue();
-    binding.window.clearPlatformBrightnessTestValue();
-    binding.window.clearPaddingTestValue();
-    binding.window.clearTextScaleFactorTestValue();
-    binding.window.clearPhysicalSizeTestValue();
-    await binding.setSurfaceSize(null);
-  }
-}
-
-class _FakeWindowPadding implements WindowPadding {
-  const _FakeWindowPadding({
-    this.bottom = 0,
-    this.left = 0,
-    this.right = 0,
-    this.top = 0,
-  });
-
-  @override
-  final double bottom;
-
-  @override
-  final double left;
-
-  @override
-  final double right;
-
-  @override
-  final double top;
-}

packages/golden_toolkit/lib/src/testing_tools.dart

@@ -192,23 +192,21 @@ Future<void> compareWithGolden(
     fail(
         'Golden tests MUST be run within a testGoldens method, not just a testWidgets method. This is so we can be confident that running "flutter test --name=GOLDEN" will run all golden tests.');
   }
-
   final shouldSkipGoldenGeneration = skip ?? GoldenToolkit.configuration.skipGoldenAssertion();
 
   final pumpAfterPrime = customPump ?? _onlyPumpAndSettle;
   /* if no finder is specified, use the first widget. Note, there is no guarantee this evaluates top-down, but in theory if all widgets are in the same
   RepaintBoundary, it should not matter */
   final actualFinder = finder ?? find.byWidgetPredicate((w) => true).first;
   final fileName = fileNameFactory(name, device);
+  final originalWindowSize = tester.binding.window.physicalSize;
 
   // This is a minor optimization and works around an issue with the current hacky implementation of invoking the golden assertion method.
   if (!shouldSkipGoldenGeneration) {
     await _primeImages(fileName, actualFinder);
   }
   await pumpAfterPrime(tester);
 
-  final originalWindowSize = tester.binding.window.physicalSize;
-
   if (autoHeight == true) {
     // Find the first scrollable element which can be scrolled vertical.
     // ListView, SingleChildScrollView, CustomScrollView? are implemented using a Scrollable widget.

packages/golden_toolkit/lib/src/widget_tester_extensions.dart

@@ -0,0 +1,96 @@
+import 'dart:ui';
+
+import 'package:flutter/widgets.dart';
+import 'package:flutter_test/flutter_test.dart';
+
+import 'device.dart';
+
+/// Convenience extensions for more easily configuring WidgetTester for pre-set configurations
+extension WidgetTesterExtensions on TestWidgetsFlutterBinding {
+  /// Configure the Test device for the duration of the supplied operation and revert
+  ///
+  /// [device] the desired configuration to apply
+  ///
+  /// [body] the closure you wish to be executed with the device configuration applied
+  ///
+  Future<void> runWithDeviceOverrides(
+    Device device, {
+    Future<void> Function() body,
+  }) async {
+    await applyDeviceOverrides(device);
+    try {
+      await body();
+    } finally {
+      await resetDeviceOverrides();
+    }
+  }
+
+  /// Configure the Test device to match the configuration of the supplied device
+  ///
+  /// Note: these settings will persist across multiple tests in the same file. It is recommended
+  /// that you reset upon completion.
+  ///
+  /// [device] the desired configuration to apply
+  ///
+  Future<void> applyDeviceOverrides(Device device) async {
+    await setSurfaceSize(Size(device.size.width, device.size.height));
+    this.window.physicalSizeTestValue = device.size;
+    this.window.devicePixelRatioTestValue = device.devicePixelRatio;
+    this.window.textScaleFactorTestValue = device.textScale;
+    this.window.safeAreaTestValue = device.safeArea;
+    this.window.platformBrightnessTestValue = device.brightness;
+  }
+
+  /// Resets any configuration that may be been specified by applyDeviceOverrides
+  ///
+  /// Only needs to be called if you are concerned about the result of applyDeviceOverrides bleeding over across tests.
+  Future<void> resetDeviceOverrides() async {
+    // there is an untested assumption that clearing these specific values is cheaper than
+    // calling binding.window.clearAllTestValues().
+    this.window.clearDevicePixelRatioTestValue();
+    this.window.clearPlatformBrightnessTestValue();
+    this.window.clearPaddingTestValue();
+    this.window.clearTextScaleFactorTestValue();
+    this.window.clearPhysicalSizeTestValue();
+    await setSurfaceSize(null);
+  }
+}
+
+/// Convenience extensions for configuring elements of the TestWindow
+extension TestWindowExtensions on TestWindow {
+  /// convenience wrapper for configuring the paddingTestValue
+  ///
+  /// paddingTestValue requires you creating your own class that implements WindowPadding
+  ///
+  /// [safeArea] specifies the safe area insets for all 4 edges that you wish to simulate
+  ///
+  set safeAreaTestValue(EdgeInsets safeArea) {
+    paddingTestValue = _FakeWindowPadding(
+      bottom: safeArea.bottom,
+      left: safeArea.left,
+      right: safeArea.right,
+      top: safeArea.top,
+    );
+  }
+}
+
+class _FakeWindowPadding implements WindowPadding {
+  const _FakeWindowPadding({
+    this.bottom = 0,
+    this.left = 0,
+    this.right = 0,
+    this.top = 0,
+  });
+
+  @override
+  final double bottom;
+
+  @override
+  final double left;
+
+  @override
+  final double right;
+
+  @override
+  final double top;
+}

packages/golden_toolkit/test/goldens/override_height.anything.png

@@ -162,6 +162,26 @@ Future<void> main() async {
           ],
         );
       });
+
+      testGoldens('Should set to exact height if override height is specified', (tester) async {
+        await tester.pumpWidget(Center(
+          // We center here so the Container is not forced to go full height
+          child: Container(color: Colors.red, height: 50),
+        ));
+
+        await multiScreenGolden(
+          tester,
+          'override_height',
+          overrideGoldenHeight: 300,
+          devices: [
+            const Device(
+              name: 'anything',
+              size: Size(100, 200),
+              brightness: Brightness.light,
+            )
+          ],
+        );
+      });
     });
   });
 }