Widget tests

What a widget test checks

Unit tests check logic; widget tests check that the UI behaves: tapping + increases the number, an invalid form shows an error, an empty list shows a friendly message. They run in a simulated Flutter environment on your computer, so they are much faster than running the app, yet they exercise real widgets, layout and gestures.

import 'package:flutter/material.dart';
import 'package:flutter_test/flutter_test.dart';
import 'package:chai_shop/counter_page.dart';

void main() {
  testWidgets('tapping + increases the cup count', (WidgetTester tester) async {
    await tester.pumpWidget(const MaterialApp(home: CounterPage()));

    expect(find.text('Cups sold today: 0'), findsOneWidget);

    await tester.tap(find.byIcon(Icons.add));
    await tester.pump();                                 // rebuild after setState

    expect(find.text('Cups sold today: 1'), findsOneWidget);
    expect(find.text('Cups sold today: 0'), findsNothing);
  });
}

Finders

Keys make tests robust: text may be translated or reworded, but a Key('mobileField') stays the same. Add keys to important inputs and buttons you test often.

Matchers for finders describe how many widgets should match: findsOneWidget, findsNothing, findsWidgets (one or more) and findsNWidgets(3).

pump versus pumpAndSettle

After an interaction, the widget tree does not rebuild by itself in tests. pump() advances one frame (enough after a simple setState). pumpAndSettle() keeps pumping until there are no more scheduled frames, which is what you want after animations or page transitions. Infinite animations (like a spinning progress indicator) never settle, so pumpAndSettle would time out; use pump(const Duration(...)) there.

Widget tests should not call real APIs either. Give the screen a fake repository, or override its provider, so the test controls exactly which data appears and runs the same way every time.

Testing a form

testWidgets('shows an error for a short mobile number', (tester) async {
  await tester.pumpWidget(const MaterialApp(home: Scaffold(body: SignupForm())));

  await tester.enterText(find.byKey(const Key('mobileField')), '98765');
  await tester.tap(find.text('Create account'));
  await tester.pump();

  expect(find.text('Enter 10 digits'), findsOneWidget);
});

Providing state in tests

If the widget reads a Provider, Riverpod provider or Bloc, wrap it the same way in the test, usually with a fake model or repository: ChangeNotifierProvider(create: (_) => FakeCart(), child: MaterialApp(home: CartPage())). With Riverpod, ProviderScope(overrides: [...]) replaces providers with test versions.

Common mistakes

• Forgetting await before tester.tap or pump: the test checks before the UI updates.
• Forgetting pump() after an interaction, then wondering why the text did not change.
• Using pumpAndSettle with an endless animation: timeout.
• Not wrapping in MaterialApp: errors about missing MediaQuery, Directionality or Material ancestors.