widget-test

Flutter Template Widget Tests

Use this skill when adding focused widget coverage for a screen, shared component, or UI state in this Flutter template.

Read First

• AGENTS.md
• docs/PROJECT_OVERVIEW.md
• docs/PROJECT_GUIDELINES.md
• Nearby tests under test/
• The widget, provider, and state files being covered

When To Add Widget Tests

• A shared widget gets new behavior, styling states, callbacks, or accessibility expectations.
• A feature screen adds meaningful loading, empty, error, or success states.
• A bug fix changes what the user sees or can tap.
• A regression would be cheap to catch with a pumpWidget test.

Do not add broad snapshot-style tests that only restate the widget tree. Prefer behavior and contract checks: visible text, enabled/disabled states, callbacks, navigation events, empty/error rendering, and provider-driven state transitions.

Test Location

• Shared UI: test/common/<widget_name>_test.dart
• Feature UI: test/features/<feature>/<feature>_page_content_test.dart
• Provider-heavy feature states may also need focused provider tests; keep them near the feature test folder unless the repo already has a stronger local pattern.

Harness Pattern

Call Configuration.setup(flavor: Flavor.develop) at the top of main() before any test runs — existing tests in test/common/ do this and widgets that read configuration fail without it.

Build the smallest wrapper that gives the widget the dependencies it expects:

Widget buildSubject({
  List<Override> overrides = const [],
}) {
  return ProviderScope(
    overrides: overrides,
    child: MaterialApp(
      localizationsDelegates: AppLocalizations.localizationsDelegates,
      supportedLocales: AppLocalizations.supportedLocales,
      theme: AppTheme.getThemeData(brightness: Brightness.light),
      home: const Scaffold(
        body: SubjectWidget(),
      ),
    ),
  );
}

Adapt imports to the current code. If the existing nearby tests use patrolWidgetTest, pumpWidgetAndSettle, or another helper, reuse that style instead of creating a parallel harness.