widgetbook_golden_test 0.0.2

Utility for running golden tests on Widgetbook use cases.

Golden Widgetbook Tests

Automatically generate Flutter golden tests from Widgetbook use cases generated by the widgetbook_generator.

Overview

This library automates the creation of golden tests for Flutter widgets using Widgetbook use cases generated in the directories file. These files are created using the widgetbook_generator package by running dart run build_runner build -d. The runWidgetbookGoldenTests function traverses these use cases to generate golden files for visual regression testing.

Note: Only auto-generated directories files are supported. Manually editing or creating *.directories.g.dart is not intended or supported.

Usage

Import the corresponding directories file generated by widgetbook_generator. Then call runWidgetbookGoldenTests inside a main of a test file.

import '../widgetbook/main.directories.g.dart';

void main() {
  runWidgetbookGoldenTests(
    nodes: directories,
    properties: WidgetbookGoldenTestsProperties(),
  );
}

Features

• Automatic Golden Test Generation: All Widgetbook use cases are discovered and tested.
• Network Image Mocking: Handles network images for reliable golden tests. You can simulate a network image loading errors and loading state by using the special URLs "error-network-image" and "loading-network-image" respectively by default. These will trigger the errorBuilder in your Image.network widget, or an indefinite loadingBuilder. The special URLs can also be customized.
• Easy Integration: Simply add your Widgetbook use cases and run the tests. Knob values are supported as well.
• Skippable Cases: To skip a golden test for a specific use case, add [skip-golden] to its name. You can customize this tag in WidgetbookGoldenTestsProperties.
• Custom Properties: Customize properties with a custom WidgetbookGoldenTestsProperties (see more below).

How It Works

• Widgetbook use cases are defined and auto-generated in the directories file.
• The directories file is generated using the widgetbook_generator package:

dart run build_runner build -d

• The The runWidgetbookGoldenTests function traverses all use cases and generates golden files for each use case.
• Network images are mocked, based on mocktail_image_network's implementation to ensure consistent results.
• Widgetbook state is mocked so knobs work properly even if they are being used.

Customization

Use the properties in WidgetbookGoldenTestsProperties to customize the properties used in the test execution.

• To skip a golden test for a specific use case, add [skip-golden] to its name. This special string tag can be customized as needed.
• You can pass your app's theme to WidgetbookGoldenTestsProperties to make sure the cases are run with proper theming.
• You can setup a default locale inside the properties.

Contributing

Pull requests are welcome! For major changes, please open an issue first to discuss what you would like to change.

License

MIT