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](LICENSE)