Set Up SnapshotsBETA

Set up Snapshots for your Flutter app using Flutter's built-in golden file testing. Generate snapshots locally or in your own CI, then upload the generated images to Sentry for image diffing, visual review, and GitHub status checks.

Step 1: Generate Images

Sentry only needs a PNG or JPEG image of each screen, so any tool that produces one works. This guide uses Flutter's built-in flutter_test package, which can render your widgets and save the result as an image using matchesGoldenFile. Write a test for each screen or component you want to snapshot:

void main() {
  group('snapshot', () {
    testWidgets('renders home screen', (tester) async {
      await tester.pumpWidget(const MaterialApp(home: MyHomeScreen()));

      await expectLater(
        find.byType(MyHomeScreen),
        matchesGoldenFile('home_screen.png'),
      );
    });
  });
}

void main() {
  group('snapshot', () {
    testWidgets('renders home screen', (tester) async {
      await tester.pumpWidget(const MaterialApp(home: MyHomeScreen()));

      await expectLater(
        find.byType(MyHomeScreen),
        matchesGoldenFile('home_screen.png'),
      );
    });
  });
}

Put your snapshot tests in a dedicated directory, such as test/snapshots/, so you can generate and upload them independently of your other widget tests. By default, matchesGoldenFile writes the image next to the test file that calls it, so a test at test/snapshots/home_screen_test.dart produces test/snapshots/home_screen.png.

Then generate the images by running your tests with --update-goldens:

flutter test --update-goldens test/snapshots/

flutter test --update-goldens test/snapshots/

Any tool that writes PNG or JPEG files works with Sentry, including packages built on top of matchesGoldenFile like golden_toolkit and alchemist, which add support for multi-device and multi-theme goldens.

Step 2: Test Locally

Generate the images, then upload them with sentry-cli:

flutter test --update-goldens test/snapshots/

sentry-cli snapshots upload --app-id com.example.your-app test/snapshots/

flutter test --update-goldens test/snapshots/

sentry-cli snapshots upload --app-id com.example.your-app test/snapshots/

See Uploading Snapshots for the full CLI reference and metadata schema.

Step 3: Integrate Into CI

Once the local upload succeeds, wire the same commands into your CI. See Integrating Into CI for the general GitHub Actions structure.

Best Practices

• Run golden tests in a consistent environment. Flutter renders text and shapes using the host operating system's font and graphics stack, so the same test can produce different pixels on macOS, Linux, and Windows. Generate your baseline and CI snapshots on the same OS (matching your CI runner locally with something like a Linux container) to avoid spurious diffs.
• Pin your Flutter SDK version. Rendering can change between Flutter versions. Use the same version locally and in CI to keep snapshots stable.
• Isolate snapshot tests. Put them in a dedicated directory so you can generate and upload them independently of your other widget tests.