adaptive_golden_test 1.2.0

A Flutter package to generate adaptive golden files during widget tests.

adaptive_golden_test

A Flutter package to generate adaptive golden files during widget tests.

Table of Contents

1. Features
2. Getting Started
3. Usage
   • Rendering Custom Fonts
   • Setting Up Test Devices
   • Configuring Difference Threshold
   • Enforcing Test Platform
   • Writing a Test
4. Migration Guide
5. Additional Information

Features

Use this package in your tests to:

• Generate golden files for different devices during tests
• Load fonts
• Set window sizes and pixel density
• Await image rendering
• Render physical and system UI layers
• Render a keyboard during tests
• Set a preferred OS for running tests
• Configure a difference tolerance threshold for file comparison

Getting Started

1. Add adaptive_test to your dev dependencies.

2. Create a flutter_test_config.dart file at the root of your test folder with a testExecutable function:

Future<void> testExecutable(FutureOr<void> Function() testMain) async {
  await testMain();
}

copied to clipboard

For more information, see the official Flutter documentation.

Usage

Rendering Custom Fonts

1. Add your fonts to your app assets folders.
2. Add your fonts to your Flutter assets in pubspec.yaml:

flutter:
  fonts:
  - family: Roboto
    fonts:
      - asset: fonts/Roboto-Black.ttf

copied to clipboard

3. In your flutter_test_config.dart, call loadFonts():

Future<void> testExecutable(FutureOr<void> Function() testMain) async {
  TestWidgetsFlutterBinding.ensureInitialized();
  await loadFonts();
  await testMain();
}

copied to clipboard

ℹ️ loadFonts() loads fonts from pubspec.yaml and from every separate package dependency as well.

Setting Up Test Devices

1. Define a set of device variants:

final defaultDeviceConfigs = {
  Devices.ios.iPhoneSE,
  Devices.ios.iPhone12,
  Devices.ios.iPad,
  Devices.linux.laptop,
  Devices.android.pixel4,
  Devices.android.samsungGalaxyS20,
};

copied to clipboard

2. Use the AdaptiveTestConfiguration singleton to set variants:

Future<void> testExecutable(FutureOr<void> Function() testMain) async {
  TestWidgetsFlutterBinding.ensureInitialized();
  AdaptiveTestConfiguration.instance
    ..setDeviceVariants(defaultDeviceConfigs);
  await loadFonts();
  await testMain();
}

copied to clipboard

Configuring Difference Threshold

To allow for small pixel differences between processors, add setupFileComparatorWithThreshold() to your flutter_test_config.dart:

Future<void> testExecutable(FutureOr<void> Function() testMain) async {
  TestWidgetsFlutterBinding.ensureInitialized();
  AdaptiveTestConfiguration.instance
    ..setDeviceVariants(defaultDeviceConfigs);
  await loadFonts();
  setupFileComparatorWithThreshold();
  await testMain();
}

copied to clipboard

Enforcing Test Platform

Configure AdaptiveTestConfiguration to enforce a specific test platform:

Future<void> testExecutable(FutureOr<void> Function() testMain) async {
  TestWidgetsFlutterBinding.ensureInitialized();
  AdaptiveTestConfiguration.instance
    ..setEnforcedTestPlatform(TargetPlatform.macOS)
    ..setDeviceVariants(defaultDeviceConfigs);
  await loadFonts();
  setupFileComparatorWithThreshold();
  await testMain();
}

copied to clipboard

To skip tests instead of throwing an error on unintended platforms:

AdaptiveTestConfiguration.instance
  ..setEnforcedTestPlatform(TargetPlatform.macOS)
  ..setFailTestOnWrongPlatform(false)
  ..setDeviceVariants(defaultDeviceConfigs);

copied to clipboard

Writing a Test

Use the testAdaptiveWidgets function:

void main() {
  testAdaptiveWidgets(
    'Test description',
    (tester, variant) async {},
  );
}

copied to clipboard

Wrap the widget you want to test with AdaptiveWrapper.

await tester.pumpWidget(
  AdaptiveWrapper(
    device: variant,
    orientation: Orientation.portrait,
    isFrameVisible: true,
    showVirtualKeyboard: false,
    child: const App(),
  ),
);

copied to clipboard

Use the WidgetTester extension expectGolden to generate golden files.

await tester.expectGolden<App>(variant);

copied to clipboard

A basic test should looks like this:

void main() {
  testAdaptiveWidgets(
    '$App render without regressions',
    (tester, variant) async {
      await tester.pumpWidget(
        AdaptiveWrapper(
          device: variant,
          orientation: Orientation.portrait,
          isFrameVisible: true,
          showVirtualKeyboard: false,
          child: const App(),
        ),
      );

      await tester.expectGolden<App>(variant);
    },
  );
}

copied to clipboard

Contributing

Pull requests are welcome. For major changes, please open an issue first to discuss what you would like to change.

Special thanks

I want to thank previous developers for their work:

• BAM: 100 people company developing and designing multiplatform applications with React Native and Flutter using the Lean & Agile methodology.

Maintainer

👤 Martin Jablečník

• Website: martin-jablecnik.cz
• Github: @mjablecnik
• Blog: dev.to/mjablecnik

Show your support

Give a ⭐️ if this project helped you!