Verification & Widget Testing Reference
Command-line verification gates, WidgetTester vs. React Testing Library idioms, and ProviderScope dependency overrides.
1. Mandatory Verification Gates
Every companion app in ./tutorial/apps/<NNNN-slug>/ must pass two automated gates with zero warnings and 100% passing tests before a lesson is complete:
flutter analyze
flutter testUnlike browser-based E2E runners (Playwright/Cypress) or JSDOM shims, flutter test executes the real Flutter layout and rendering pipeline against a deterministic fake clock inside the Dart VM—typically completing in under two seconds.
When a lesson introduces or modifies @freezed, @JsonSerializable, or @riverpod annotations (starting in Lesson 0002), regenerate the companion *.freezed.dart and *.g.dart part files via:
dart run build_runner build --delete-conflicting-outputs2. React Testing Library vs. flutter_test
Table: Translating React Testing Library + Vitest to package:flutter_test
| Testing Action | React Testing Library (@testing-library/react) |
Flutter Widget Test (package:flutter_test) |
|---|---|---|
| Define a UI test | test('renders workbench', async () => { ... }) |
testWidgets('renders workbench', (WidgetTester tester) async { ... }) |
| Mount component tree | render(<Provider><PartsTrackerApp /></Provider>) |
await tester.pumpWidget(const ProviderScope(child: PartsTrackerApp())) |
| Wait for async state / animations | await waitFor(() => ...) |
await tester.pumpAndSettle() |
| Find by visible text | screen.getByText('Electronics Parts Tracker') |
find.text('Electronics Parts Tracker') |
| Find by substring | screen.getByText(/RC0603/i) |
find.textContaining('RC0603') |
Find by data-testid |
screen.getByTestId('part_lcsc_input') |
find.byKey(const Key('part_lcsc_input')) |
| Assert element is present once | expect(el).toBeInTheDocument() |
expect(finder, findsOneWidget) |
| Assert element is absent | expect(screen.queryByText('...')).toBeNull() |
expect(finder, findsNothing) |
| Click / tap an element | await userEvent.click(el) |
await tester.tap(finder); await tester.pumpAndSettle(); |
| Type into a text input | await userEvent.type(input, '0.1uF') |
await tester.enterText(finder, '0.1uF'); await tester.pumpAndSettle(); |
3. Dependency Injection with ProviderScope Overrides
In React, testing components with mock stores or fake API clients requires wrapping the tree in custom <Context.Provider value={mock}> layers or module-mocking (vi.mock(...)). In Riverpod, every dependency is a provider that can be cleanly overridden per test without global module mocks:
await tester.pumpWidget(
ProviderScope(
overrides: [
catalogPersistenceProvider.overrideWithValue(persistence),
lcscClientProvider.overrideWithValue(fakeLcsc),
],
child: const PartsTrackerApp(),
),
);
await tester.pumpAndSettle();