Golden tests that explain what changed

Run deterministic Flutter scenarios across real device geometry, themes, locales, text scales, directions, platforms, brightness, and accessibility settings. Review every capture in a portable, searchable report.

Get started Open the live report View on GitHub

FF Golden is the visual-testing stack for Flutter Files. It combines a strict Flutter runner with a project-local publication tool without moving correctness decisions into the report layer.

Published packages: ff_golden for test execution and ff_golden_presenter for reports and publication.

Device fidelity

Apply logical size, physical size, DPR, safe areas, target platform, brightness, and high contrast to the Flutter test view.

Controlled coverage

Cover devices and environment axes with full, smoke, pairwise, or risk-priority sampling. Insufficient coverage fails instead of silently dropping cases.

Stateful scenarios

Enter text, tap controls, wait with bounded virtual time, and capture one or several named moments from the same workflow.

Review-ready output

Merge sharded run metadata with images into a searchable static report that can be opened locally, attached to CI, or published to Pages.

Five-minute example

Add the runner as a development dependency:

flutter pub add --dev 'ff_golden:^1.3.0'

Create a deterministic scenario:

import 'package:ff_golden/ff_golden.dart';
import 'package:flutter/material.dart';
import 'package:flutter_test/flutter_test.dart';

void main() {
  testFfGoldens(
    'sign in validation',
    scenario: 'authentication/invalid-email',
    coverage: GoldenCoverage(
      devices: const [
        GoldenDevice.iPhone11,
        GoldenDevice.iPad,
      ],
      themes: [GoldenTheme.light, GoldenTheme.dark],
      locales: const [Locale('en'), Locale('ar')],
      textScales: const [1, 1.5],
      sampling: GoldenSampling.pairwise,
    ),
    build: (variant) => const SignInPage(),
    interact: (context) async {
      await context.tester.enterText(
        find.byKey(const Key('email')),
        'not-an-email',
      );
      await context.tester.tap(find.text('Continue'));
    },
  );
}

Generate and verify baselines with the project-local runner:

flutter pub run ff_golden update
flutter pub run ff_golden test

Review every regenerated PNG

--update-goldens accepts a new visual contract. It is not a generic way to make a failing test pass.

Two packages, one clear boundary

ff_golden owns correctness

Test expansion, view configuration, capture, comparison, overflow diagnostics, stale-baseline checks, naming, and machine-readable run manifests.

ff_golden_presenter owns publication

Image collection, staged optimization, search and filtering, HTML generation, Docker packaging, CI artifacts, and migration automation.

The generated report never decides whether a visual test passed. It presents the runner's result and preserves the original golden files.

Choose your next step

• Follow Get started to add fonts, initial coverage, and a local report.
• Understand device fidelity before defining custom presets or changing capture scale.
• Use stateful and multi-shot scenarios for real user workflows.
• Read Migration before renaming an existing golden suite.
• Open the live FF Golden Presenter demo to explore the final review surface.

Requirements

• Flutter 3.27 or newer
• Dart 3.6 or newer
• Baselines stored and reviewed with the application source

Both packages are available under the MIT License.