Index of every page on this site: llms.txt
All skills
flutter avatar

/flutter-add-widget-test

@ff6d472 official
by flutterflutter/agent-plugins3.2k stars
193
Run it yourself

Implement a component-level test using `WidgetTester` to verify UI rendering and user interactions (tapping, scrolling, entering text). Use when validating that a specific widget displays correct data and responds to events as expected.

Use this Skill: https://skilld.dev/gh/flutter/agent-plugins/flutter-add-widget-test

Nothing lands on disk. Nothing to clean up.

Fork this Skill

Edit a local copy. It keeps the author and licence.

SKILL.md

≈65 tokens for metadata: the name and description. ≈1.5k when used: this file.

Description uses 3.3% of example budget

Before choosing a Skill, your Agent reads its name and description. All available Skills share that space.

  • A shorter description leaves more room for other Skills. This entry exceeds our 1% size suggestion.

In our Claude Code example, all Skill names and descriptions share 8,000 characters. This Skill uses ≈262 characters, or 3.3%.

The 1% threshold is a size suggestion. Longer descriptions can still fit.

Your model, settings, and other Skills decide how much text your Agent can read.

Example settings and source

The example uses a 200k-token context and default Claude Code settings. The count includes the name, description, separators, and when_to_use when present. Codex also counts local file paths.

Skit's source and limits: Codex 0.160.1, Claude Code 2.1.292.

Writing Flutter Widget Tests

Contents

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.

Interaction & State Management

Apply the following conditional logic based on the type of interaction or state change being tested:

  • If testing static rendering: Call await tester.pumpWidget() once, then immediately run expect() assertions.
  • If testing standard state changes (e.g., button taps):
    1. Call await tester.tap(finder).
    2. Call await tester.pump() to trigger a single frame rebuild.
  • If testing animations, transitions, or asynchronous UI updates:
    1. Trigger the action (e.g., await tester.drag(finder, Offset(500, 0))).
    2. Call await tester.pumpAndSettle() to repeatedly pump frames until no more frames are scheduled (animation completes).
  • If testing text input: Call await tester.enterText(textFieldFinder, 'Input string').
  • If testing items in a dynamic or long list: Call await tester.scrollUntilVisible(itemFinder, 500.0, scrollable: listFinder) to ensure the target widget is rendered before interacting with it.

Examples

High-Fidelity Widget Test Implementation

Target Widget (lib/todo_list.dart):

import 'package:flutter/material.dart';

class TodoList extends StatefulWidget {
  const TodoList({super.key});

  @override
  State<TodoList> createState() => _TodoListState();
}

class _TodoListState extends State<TodoList> {
  final todos = <String>[];
  final controller = TextEditingController();

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      home: Scaffold(
        body: Column(
          children: [
            TextField(controller: controller),
            Expanded(
              child: ListView.builder(
                itemCount: todos.length,
                itemBuilder: (context, index) {
                  final todo = todos[index];
                  return Dismissible(
                    key: Key('$todo$index'),
                    onDismissed: (_) => setState(() => todos.removeAt(index)),
                    child: ListTile(title: Text(todo)),
                  );
                },
              ),
            ),
          ],
        ),
        floatingActionButton: FloatingActionButton(
          onPressed: () {
            setState(() {
              todos.add(controller.text);
              controller.clear();
            });
          },
          child: const Icon(Icons.add),
        ),
      ),
    );
  }
}

Test Implementation (test/todo_list_test.dart):

import 'package:flutter/material.dart';
import 'package:flutter_test/flutter_test.dart';
import 'package:my_app/todo_list.dart';

void main() {
  testWidgets('Add and remove a todo item', (WidgetTester tester) async {
    // 1. Build the widget
    await tester.pumpWidget(const TodoList());

    // 2. Verify initial state
    expect(find.byType(ListTile), findsNothing);

    // 3. Enter text into the TextField
    await tester.enterText(find.byType(TextField), 'Buy groceries');

    // 4. Tap the add button
    await tester.tap(find.byType(FloatingActionButton));

    // 5. Rebuild the widget to reflect the new state
    await tester.pump();

    // 6. Verify the item was added
    expect(find.text('Buy groceries'), findsOneWidget);

    // 7. Swipe the item to dismiss it
    await tester.drag(find.byType(Dismissible), const Offset(500, 0));

    // 8. Build the widget until the dismiss animation ends
    await tester.pumpAndSettle();

    // 9. Verify the item was removed
    expect(find.text('Buy groceries'), findsNothing);
  });
}

Source: SKILL.md on GitHub

No rule matched.

skilld matched fixed text patterns in SKILL.md and file names. Patterns miss obfuscated code.

skilld run checks every file with the same patterns. It asks for approval before it loads a Skill with a behavior marked Needs approval.

No alerts4mo3 checks · Risk SAFE
  • Gen Agent Trust Hub4mo

    The skill provides instructions and examples for writing Flutter widget tests. It does not contain any malicious patterns, dangerous commands, or external dependencies from untrusted sources.

  • Socket4mo

    No alerts

  • Snyk4mo

    Risk: LOW · No issues

Signed by skilld at ff6d472. This ties the file your Agent reads to that commit on GitHub. It does not review the instructions.

Last checked against GitHub yesterday.

Activeupdated 7 months ago
Other metadata
metadata
{
  "model": "models/gemini-3.1-pro-preview",
  "last_modified": "Tue, 21 Apr 2026 21:15:41 GMT"
}
  • Testing
  • flutter
  • widget-testing
  • flutter-test
  • ui-testing
  • dart
  • interaction-testing
  • state-management

README badge

README badge for flutter/agent-plugins/flutter-add-widget-test

Writes component-level tests for Flutter widgets using WidgetTester to verify UI rendering, user interactions like taps and text input, and state changes. Covers test setup with flutter_test, Finder and Matcher usage, and workflows for static renders, animations, and list scrolling.

Generated from the current SKILL.md.

What do I need to set up to write Flutter widget tests?
Add `flutter_test` to dev_dependencies in pubspec.yaml, place test files in the `test/` directory, and name them with a `_test.dart` suffix (e.g., `widget_test.dart`).
How do I simulate user interactions like button taps or text input?
Use `await tester.tap(finder)` for button taps, `await tester.enterText(finder, 'text')` for text input, and `await tester.drag(finder, Offset(...))` for gestures. Call `await tester.pump()` afterward to rebuild the widget tree.
When should I use `pumpAndSettle()` instead of `pump()`?
Use `pumpAndSettle()` when testing animations, transitions, or asynchronous UI updates—it repeatedly pumps frames until no more are scheduled. Use `pump()` for simple state changes like button taps.
How do I find and verify widgets in a test?
Use `Finder` objects like `find.text('label')`, `find.byType(Widget)`, or `find.byKey(Key('id'))` to locate widgets, then verify with matchers like `expect(finder, findsOneWidget)` or `expect(finder, findsNothing)`.

Generated from the current SKILL.md. These answers refresh after source changes.