Skip to content
pubscout

alchemist

0.15.0, released 3 days ago by betterment.dev

Streamlined golden testing tool for Flutter with local and CI-safe output support

Uses material_ui
$ flutter pub add alchemist
Source repository

What it does

Alchemist simplifies writing and executing golden tests in Flutter by providing declarative test scenarios and groupings. It distinguishes between local human-readable golden tests and cross-platform CI tests that use obscured text and the Ahem font to avoid font rendering discrepancies across operating systems. It also includes configurable diff thresholds, custom pumping behavior, and auto-sizing.

AI-written summary of version 0.15.0, based on the package's README and metadata. Report an inaccuracy

Use it when

  • Writing visual regression and golden tests across multiple platforms without font mismatches failing CI
  • Organizing golden tests into structured groups and scenarios in a table format
  • Needing fine-grained control over golden test diff thresholds, theming, and gestures

Skip it when

  • You only require basic unit or widget testing without visual screenshot comparisons
  • Your project cannot use Dart 3.12+ or migrate to the standalone material_ui / cupertino_ui packages required by 0.15.0

Strengths

  • Solves cross-platform font rendering issues on CI by rendering obscured text using the Ahem font
  • Provides clean `GoldenTestGroup` and `GoldenTestScenario` APIs to arrange multi-widget tests in a grid
  • Supports fine-grained configuration including pixel difference thresholds (`diffThreshold`) and custom pumping

Weaknesses

  • Version 0.15.0 introduces a breaking change requiring standalone `material_ui`/`cupertino_ui` packages and minimum Flutter 3.44 / Dart 3.12
  • Generates separate sets of golden files for CI and local platforms, increasing repository file size

Setup

Kind
Flutter widgets
Effort
Low
Code generation
No
Direct dependencies
5

Requires running tests with `flutter test --update-goldens` to generate baseline golden images.

goldenTest(
  'renders correctly',
  fileName: 'list_tile',
  builder: () => GoldenTestGroup(
    scenarioConstraints: const BoxConstraints(maxWidth: 600),
    children: [
      GoldenTestScenario(
        name: 'with title',
        child: ListTile(title: Text('ListTile.title')),
      ),
    ],
  ),
);

Alternatives

Packages that do the same job and could replace alchemist.

Works with

Packages commonly used together with alchemist: ones it builds on, ones built on it, and its own family.