golden_test 2.2.0

A utility Flutter plugin for writing golden tests that streamlines adding golden tests to your project

2.2.0

New features

• Keyboard: goldenTest takes a keyboard, which shows the software keyboard over the bottom of the screen for the whole test, so a golden captures how a screen lays out while someone is typing. The view reports it as a bottom viewInsets, as a device does, so a Scaffold with resizeToAvoidBottomInset shrinks its body, one without it is covered, and content that no longer fits overflows. It takes the taps over its area, as on a device. GoldenKeyboard picks the TextInputType (letters, email, URL, Twitter, web search, number pad, phone pad, and the iOS digits-and-punctuation layer for datetime and signed numbers), the style (GoldenKeyboardStyle.ios or .android) and optionally the height. See README § Keyboard.
• Keyboard on focus, opt-in: with goldenTestSimulateKeyboard = true in flutter_test_config.dart, or simulateKeyboard: true on a single goldenTest, the keyboard appears by itself when a text field in the widget under test gains focus and hides when it loses focus. It is built from what the field asks the platform for, so its layout follows the field's keyboardType and its style the device's platform. As on a device, a field with TextInputType.none and a device with a desktop platform open no keyboard. While it is on, the harness leaves viewInsets to the widget under test, so a test that sets tester.view.viewInsets itself is no longer shrunk by the harness. It is off by default, because turning it on changes every golden that focuses a field.
• Device.platform: devices carry an optional TargetPlatform, which picks the keyboard drawn when GoldenKeyboard has no style of its own. Device.iphone15Pro() and Device.ipadPro12() are iOS, Device.pixel9ProXL() is Android and Device.browser() is macOS, which shows no keyboard on focus. It does not change the platform the widget under test is built for.

2.1.1

Fixes

• Failure images no longer overwrite each other across variants — without goldenTestDifferenceTolerance, Flutter's own comparator was used. It writes every failure to one failures/ folder next to the test file, named after the golden file only. All locales, themes, devices and text scales of a test share that name, so each failing variant overwrote the previous one and only the last one was left. goldenTest now uses the package comparator with a tolerance of 0 unless the project set its own comparator, so failure images always land next to each variant's golden file, e.g. goldens/en/light/failures/. goldenTestDifferenceTolerance still sets the tolerance. If your CI uploads test/failures/ or your .gitignore ignores only test/failures/, change them to **/goldens/**/failures/.
• Diff images are freed after each comparison — the package comparator never disposed the comparison result, so its diff images leaked on every failure and on every pass within the tolerance.

2.1.0

New features

• Navigator builder: goldenTest takes a navigatorBuilder, and goldenTestNavigatorBuilder sets one for every test. In the harness the root navigator is the only one, so every route pushed from the widget under test (dialogs, sheets, menus, pages) is built next to it. Providers returned from builder never reached those routes, so they failed to build. navigatorBuilder wraps the root navigator, so what it provides is visible to every route. Both are typed GoldenTestNavigatorBuilder, which receives the navigator as a non-null Widget, for wrappers around goldenTest that forward it. See README § Navigator Builder.

2.0.1

Fixes

• Goldens no longer fail when the widget under test builds its own app — the screenshot was taken of find.byType(MaterialApp), which matched both the harness's app and the one under test. The test failed with matched too many widgets and no golden was written, including under --update-goldens. Server-driven UI, storybook-style harnesses and nested navigators all hit this. The snapshot is now anchored to a private root widget, so it resolves to a single widget whatever the builder returns. Existing goldens are byte-identical and do not need regenerating.

2.0.0

Breaking changes

• Migrated to material_ui — Flutter 3.47 decoupled Material (and Cupertino) from the core SDK into standalone material_ui/cupertino_ui packages on pub.dev, deprecating package:flutter/material.dart. golden_test now imports package:material_ui/material_ui.dart instead, and the minimum supported Flutter version is now 3.47.0 (Dart SDK >=3.13.0). Projects on older Flutter versions will need to stay on golden_test 1.x.
• Framework localization delegates are now built in — GlobalMaterialLocalizations, GlobalWidgetsLocalizations and GlobalCupertinoLocalizations are appended automatically, so goldenTestLocalizationsDelegates only needs your own app's delegates. Remove the framework ones from your config; you no longer need to import them, or to depend on flutter_localizations/cupertino_ui just for tests. This also sidesteps the ambiguous_import that otherwise occurs because flutter_localizations still exports deprecated copies of the Material and Cupertino delegates that material_ui/cupertino_ui now own. Delegates you supply are resolved before the built-in ones, so overriding still works.
• Network images are stubbed by default — goldenTestStubNetworkImages defaults to true, so any NetworkImage now resolves to a placeholder instead of failing to load. Goldens that contain network images will change: they previously captured a blank or error state and now show the placeholder, so they need regenerating. If you already stub network images yourself, note that golden_test installs its stub before the test body: a debugNetworkImageHttpClientProvider or HttpOverrides set in flutter_test_config.dart is superseded — set goldenTestStubNetworkImages = false to keep your own. Stubs installed inside globalSetup or a test's setup still win, since those run after, and are unaffected.

