widgetbook_golden_test 0.4.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. It leverages the generated directory files from widgetbook_generator to discover use cases and render them into golden images for visual regression testing.

It is built upon widgetbook_golden_test_core, which provides the underlying engine for rendering and mocking dependencies.

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

1. Generate your Widgetbook directories using widgetbook_generator:

dart run build_runner build -d

2. Import the directories file generated.
3. Call runWidgetbookGoldenTests inside the main function of a test file.

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

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

4. Generate the golden files by running:

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

Note: Replace <path-to-test-file> with the actual path to your test file. If omitted, Flutter will run all tests in the project.

Features

• Automatic Discovery: All Widgetbook use cases are automatically discovered and tested.
• Network Image Mocking: Handles network images for reliable tests. You can simulate loading and error states using WidgetbookGoldenTestsProperties.defaultErrorImageUrl and WidgetbookGoldenTestsProperties.defaultLoadingImageUrl.
• Knob Support: Supports Widgetbook knobs by mocking the internal state.
• Customization: Customize properties at the group level via WidgetbookGoldenTestsProperties or per use-case using WidgetbookGoldenTestBuilder.
• Play Actions: Use GoldenPlayAction within WidgetbookGoldenTestBuilder to capture snapshots after interactions (e.g., scrolling, tapping).
• Widgetbook Addons: Apply and merge Widgetbook addons to test different themes, locales, and text scales.

How It Works

1. Discovery: Use cases are defined and auto-generated in the directories file by widgetbook_generator.
2. Traversal: The runWidgetbookGoldenTests function traverses the provided Widgetbook nodes.
3. Mocking: It sets up a mocked environment using goldenTestZoneRunner, which includes a mocked HttpClient for network images.
4. Execution: Each use case is pumped into a MockedWidgetbookCase which provides the necessary WidgetbookScope and theme context.
5. Verification: The WidgetbookGoldenFlutterTestRenderer uses flutter_test's expectLater and matchesGoldenFile to perform the visual comparison.

Customization

WidgetbookGoldenTestsProperties

Use this to configure global settings for your golden tests:

• addons: Apply global addons.
• theme: Set a default theme.
• onTestError: Handle or ignore specific errors.
• networkImageResolver: Provide custom logic for loading network images.

Warning

If you call runWidgetbookGoldenTests multiple times within the same main function using different special URLs (error/loading), you may encounter conflicts because HttpOverrides is global. It is recommended to use separate test files (with separate main functions) in such cases to avoid potential hang-ups.

WidgetbookGoldenTestBuilder

Wrap your use case builder with this to customize individual tests:

• skip: Skip specific tests.
• addons: Override or merge addons for a specific case.
• goldenActions: Define a sequence of actions and snapshot points.

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