widgetbook_golden_test 0.1.0

Utility for running golden tests on Widgetbook use cases.

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