New features

• AI agent skills — the package now ships three Agent Skills under skills/, installable with dart run skills@ get: golden_test-setup (wiring flutter_test_config.dart to your app's themes, locales and fonts), golden_test-widget (component goldens) and golden_test-route (screen goldens). They cover which test axes are worth their cost, deriving edge cases from branches in your own formatting code, and reading a failing golden — see README § AI Agent Skills.
• Built-in network image stub — golden tests no longer time out or produce flaky output when the widget tree loads images from the network. Any NetworkImage is resolved from a placeholder out of the box, no setup required, wherever it appears — Image.network, FadeInImage, a DecorationImage in a BoxDecoration, or a custom widget. Other dart:io HTTP traffic is left alone, so a repository call fired from the widget tree still behaves as it did. Opt out with goldenTestStubNetworkImages = false, or replace the placeholder via goldenTestNetworkImageStubPng.
• Image loader hook — goldenTestImageLoaderSetups lets any package register a per-test image-loading stub, for loaders that don't go through NetworkImage. It's a list, so several packages can register without clobbering one another. CachedNetworkImage is supported this way by the companion golden_test_cached_network_image package, which keeps cached_network_image and flutter_cache_manager out of the dependency graph of projects that don't use them — see README § CachedNetworkImage support.

Fixes

• Device.copyWith no longer drops name — omitting name reset it to null, which made the golden path fall back to default and caused distinct devices in one supportedDevices list to share a single golden file.

1.1.2

Released from the 1.x maintenance branch, for projects still on Flutter below 3.47. Same fix as 2.0.1.

Fixes

• Goldens no longer fail when the widget under test builds its own app — the screenshot was taken of find.byType(MaterialApp), which matched both the harness's app and the one under test. The test failed with matched too many widgets and no golden was written, including under --update-goldens. Server-driven UI, storybook-style harnesses and nested navigators all hit this. The snapshot is now anchored to a private root widget, so it resolves to a single widget whatever the builder returns. Existing goldens are byte-identical and do not need regenerating.

1.1.1

Fixes

• Bundled Roboto font — The package now ships its own Roboto font, so the device frame's status bar time renders correctly in any consuming project regardless of whether it bundles Roboto itself.

1.1.0

Fixes

• Async hooks now awaited — globalSetup, setup, and tearDown callbacks are now properly awaited inside goldenTest, preventing race conditions with font loading, Intl.defaultLocale, and mock wiring.

Improvements

• Typed tags parameter — goldenTest's tags parameter is now Object? (matching Flutter's own testWidgets signature) instead of dynamic, with dartdoc clarifying the accepted shapes (String, Tag, Iterable).

New features

• Text-scale matrix — supportedTextScales and goldenTestSupportedTextScales add text scale as a test axis. Optional [AndroidFontScale] / [IosDynamicTypeScale] enums and accessibility preset lists are available.

1.0.1

• Fixed README images not rendering on pub.dev by using absolute URLs.

1.0.0

First stable release under semantic versioning; the public API is now versioned with breaking changes reserved for major bumps.

Breaking changes

• Golden frame — Redesigned the status bar and bottom bar UI rendered around the widget under test. All existing golden screenshots will need to be regenerated (flutter test --update-goldens).

Improvements

• Example app — Expanded and clearer examples demonstrating real usage patterns.
• Documentation — Reworked and expanded docs so setup and options are easier to follow.

0.1.7

1. Added tags parameter to properly proxy it to testWidgets

0.1.6

1. New Feature: Added subdirectory parameter to goldenTest for organizing golden files into custom subdirectories
   • Allows per-test configuration of golden file organization
   • Useful for managing multiple apps with different design tokens
   • Supports nested subdirectories (e.g., 'design_system/v2')
   • Path structure: goldens/[subdirectory]/locale/theme/[device]/name.png

0.1.5

1. Refactor device configuration system to support three distinct configuration levels:

   • New: Added goldenTestDefaultDevices for setting global default device(s)
   • Improved: goldenTestSupportedDevices now exclusively for multi-device testing
   • Changed: supportedDevices parameter is now nullable, enabling proper configuration hierarchy
   • Enhanced: Device selection logic now follows clear priority: per-test override > multi-device mode > global default
   • Fixed: Golden file paths now intelligently include device names only when testing multiple devices

   This change makes device configuration more intuitive and eliminates the need to pass supportMultipleDevices: true just to use a globally-defined single device.

2. Improved formatting

3. Updated dependencies

4. Updated example project

5. Updated documentation

6. Drop deprecated .withOpacity

0.1.4

Fix directory for generating failure screenshots.

0.1.3

Add option to precache assets.

0.1.2

Add option to set difference tolerance at which tests are considered failing.

0.1.1

Add read.me to example project.

0.1.0

Initial release of goldenTest method which helps writing Golden Tests very easily by pumping Flutter Widgets.

Features:

1. goldenTest - utility method for generating screenshots
2. Supporting multiple locales.
3. Supporting multiple localizations.
4. Supporting light and dark mode.