Zero third-party dependencies

One test to
rule them all.

Every theme, every locale, every device and every text scale your app supports, rendered and compared by a single goldenTest call. Golden tests for Flutter, without the boilerplate.

$dart pub add golden_test --dev

Get started View on GitHub

Your Flutter: 3.47+golden_test 2.x3.19.6 – 3.46golden_test 1.x
pub points: 160/160
License: BSD-3

dart pub add picks the right line for your SDK.

00:04 +12: All tests passed!

en/lighten/darkes/lightes/dark iphone 15 pro

pixel 9 pro xl

ipad pro 12

test/example_screen_test.dart

void main() {
  goldenTest(
    name: 'ExampleScreen',
    builder: (_) => const ExampleScreen(),
  );
}

Locales, themes and devices come from flutter_test_config.dart ↓

test/

Runs like any other Flutter test.

golden_test is built on flutter_test, so there is nothing new to install or learn. Set your axes once, then run the command you already use.

Add the package

Flutter 3.47+ gets 2.x. Older Flutter, down to 3.19.6, gets 1.x.
```
$ dart pub add golden_test --dev
```

Set your axes once

Light and dark are on by default. Any single test can override any axis.

test/flutter_test_config.dart

Future<void> testExecutable(
  FutureOr<void> Function() testMain,
) async {
  goldenTestSupportedLocales = const [
    Locale('en'),
    Locale('es'),
  ];
  goldenTestDefaultDevices = const [
    Device.iphone15Pro(),
    Device.pixel9ProXL(),
    Device.ipadPro12(),
  ];
  return testMain();
}

Run it

Renders every variant and compares it with the golden on disk. One changed pixel fails the test.
```
$ flutter test
00:00 +0: loading test/example_screen_test.dart
00:04 +12: All tests passed!
```
- goldens/en/light/iphone 15 pro/ExampleScreen.pngmatches
- goldens/en/light/pixel 9 pro xl/ExampleScreen.pngmatches
- goldens/en/light/ipad pro 12/ExampleScreen.pngmatches
- goldens/en/dark/iphone 15 pro/ExampleScreen.pngmatches
- 8 more in test/goldens/match

test/goldens/

Every axis is one parameter.

Pick the axes below. The call on the left is the test, and the images on the right are the files it writes, at the paths it writes them to. Every image was rendered by golden_test from the example app.

supportedLocales

supportedThemes

supportedDevices

supportedTextScales

test/example_screen_test.dart

8golden files from one call

00:03 +8: All tests passed!

At 2.0× the example app breaks, and the test fails with Flutter's own error: A RenderFlex overflowed by 8.0 pixels on the bottom. The golden is still written, so you can see exactly what broke.

failures/

A two-line commit moved 195,150 pixels.

The two lines changed values in the quick actions: a corner radius from 16 to 6 and a gap from 8 to 16. Code review shows two lines with no picture attached. The golden shows every pixel they moved. Compare the two renders side by side, with a swipe, or as an onion skin.

masterImage · diff · testImage

The committed golden: ExampleScreen, English, light theme, iPhone 15 Pro — _masterImage.pngcommitted

Every pixel that differs between the two renders, in magenta — diff195,150 px

The new render of the same screen after the change — _testImage.pngthis commit

← _masterImage.png_testImage.png →

mastertest

What the test prints

flutter test

00:02 +0 -1: ExampleScreen [E]
  Golden "goldens/en/light/iphone%2015%20pro/ExampleScreen.png": Pixel test failed, 6.48%, 195150px diff detected.
  Failure feedback can be found at test/goldens/en/light/iphone 15 pro/failures

What it writes to failures/ (cropped, 1:1 pixels)

Crop of the master image — ExampleScreen_masterImage.pngThe golden in git

Crop of the test image — ExampleScreen_testImage.pngWhat renders now

Crop of the isolated diff — ExampleScreen_isolatedDiff.pngOnly the pixels that differ

Crop of the masked diff — ExampleScreen_maskedDiff.pngDifferences drawn over the new render

goldens/en/light/2x/

Large text breaks layouts. Drag to find where.

Every stop on the slider is a real golden of the example app at that text scale, using the platform presets golden_test ships. The screen holds up to 1.5×. From the first iOS accessibility size it starts to overflow.

ExampleScreen at text scale 1.0 — 1x/baseline

ExampleScreen at text scale 0.82 — 2x/fails

ExampleScreen at text scale 0.85 — 2x/fails

2.0×AndroidFontScale.maximum

A RenderFlex overflowed by 8.0 pixels on the bottom.The test fails, and the golden shows where.

AndroidFontScale

IosDynamicTypeScale

supportedTextScales: [
  1.0,
  ...iosAccessibilityTextScalePresets,
],

skills/

Your coding agent can write these.

golden_test ships three Agent Skills. They teach an agent to wire flutter_test_config.dart to your real themes and fonts, pick the axes worth their cost, and read a failing golden before reaching for --update-goldens.

$dart run skills@ get

golden_test-setup
One-time setup: the dependency and a flutter_test_config.dart wired to your app's themes, locales and fonts.
golden_test-widget
Goldens for widgets and design-system components in isolation.
golden_test-route
Goldens for full screens: loading, success, error, empty, scrolled, and the states only your app has.

lib/

Also in the box.

Network images, stubbed: Image.network and every other NetworkImage resolve to a visible placeholder, so goldens never wait on a network.
CachedNetworkImage: The companion package golden_test_cached_network_image stops it from hanging your tests.
Difference tolerance: goldenTestDifferenceTolerance(0.05) absorbs anti-aliasing drift between machines. Keep it at 0 until you have measured that drift.
Your own devices: Device takes a name, size, pixel ratio and safe-area insets, so any screen you ship to can be an axis.
Pushed routes: simulateRouteStack renders a screen as if it was pushed, back button included.
Folders per app: subdirectory: 'design_system/v2' keeps goldens for each app or package apart.

medium.com/@dm.kasperski

One test to
rule them all.

Runs like any other Flutter test.

Add the package

Set your axes once

Run it

Every axis is one parameter.

A two-line commit moved 195,150 pixels.

What the test prints

What it writes to failures/ (cropped, 1:1 pixels)

Large text breaks layouts. Drag to find where.

Your coding agent can write these.

Also in the box.

Read more about golden tests.

Flutter Golden Tests Made Easy: Visual Regression Testing With Less Boilerplate

One test torule them all.

Runs like any other Flutter test.

Add the package

Set your axes once

Run it

Every axis is one parameter.

A two-line commit moved 195,150 pixels.

What the test prints

What it writes to failures/ (cropped, 1:1 pixels)

Large text breaks layouts. Drag to find where.

Your coding agent can write these.

Also in the box.

Read more about golden tests.

Flutter Golden Tests Made Easy: Visual Regression Testing With Less Boilerplate

One test to
rule them all.