alchemist
0.15.0, released 3 days ago by betterment.dev
Streamlined golden testing tool for Flutter with local and CI-safe output support
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.
- bloc_test
A testing library that makes it easy to test blocs and cubits.
82Compare - golden_test
A zero-dependency wrapper for Flutter golden tests with theme, locale, and multi-device support.
79Compare - golden_screenshot
Utilities to automate screenshot generation using Flutter's golden tests.
76Compare - elementary_test
Testing library for apps built with the Elementary architecture.
68Compare
Works with
Packages commonly used together with alchemist: ones it builds on, ones built on it, and its own family.
- equatablealchemist depends on itProvides value‑based equality for Dart objects without manual == and hashCode.
- material_uialchemist depends on itOfficial Flutter Material UI library implementing Google’s Material Design system.
- cupertino_uialchemist depends on itOfficial Flutter Cupertino design library implementing Apple HIG iOS and macOS user interfaces.