print_widget library

Capture Flutter widgets and pages as PNG screenshots for visual verification.

This library provides two APIs:

Session API (recommended for CLI usage):

Standalone test API (for direct use in Flutter tests):

Classes

CropRegion
A named rectangular region to extract from a screenshot, in logical pixels.
DeviceFrame
A device specification that controls the viewport and output dimensions of a screenshot.
PrintConfig
Configuration for the standalone test API (printWidget, etc.).
PrintEntry
A single screenshot entry defining what to capture.
PrintManifest
The full manifest generated alongside screenshots.
PrintManifestEntry
A single entry in the screenshot manifest.
PrintSession
Configuration for a screenshot capture session.
PrintState
A named visual state of a widget or page.

Enums

PrintType
The rendering mode for a printable widget.
StateOutputMode
How state names are placed in the output file path.

Mixins

Printable
A mixin that allows a widget to describe its own screenshot metadata.

Properties

loadedFontFamilies → Set<String>
Set of font family names that were successfully loaded.
final

Functions

appWrapperFromMaterialApp({ThemeData? theme, ThemeData? darkTheme, Locale? locale, Iterable<LocalizationsDelegate>? localizationsDelegates}) → AppWrapper
Creates an AppWrapper from common MaterialApp parameters.
cropsFromMap(Map<String, Rect> crops) → List<CropRegion>
Converts a Map<String, Rect> into the list form used internally.
loadCropsFromJson(String jsonPath) → List<CropRegion>
Loads crop regions from a JSON file.
loadCustomFonts(Map<String, List<String>> fontFamilies) → Future<void>
Loads additional fonts from file paths.
loadPackageFonts(String packageName) → Future<void>
Loads fonts declared in a package's pubspec.yaml.
loadPrintWidgetFonts({String? projectRoot}) → Future<void>
Loads bundled Roboto + MaterialIcons and auto-detects project fonts.
page(String name, Widget widget, {List<DeviceFrame>? devices, Future<void> setup(WidgetTester tester)?, double? scrollExtent, double? scrollTo, AppWrapper? appWrapper, Map<String, Rect>? crops, String? cropsFrom}) → PrintEntry
Creates a full-screen page entry.
pages(String name, {required List<PrintState> states, List<DeviceFrame>? devices, Future<void> setup(WidgetTester tester)?, double? scrollExtent, double? scrollTo, AppWrapper? appWrapper, Map<String, Rect>? crops, String? cropsFrom}) → PrintEntry
Creates a grouped page entry with multiple visual states.
printAllEntries(WidgetTester tester, {required List<PrintEntry> entries, required PrintSession session, PrintConfig? config}) → Future<List<PrintManifestEntry>>
Renders all entries from a print list and returns manifest entries.
printEntry(WidgetTester tester, {required PrintEntry entry, required PrintSession session, DeviceFrame? deviceOverride, PrintConfig? config}) → Future<List<PrintManifestEntry>>
Renders a single PrintEntry using a PrintSession.
printWidget(WidgetTester tester, {required String name, required Widget widget, DeviceFrame? device, PrintConfig config = const PrintConfig()}) → Future<void>
Captures a single widget as a golden PNG file.
printWidgetOnDevices(WidgetTester tester, {required String name, required Widget widget, required List<DeviceFrame> devices, PrintConfig config = const PrintConfig()}) → Future<void>
Captures the same widget across multiple device frames.
printWidgets(WidgetTester tester, {required Map<String, Widget> widgets, DeviceFrame? device, PrintConfig config = const PrintConfig()}) → Future<void>
Captures a list of widgets, each with its own name.
printWidgetThemed(WidgetTester tester, {required String name, required Widget widget, ThemeData? lightTheme, ThemeData? darkTheme, DeviceFrame? device, PrintConfig config = const PrintConfig()}) → Future<void>
Captures light and dark variants of a widget.
processEntryCrops({required String goldenPath, required Map<String, Rect>? inlineCrops, required String? cropsFromJson, required double pixelRatio, String cropSubdir = 'crops'}) → Future<String?>
Convenience: resolves an entry's crops (inline or from JSON) and writes them to <goldenDir>/crops/ next to the golden PNG.
state(String name, Widget widget, {Future<void> setup(WidgetTester tester)?}) → PrintState
Creates a PrintState with the given name and widget.
widget(String name, Widget widget, {Size? size, List<DeviceFrame>? devices, Future<void> setup(WidgetTester tester)?, double? scrollExtent, double? scrollTo, AppWrapper? appWrapper, Map<String, Rect>? crops, String? cropsFrom}) → PrintEntry
Creates a centered widget entry.
widgets(String name, {required List<PrintState> states, Size? size, List<DeviceFrame>? devices, Future<void> setup(WidgetTester tester)?, AppWrapper? appWrapper, Map<String, Rect>? crops, String? cropsFrom}) → PrintEntry
Creates a grouped widget entry with multiple visual states.
writeCropsToDisk({required String sourcePngPath, required List<CropRegion> regions, required String outputDir, required double pixelRatio}) → Future<List<String>>
Crops a source PNG into per-region PNGs.

Typedefs

AppWrapper = Widget Function(Widget child)
A function that wraps a widget in a top-level app shell.