philiprehberger_snapshot_test

Visual snapshot testing for Flutter widgets with golden file comparison

Requirements

• Flutter >= 3.24.0
• Dart >= 3.6

Installation

Add to your pubspec.yaml:

dev_dependencies:
  philiprehberger_snapshot_test: ^0.2.0

Then run:

flutter pub get

Usage

import 'package:flutter_test/flutter_test.dart';
import 'package:philiprehberger_snapshot_test/snapshot_test.dart';

void main() {
  testWidgets('widget snapshot', (tester) async {
    await SnapshotTester.testWidget(
      tester,
      widget: const MyWidget(),
      goldenFileName: 'goldens/my_widget.png',
    );
  });
}

Multi-Device Testing

Test a widget across multiple device configurations at once:

testWidgets('multi-device snapshot', (tester) async {
  await SnapshotTester.testMultiDevice(
    tester,
    widget: const MyWidget(),
    goldenFilePrefix: 'goldens/my_widget',
  );
});

Theme Comparison

Compare light and dark theme rendering side by side:

testWidgets('theme comparison', (tester) async {
  await SnapshotTester.testThemes(
    tester,
    widget: const MyWidget(),
    goldenFilePrefix: 'goldens/my_widget',
  );
});

Custom Device Configs

Define your own device configurations:

const galaxyFold = SnapshotConfig(
  name: 'Galaxy Fold',
  size: Size(280, 653),
  devicePixelRatio: 3.0,
);

testWidgets('custom device', (tester) async {
  await SnapshotTester.testWidget(
    tester,
    widget: const MyWidget(),
    goldenFileName: 'goldens/my_widget_fold.png',
    config: galaxyFold,
  );
});

Orientation Testing

Test a widget in both portrait and landscape orientations:

testWidgets('orientation snapshot', (tester) async {
  await SnapshotTester.testOrientations(
    tester,
    widget: const MyWidget(),
    goldenFilePrefix: 'goldens/my_widget',
  );
});

State Testing

Test multiple widget states with a single call:

testWidgets('state snapshots', (tester) async {
  await SnapshotTester.testStates(
    tester,
    states: {
      'empty': const MyWidget(items: []),
      'loaded': const MyWidget(items: ['a', 'b']),
      'error': const MyWidget(error: 'Something went wrong'),
    },
    goldenFilePrefix: 'goldens/my_widget',
  );
});

Accessibility Testing

Test with multiple text scale factors for accessibility:

testWidgets('accessibility snapshot', (tester) async {
  await SnapshotTester.testAccessibility(
    tester,
    widget: const MyWidget(),
    goldenFilePrefix: 'goldens/my_widget',
  );
});

Test with large text scaling using config variants:

testWidgets('large text snapshot', (tester) async {
  await SnapshotTester.testWidget(
    tester,
    widget: const MyWidget(),
    goldenFileName: 'goldens/my_widget_large_text.png',
    config: SnapshotConfig.iPhone14.withLargeText(),
  );
});

API

SnapshotConfig

Property / Method	Description
name	Device name for identification
size	Device screen size
devicePixelRatio	Device pixel ratio (default: 1.0)
textScaleFactor	Text scale factor (default: 1.0)
landscape()	Returns a copy with width/height swapped
withDarkMode()	Returns a copy with name suffixed ' Dark'
withLargeText()	Returns a copy with 1.5x text scale
iPhone14	Preset: 390x844 @3x
iPhone14ProMax	Preset: 430x932 @3x
pixel7	Preset: 412x915 @2.75x
pixel8	Preset: 412x924 @2.75x
galaxyS24	Preset: 360x780 @3x
iPhoneSE	Preset: 375x667 @2x
iPadPro12	Preset: 1024x1366 @2x
desktop	Preset: 1440x900 @1x
allDevices	List of all preset configs

SnapshotWrapper

Property	Description
child	The widget to test
config	Device configuration to apply
theme	Optional ThemeData
locale	Optional Locale

SnapshotTester

Method	Description
testWidget(tester, {widget, goldenFileName, config?, theme?, locale?})	Test a widget against a single golden file
testMultiDevice(tester, {widget, goldenFilePrefix, configs?, theme?})	Test across multiple device configurations
testThemes(tester, {widget, goldenFilePrefix, config?, lightTheme?, darkTheme?})	Test with light and dark themes
testOrientations(tester, {widget, goldenFilePrefix, config?, theme?})	Test portrait and landscape orientations
testStates(tester, {states, goldenFilePrefix, config?, theme?})	Test multiple widget states
testAccessibility(tester, {widget, goldenFilePrefix, config?, theme?})	Test normal, large, and extra large text

Development

flutter pub get
flutter analyze
flutter test

To update golden files:

flutter test --update-goldens

Support

If you find this project useful:

:star: Star the repo

:bug: Report issues

:bulb: Suggest features

:heart: Sponsor development

:globe_with_meridians: All Open Source Projects

:computer: GitHub Profile

:link: LinkedIn Profile

License

MIT