Skip to content

Commit fa66f29

Browse files
richardthe3rdrichardthe3rd
authored
Merge pull request #105 from richardthe3rd/copilot/introduce-go-routes
Add go_router to improve web app experience
2 parents 5ef59eb + 331df93 commit fa66f29

14 files changed

Lines changed: 502 additions & 107 deletions

‎docs/TESTING_FLUTTER_WEB.md‎

Lines changed: 170 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,170 @@
1+
# Testing Flutter Web Apps with Playwright
2+
3+
## The Challenge
4+
5+
Flutter web apps render their UI to a canvas element, which makes traditional DOM-based testing approaches ineffective. You cannot:
6+
- ❌ Use CSS selectors to find buttons, text, or other UI elements
7+
- ❌ Directly interact with Flutter widgets via Playwright
8+
- ❌ Inspect the visual content rendered on the canvas
9+
10+
## The Solution: Accessibility-Based Testing
11+
12+
Flutter creates **DOM elements for accessibility** through the `Semantics` widget. These elements are specifically designed for screen readers but also serve as a reliable testing interface.
13+
14+
### How It Works
15+
16+
1. **Flutter Semantics Widget** → Creates ARIA labels in the DOM
17+
2. **Screen readers** → Read these ARIA labels
18+
3. **Playwright tests** → Can also read these ARIA labels
19+
20+
### Example
21+
22+
**Flutter Code:**
23+
```dart
24+
Semantics(
25+
label: 'Drinks tab, browse all festival drinks',
26+
child: const Icon(Icons.local_drink_outlined),
27+
)
28+
```
29+
30+
**Generated DOM (simplified):**
31+
```html
32+
<flt-semantics aria-label="Drinks tab, browse all festival drinks">
33+
<!-- Flutter renders icon to canvas -->
34+
</flt-semantics>
35+
```
36+
37+
**Playwright Test:**
38+
```typescript
39+
const drinksTabLabel = page.locator('[aria-label*="Drinks tab"]');
40+
await expect(drinksTabLabel.first()).toBeAttached();
41+
```
42+
43+
## What You CAN Test
44+
45+
✅ **Page loads successfully** - Check for Flutter embedder elements
46+
✅ **URL routing** - Verify URLs change correctly during navigation
47+
✅ **Browser history** - Test back/forward button functionality
48+
✅ **Console errors** - Monitor for JavaScript errors
49+
✅ **Network requests** - Verify API calls are made
50+
✅ **Screen verification** - Use ARIA labels to confirm which screen is displayed
51+
✅ **Accessibility** - Ensure proper ARIA labels exist for screen readers
52+
53+
## What You CANNOT Test
54+
55+
❌ **Visual appearance** - Colors, fonts, layout (use visual regression testing or Flutter integration tests)
56+
❌ **Canvas interactions** - Clicking specific points on the canvas
57+
❌ **Gesture detection** - Swipes, drags, pinch-to-zoom
58+
❌ **Text content** - Reading text rendered on canvas (unless it has ARIA labels)
59+
60+
## Best Practices
61+
62+
### 1. Add Semantics to Key UI Elements
63+
64+
Always wrap important UI elements with `Semantics` widgets:
65+
66+
```dart
67+
// Good
68+
Semantics(
69+
label: 'View source code on GitHub',
70+
hint: 'Double tap to open GitHub repository in browser',
71+
button: true,
72+
child: IconButton(
73+
icon: Icon(Icons.code),
74+
onPressed: _openGitHub,
75+
),
76+
)
77+
78+
// Bad - no Semantics, cannot be tested or used by screen readers
79+
IconButton(
80+
icon: Icon(Icons.code),
81+
onPressed: _openGitHub,
82+
)
83+
```
84+
85+
### 2. Use Descriptive ARIA Labels
86+
87+
Make labels unique enough to identify specific screens:
88+
89+
```dart
90+
// Good - unique to About screen
91+
Semantics(
92+
label: 'View source code on GitHub',
93+
// ...
94+
)
95+
96+
// Bad - too generic, could be on any screen
97+
Semantics(
98+
label: 'Button',
99+
// ...
100+
)
101+
```
102+
103+
### 3. Test What Matters for Routing
104+
105+
For go_router navigation tests, focus on:
106+
107+
```typescript
108+
test('should navigate to about screen', async ({ page }) => {
109+
await page.goto('http://localhost:8080/about');
110+
await waitForPageReady(page);
111+
112+
// 1. Verify URL changed
113+
expect(page.url()).toBe('http://localhost:8080/about');
114+
115+
// 2. Verify correct screen via unique ARIA label
116+
const aboutLabel = page.locator('[aria-label*="View source code on GitHub"]');
117+
await expect(aboutLabel.first()).toBeAttached();
118+
119+
// 3. Verify no console errors
120+
// (setup error listeners before navigation)
121+
});
122+
```
123+
124+
### 4. Keep Tests Focused
125+
126+
Don't try to test complex user interactions in E2E tests. Use Flutter integration tests for those:
127+
128+
```dart
129+
// This belongs in Flutter integration tests, not Playwright:
130+
testWidgets('tapping favorite button adds drink to favorites', (tester) async {
131+
await tester.pumpWidget(MyApp());
132+
await tester.tap(find.byIcon(Icons.favorite_border));
133+
await tester.pump();
134+
expect(find.byIcon(Icons.favorite), findsOneWidget);
135+
});
136+
```
137+
138+
## Example Test Suite Structure
139+
140+
```
141+
test-e2e/
142+
├── app.spec.ts # Basic app loading tests
143+
├── routing.spec.ts # Navigation/routing tests (uses ARIA labels)
144+
└── network.spec.ts # API request tests (optional)
145+
```
146+
147+
## Benefits of This Approach
148+
149+
1. **Accessibility First** - Tests ensure the app is usable by screen readers
150+
2. **Stable Selectors** - ARIA labels are less likely to change than internal Flutter DOM structure
151+
3. **Meaningful Tests** - Verifies actual user-facing behavior (navigation, errors)
152+
4. **Dual Purpose** - Same Semantics widgets benefit both testing and accessibility
153+
5. **Fast Feedback** - Catch routing issues in CI before manual testing
154+
155+
## References
156+
157+
- [Flutter Semantics Documentation](https://api.flutter.dev/flutter/widgets/Semantics-class.html)
158+
- [Playwright Accessibility Testing](https://playwright.dev/docs/accessibility-testing)
159+
- [Flutter Web Rendering](https://docs.flutter.dev/platform-integration/web/renderers)
160+
161+
## Current Usage in This App
162+
163+
This app has **24 Semantics widgets** across various screens:
164+
- Navigation tabs (Drinks, Favorites)
165+
- About screen buttons (GitHub, Issues, Licenses, Theme toggle)
166+
- Search field
167+
- Filter chips
168+
- Info buttons
169+
170+
These provide both accessibility and testability.

‎lib/main.dart‎

Lines changed: 36 additions & 27 deletions
Original file line numberDiff line numberDiff line change
@@ -2,9 +2,10 @@ import 'dart:ui';
22
import 'package:flutter/material.dart';
33
import 'package:firebase_core/firebase_core.dart';
44
import 'package:firebase_crashlytics/firebase_crashlytics.dart';
5+
import 'package:go_router/go_router.dart';
56
import 'package:provider/provider.dart';
67
import 'providers/providers.dart';
7-
import 'screens/screens.dart';
8+
import 'router.dart';
89
import 'services/services.dart';
910
import 'widgets/widgets.dart';
1011
import 'firebase_options.dart';
@@ -46,7 +47,7 @@ class BeerFestivalApp extends StatelessWidget {
4647
child: Builder(
4748
builder: (context) {
4849
final themeMode = context.watch<BeerProvider>().themeMode;
49-
return MaterialApp(
50+
return MaterialApp.router(
5051
title: 'Cambridge Beer Festival',
5152
debugShowCheckedModeBanner: false,
5253
theme: ThemeData(
@@ -64,7 +65,7 @@ class BeerFestivalApp extends StatelessWidget {
6465
useMaterial3: true,
6566
),
6667
themeMode: themeMode,
67-
home: const BeerFestivalHome(),
68+
routerConfig: appRouter,
6869
);
6970
},
7071
),
@@ -73,16 +74,43 @@ class BeerFestivalApp extends StatelessWidget {
7374
}
7475

7576
class BeerFestivalHome extends StatefulWidget {
76-
const BeerFestivalHome({super.key});
77+
final Widget child;
78+
79+
const BeerFestivalHome({super.key, required this.child});
7780

7881
@override
7982
State<BeerFestivalHome> createState() => _BeerFestivalHomeState();
8083
}
8184

8285
class _BeerFestivalHomeState extends State<BeerFestivalHome> with WidgetsBindingObserver {
83-
int _currentIndex = 0;
8486
bool _initialized = false;
8587

88+
int get _currentIndex {
89+
// Try to get the current location from GoRouter
90+
try {
91+
final location = GoRouterState.of(context).uri.toString();
92+
if (location == '/favorites') return 1;
93+
return 0;
94+
} catch (e) {
95+
// If GoRouter is not available (e.g., in tests), default to 0
96+
return 0;
97+
}
98+
}
99+
100+
void _onDestinationSelected(int index) {
101+
// Try to use GoRouter navigation
102+
try {
103+
if (index == 0) {
104+
context.go('/');
105+
} else if (index == 1) {
106+
context.go('/favorites');
107+
}
108+
} catch (e) {
109+
// If GoRouter is not available, this is a no-op
110+
// (tests that don't use GoRouter won't navigate)
111+
}
112+
}
113+
86114
@override
87115
void initState() {
88116
super.initState();
@@ -120,26 +148,12 @@ class _BeerFestivalHomeState extends State<BeerFestivalHome> with WidgetsBinding
120148
@override
121149
Widget build(BuildContext context) {
122150
return Scaffold(
123-
// IndexedStack keeps all children (both screens) in memory simultaneously.
124-
// Memory trade-off: Higher memory usage, but preserves state when switching tabs
125-
// (scroll position, filters, search queries, expanded sections, etc.).
126-
// This provides better UX than rebuilding screens on each tab switch.
127-
body: IndexedStack(
128-
index: _currentIndex,
129-
children: const [
130-
DrinksScreen(),
131-
FavoritesScreen(),
132-
],
133-
),
151+
body: widget.child,
134152
bottomNavigationBar: NavigationBar(
135153
height: 60,
136154
labelBehavior: NavigationDestinationLabelBehavior.alwaysHide,
137155
selectedIndex: _currentIndex,
138-
onDestinationSelected: (index) {
139-
setState(() {
140-
_currentIndex = index;
141-
});
142-
},
156+
onDestinationSelected: _onDestinationSelected,
143157
destinations: [
144158
NavigationDestination(
145159
icon: Semantics(
@@ -210,12 +224,7 @@ class FavoritesScreen extends StatelessWidget {
210224
return DrinkCard(
211225
key: ValueKey(drink.id),
212226
drink: drink,
213-
onTap: () => Navigator.push(
214-
context,
215-
MaterialPageRoute(
216-
builder: (context) => DrinkDetailScreen(drinkId: drink.id),
217-
),
218-
),
227+
onTap: () => context.go('/drink/${drink.id}'),
219228
onFavoriteTap: () => provider.toggleFavorite(drink),
220229
);
221230
},

‎lib/router.dart‎

Lines changed: 64 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,64 @@
1+
import 'package:go_router/go_router.dart';
2+
import 'package:provider/provider.dart';
3+
import 'providers/providers.dart';
4+
import 'screens/screens.dart';
5+
import 'main.dart';
6+
7+
/// Application router configuration using go_router for better web support
8+
final GoRouter appRouter = GoRouter(
9+
initialLocation: '/',
10+
debugLogDiagnostics: true,
11+
routes: [
12+
ShellRoute(
13+
builder: (context, state, child) => BeerFestivalHome(child: child),
14+
routes: [
15+
GoRoute(
16+
path: '/',
17+
pageBuilder: (context, state) => const NoTransitionPage(
18+
child: DrinksScreen(),
19+
),
20+
),
21+
GoRoute(
22+
path: '/favorites',
23+
pageBuilder: (context, state) => const NoTransitionPage(
24+
child: FavoritesScreen(),
25+
),
26+
),
27+
],
28+
),
29+
GoRoute(
30+
path: '/drink/:id',
31+
builder: (context, state) {
32+
final id = state.pathParameters['id']!;
33+
return DrinkDetailScreen(drinkId: id);
34+
},
35+
),
36+
GoRoute(
37+
path: '/brewery/:id',
38+
builder: (context, state) {
39+
final id = state.pathParameters['id']!;
40+
return BreweryScreen(breweryId: id);
41+
},
42+
),
43+
GoRoute(
44+
path: '/style/:name',
45+
builder: (context, state) {
46+
final name = state.pathParameters['name']!;
47+
final decodedName = Uri.decodeComponent(name);
48+
return StyleScreen(style: decodedName);
49+
},
50+
),
51+
GoRoute(
52+
path: '/about',
53+
builder: (context, state) => const AboutScreen(),
54+
),
55+
GoRoute(
56+
path: '/festival-info',
57+
builder: (context, state) {
58+
// Get festival from provider
59+
final festival = context.read<BeerProvider>().currentFestival;
60+
return FestivalInfoScreen(festival: festival);
61+
},
62+
),
63+
],
64+
);

‎lib/screens/brewery_screen.dart‎

Lines changed: 2 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,10 @@
11
import 'dart:async';
22
import 'package:flutter/material.dart';
3+
import 'package:go_router/go_router.dart';
34
import 'package:provider/provider.dart';
45
import '../providers/providers.dart';
56
import '../models/models.dart';
67
import '../widgets/widgets.dart';
7-
import 'drink_detail_screen.dart';
88

99
/// Screen showing a brewery and its drinks
1010
class BreweryScreen extends StatefulWidget {
@@ -76,12 +76,7 @@ class _BreweryScreenState extends State<BreweryScreen> {
7676
final drink = breweryDrinks[index];
7777
return DrinkCard(
7878
drink: drink,
79-
onTap: () => Navigator.push(
80-
context,
81-
MaterialPageRoute(
82-
builder: (context) => DrinkDetailScreen(drinkId: drink.id),
83-
),
84-
),
79+
onTap: () => context.go('/drink/${drink.id}'),
8580
onFavoriteTap: () => provider.toggleFavorite(drink),
8681
);
8782
},

0 commit comments

Comments
 (0)