golden_matrix

golden_matrix

pub package test codecov

Matrix-based visual regression testing for Flutter. Declare themes, locales, devices, text scales β€” get all combinations, sampled if you want, with HTML + JUnit reports for CI.

πŸ“– Docs Β· Quick start Β· CI integration Β· Migrating from golden_toolkit

Install

# pubspec.yaml
dev_dependencies:
  golden_matrix: ^1.6.0

// test/flutter_test_config.dart β€” load real fonts for text rendering
import 'dart:async';
import 'package:golden_matrix/golden_matrix.dart';

Future<void> testExecutable(FutureOr<void> Function() testMain) async {
  await loadAppFonts();
  return testMain();
}

30-second example

import 'package:flutter/widgets.dart';
import 'package:golden_matrix/golden_matrix.dart';

void main() {
  matrixGolden(
    'PrimaryButton',
    scenarios: [
      MatrixScenario('default', builder: () => const PrimaryButton(label: 'OK')),
      MatrixScenario('disabled', builder: () => const PrimaryButton(label: 'OK', enabled: false)),
    ],
    axes: MatrixAxes(
      themes: [MatrixTheme.light, MatrixTheme.dark],
      locales: [Locale('en'), Locale('ar')],
      textScales: [1.0, 2.0],
      devices: [MatrixDevice.phoneSmall, MatrixDevice.phoneLarge],
    ),
  );
  // 2 scenarios Γ— 2 themes Γ— 2 locales Γ— 2 scales Γ— 2 devices = 32 golden files
}

flutter test --update-goldens  # generate baselines
flutter test                   # run regression tests

What's in the box

  • Declarative matrix β€” themes Γ— locales Γ— devices Γ— text scales Γ— directions, all combinations automatically
  • Three entry points β€” matrixGolden (components), screenMatrixGolden (full screens), componentMatrixGolden (intrinsic-size primitives)
  • Typed scenarios β€” MatrixScenario.typed<T> attaches a compile-time-checked state payload, so one builder covers loading/loaded/error/empty
  • Sampling β€” full, smoke, pairwise (constraint-aware, so exclusion rules never silently drop pair coverage), priorityBased to keep CI fast
  • HTML / JSON / Markdown / JUnit XML reports (opt-in via reportFormats) β€” inline pixel-diff thumbnails on failure, the phase a failure came from (build / pump / setup / comparison), and measured per-combination timings
  • Stale + overflow detection β€” orphan goldens and RenderFlex overflow surface automatically
  • RTL auto-inference across CLDR's right-to-left languages and scripts (ar, he, fa, ur, ps, sd, ug, ckb, … and az-Arab by script); replace it wholesale with MatrixAxes.directionResolver
  • 20+ device presets β€” modern iPhones, Android, foldables, full iPad lineup, plus custom devices
  • Capture resolution β€” captureScale for supersampled goldens (2Γ—/3Γ— rasters); device pixelRatio stays layout-only
  • DI-friendly β€” wrapApp / wrapChild hooks for Riverpod / Bloc / Provider
  • Shared run config β€” MatrixRunConfig declares the options once; a direct argument still overrides it
  • Dry-run preview β€” inspect counts, paths, and collisions without rendering; runners warn about empty matrices and colliding golden paths on their own
  • Zero external dependencies β€” only the Flutter SDK

Read the full docs β†’

Requirements

  • Flutter SDK >= 3.16.0
  • Dart SDK >= 3.2.0

License

MIT

Libraries

golden_matrix