widgetbook_golden_test #

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: This has been mainly tested with auto-generated directories. Manually editing or creating *.directories.g.dart should work as well but is not intended.

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.
• 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.
• Custom Properties: Customize properties with a custom WidgetbookGoldenTestsProperties (see more below).
• Play functions: Use WidgetbookGoldenTestBuilder at the top level of your use case to provide a list of goldenActions. A golden snapshot will be taken after each goldenAction. This allows you to capture snapshots after certain user interactions like scrolling or tapping a button menu.
• Apply Widgetbook Addons: Use the Widgetbook Addons to further customize your generated snapshots. Note: The order in which addons are declared affects the result.

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 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.

• Modify skipTag to change the default tag used to skip golden test execution.
• You can pass your app's theme to WidgetbookGoldenTestsProperties to make sure the cases are run with proper theming.
• Use the addons property to apply Widgetbook Addons. With these addons, you can change the text scale, add grid guidelines, and more.
• Use a onTestError to handle modify the default behavior when a test fails. This can be used to ignore certain errors or add additional functionality like logging.
• You can setup a default locale inside the properties.
• The special URLs for error and loading network images can be changed to custom ones.

Note: If you want to call runWidgetbookGoldenTests twice with different special URLs in each call, do it on separate main functions. The HttpOverrides may conflict on each other and cause hang-ups if they are ran in the same main function. If they share the same URLs, then they can be called in the same main function without issues.

Contributing #

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

License #

MIT