Tour

test/main_shell_test.dart

@@ -1,7 +1,9 @@
 import 'package:flutter/material.dart';
 import 'package:flutter_test/flutter_test.dart';
 import 'package:provider/provider.dart';
+import 'package:shared_preferences/shared_preferences.dart';
 
+import 'package:fuel_tax_tracker/screens/data_settings_screen.dart';
 import 'package:fuel_tax_tracker/screens/main_shell.dart';
 import 'package:fuel_tax_tracker/services/app_state.dart';
 
@@ -102,4 +104,148 @@ void main() {
     final selectedLabel = tester.widget<Text>(find.text('Last 3 Months'));
     expect((selectedLabel.style?.fontWeight), FontWeight.w800, reason: 'still the active range');
   });
+
+  group('first-launch onboarding tour', () {
+    setUp(() {
+      SharedPreferences.setMockInitialValues({});
+    });
+
+    Future<AppState> pumpShellWithFreshTour(WidgetTester tester) async {
+      // AppState.hasSeenOnboardingTour defaults to true precisely so that
+      // ad-hoc AppState() construction elsewhere (every other test in this
+      // file included) doesn't trigger the tour — these tests explicitly
+      // flip it to false to reproduce a real fresh install's state.
+      final appState = AppState()
+        ..isLoading = false
+        ..hasSeenOnboardingTour = false;
+
+      await tester.pumpWidget(
+        ChangeNotifierProvider.value(
+          value: appState,
+          child: const MaterialApp(home: MainShell()),
+        ),
+      );
+      await tester.pumpAndSettle();
+      return appState;
+    }
+
+    testWidgets('shows step 1 (Receipts) automatically on first launch', (tester) async {
+      await pumpShellWithFreshTour(tester);
+
+      expect(find.text('Add Receipts Here'), findsOneWidget);
+      expect(find.text('Step 1 of 4'), findsOneWidget);
+      expect(find.widgetWithText(AppBar, 'Receipts'), findsOneWidget);
+    });
+
+    testWidgets('does not show the tour once hasSeenOnboardingTour is true', (tester) async {
+      final appState = AppState()
+        ..isLoading = false
+        ..hasSeenOnboardingTour = true;
+
+      await tester.pumpWidget(
+        ChangeNotifierProvider.value(
+          value: appState,
+          child: const MaterialApp(home: MainShell()),
+        ),
+      );
+      await tester.pumpAndSettle();
+
+      expect(find.text('Add Receipts Here'), findsNothing);
+    });
+
+    testWidgets('tapping the dimmed barrier does not dismiss the tour or reach the highlighted button',
+        (tester) async {
+      await pumpShellWithFreshTour(tester);
+
+      // Top-left corner, away from the card and from the highlighted "+"
+      // (which sits top-right in the AppBar).
+      await tester.tapAt(const Offset(10, 10));
+      await tester.pumpAndSettle();
+
+      expect(find.text('Add Receipts Here'), findsOneWidget, reason: 'tour still showing');
+      expect(find.widgetWithText(AppBar, 'Add Vehicle'), findsNothing,
+          reason: "the receipt '+' — which opens vehicle creation when there are no "
+              "vehicles yet — was not actually reached");
+    });
+
+    testWidgets('Next advances through all four steps, switching tabs and pushing Settings > Data',
+        (tester) async {
+      await pumpShellWithFreshTour(tester);
+
+      expect(find.text('Add Receipts Here'), findsOneWidget);
+      expect(find.widgetWithText(AppBar, 'Receipts'), findsOneWidget);
+
+      await tester.tap(find.widgetWithText(FilledButton, 'Next'));
+      await tester.pumpAndSettle();
+      expect(find.text('Add Vehicles Here'), findsOneWidget);
+      expect(find.text('Step 2 of 4'), findsOneWidget);
+      expect(find.widgetWithText(AppBar, 'Vehicles'), findsOneWidget);
+
+      await tester.tap(find.widgetWithText(FilledButton, 'Next'));
+      await tester.pumpAndSettle();
+      expect(find.text('Choose a Report Date Range'), findsOneWidget);
+      expect(find.widgetWithText(AppBar, 'Fuel Report'), findsOneWidget);
+
+      await tester.tap(find.widgetWithText(FilledButton, 'Next'));
+      await tester.pumpAndSettle();
+      expect(find.text('Back Up to the Cloud'), findsOneWidget);
+      expect(find.text('Step 4 of 4'), findsOneWidget);
+      expect(find.byType(DataSettingsScreen), findsOneWidget, reason: 'tour pushed Settings > Data');
+      expect(find.text('Cloud Storage'), findsOneWidget);
+      expect(find.widgetWithText(FilledButton, 'Got It'), findsOneWidget,
+          reason: 'last step reads "Got It", not "Next"');
+    });
+
+    testWidgets(
+        'finishing on the last step pops the tour-pushed Data screen and marks the tour seen',
+        (tester) async {
+      final appState = await pumpShellWithFreshTour(tester);
+
+      for (var i = 0; i < 3; i++) {
+        await tester.tap(find.widgetWithText(FilledButton, 'Next'));
+        await tester.pumpAndSettle();
+      }
+      expect(find.byType(DataSettingsScreen), findsOneWidget);
+
+      await tester.tap(find.widgetWithText(FilledButton, 'Got It'));
+      await tester.pumpAndSettle();
+
+      expect(find.byType(DataSettingsScreen), findsNothing, reason: 'tour-pushed screen popped');
+      expect(find.text('Back Up to the Cloud'), findsNothing, reason: 'overlay gone');
+      expect(appState.hasSeenOnboardingTour, isTrue);
+
+      final prefs = await SharedPreferences.getInstance();
+      expect(prefs.getBool('has_seen_onboarding_tour'), isTrue,
+          reason: 'persisted so the tour never shows again on this device');
+    });
+
+    testWidgets('Skip Tour on the very first step ends the tour immediately and marks it seen',
+        (tester) async {
+      final appState = await pumpShellWithFreshTour(tester);
+
+      await tester.tap(find.widgetWithText(TextButton, 'Skip Tour'));
+      await tester.pumpAndSettle();
+
+      expect(find.text('Add Receipts Here'), findsNothing);
+      expect(appState.hasSeenOnboardingTour, isTrue);
+      expect(find.widgetWithText(AppBar, 'Receipts'), findsOneWidget,
+          reason: 'stayed on the tab it started on');
+    });
+
+    testWidgets('Skip Tour from the last step still pops the tour-pushed Data screen',
+        (tester) async {
+      await pumpShellWithFreshTour(tester);
+
+      for (var i = 0; i < 3; i++) {
+        await tester.tap(find.widgetWithText(FilledButton, 'Next'));
+        await tester.pumpAndSettle();
+      }
+      expect(find.byType(DataSettingsScreen), findsOneWidget);
+
+      await tester.tap(find.widgetWithText(TextButton, 'Skip Tour'));
+      await tester.pumpAndSettle();
+
+      expect(find.byType(DataSettingsScreen), findsNothing);
+    });
+  });
 }