flutter-add-widget-test

Writing Flutter Widget Tests

Contents

• Setup & Configuration
• Core Components
• Workflow: Implementing a Widget Test
• Interaction & State Management
• Examples

Setup & Configuration

Ensure the testing environment is properly configured before authoring widget tests.

1. Add the flutter_test dependency to the dev_dependencies section of pubspec.yaml.
2. Place all test files in the test/ directory at the root of the project.
3. Suffix all test file names with _test.dart (e.g., widget_test.dart).

Core Components

Utilize the following flutter_test components to interact with and validate the widget tree:

• WidgetTester: The primary interface for building and interacting with widgets in the test environment. Provided automatically by the testWidgets() function.
• Finder: Locates widgets in the test environment (e.g., find.text('Submit'), find.byType(TextField), find.byKey(Key('submit_btn'))).
• Matcher: Verifies the presence or state of widgets located by a Finder (e.g., findsOneWidget, findsNothing, findsNWidgets(2), matchesGoldenFile).

Workflow: Implementing a Widget Test

Copy the following checklist to track progress when implementing a new widget test.

Task Progress

• Step 1: Define the test. Use testWidgets('description', (WidgetTester tester) async { ... }).
• Step 2: Build the widget. Call await tester.pumpWidget(MyWidget()) to render the UI. Wrap the widget in a MaterialApp or Directionality widget if it requires inherited directional or theme data.
• Step 3: Locate elements. Instantiate Finder objects for the target widgets.
• Step 4: Verify initial state. Use expect(finder, matcher) to validate the initial render.
• Step 5: Simulate interactions. Execute gestures or inputs (e.g., await tester.tap(buttonFinder)).
• Step 6: Rebuild the tree. Call await tester.pump() or await tester.pumpAndSettle() to process state changes.
• Step 7: Verify updated state. Use expect() to validate the UI after the interaction.
• Step 8: Run and validate. Execute flutter test test/your_test_file_test.dart.
• Step 9: Feedback Loop. Review test output -> identify failing matchers -> adjust widget logic or test assertions -> re-run until passing.