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 the main function of a test file.

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

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

To generate the golden files, run the following command:

flutter test <path-to-test-file> --update-goldens

Note: Replace <path-to-test-file> with the path to your test file where you are invoking runWidgetbookGoldenTests. The path to the test file is optional but recommended, because it will run all your other tests without it.

To update your golden files, run the same command again.

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 specific values as the image URLs. These are constants declared in WidgetbookGoldenTestsProperties as WidgetbookGoldenTestsProperties.defaultErrorImageUrl and WidgetbookGoldenTestsProperties.defaultLoadingImageUrl respectively by default. These will trigger the errorBuilder in your Image.network widget, or an indefinite loadingBuilder. You can pass a networkImageResolver to customize the returned image.
• 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 WidgetbookGoldenTestsProperties.defaultSkipTag 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 if necessary.

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.

Credits #

• This library’s image network mocking implementation is based on mocktail_image_network by Felix Angelov.

Contributing #

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

License #

MIT