ci: Bump version to 0.7.28 [skip ci]

notes-to-ai4.txt

@@ -13,6 +13,12 @@ RULES:
 
 
 
+latest refacter
+
+Refactor `RecipeSuggester.test.tsx` to use `renderWithProviders`.
+Create a new test file for `StatCard.tsx` to verify its props and rendering.
+
+
 
 
 UPC SCANNING !

package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "flyer-crawler",
-  "version": "0.7.7",
+  "version": "0.7.28",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "flyer-crawler",
-      "version": "0.7.7",
+      "version": "0.7.28",
       "dependencies": {
         "@bull-board/api": "^6.14.2",
         "@bull-board/express": "^6.14.2",

package.json

@@ -1,7 +1,7 @@
 {
   "name": "flyer-crawler",
   "private": true,
-  "version": "0.7.7",
+  "version": "0.7.28",
   "type": "module",
   "scripts": {
     "dev": "concurrently \"npm:start:dev\" \"vite\"",

sql/master_schema_rollup.sql

@@ -1248,7 +1248,8 @@ INSERT INTO public.achievements (name, description, icon, points_value) VALUES
 ('List Sharer', 'Share a shopping list with another user for the first time.', 'list', 20),
 ('First Favorite', 'Mark a recipe as one of your favorites.', 'heart', 5),
 ('First Fork', 'Make a personal copy of a public recipe.', 'git-fork', 10),
-('First Budget Created', 'Create your first budget to track spending.', 'piggy-bank', 15)
+('First Budget Created', 'Create your first budget to track spending.', 'piggy-bank', 15),
+('First-Upload', 'Upload your first flyer.', 'upload-cloud', 25)
 ON CONFLICT (name) DO NOTHING;
 
 -- ============================================================================
@@ -2114,6 +2115,61 @@ AS $$
   ORDER BY potential_savings_cents DESC;
 $$;
 
+-- Function to get a user's spending breakdown by category for a given date range.
+DROP FUNCTION IF EXISTS public.get_spending_by_category(UUID, DATE, DATE);
+
+CREATE OR REPLACE FUNCTION public.get_spending_by_category(p_user_id UUID, p_start_date DATE, p_end_date DATE)
+RETURNS TABLE (
+    category_id BIGINT,
+    category_name TEXT,
+    total_spent_cents BIGINT
+)
+LANGUAGE sql
+STABLE
+SECURITY INVOKER
+AS $$
+  WITH all_purchases AS (
+    -- CTE 1: Combine purchases from completed shopping trips.
+    -- We only consider items that have a price paid.
+    SELECT
+      sti.master_item_id,
+      sti.price_paid_cents
+    FROM public.shopping_trip_items sti
+    JOIN public.shopping_trips st ON sti.shopping_trip_id = st.shopping_trip_id
+    WHERE st.user_id = p_user_id
+      AND st.completed_at::date BETWEEN p_start_date AND p_end_date
+      AND sti.price_paid_cents IS NOT NULL
+
+    UNION ALL
+
+    -- CTE 2: Combine purchases from processed receipts.
+    SELECT
+      ri.master_item_id,
+      ri.price_paid_cents
+    FROM public.receipt_items ri
+    JOIN public.receipts r ON ri.receipt_id = r.receipt_id
+    WHERE r.user_id = p_user_id
+      AND r.transaction_date::date BETWEEN p_start_date AND p_end_date
+      AND ri.master_item_id IS NOT NULL -- Only include items matched to a master item
+  )
+  -- Final Aggregation: Group all combined purchases by category and sum the spending.
+  SELECT
+    c.category_id,
+    c.name AS category_name,
+    SUM(ap.price_paid_cents)::BIGINT AS total_spent_cents
+  FROM all_purchases ap
+  -- Join with master_grocery_items to get the category_id for each purchase.
+  JOIN public.master_grocery_items mgi ON ap.master_item_id = mgi.master_grocery_item_id
+  -- Join with categories to get the category name for display.
+  JOIN public.categories c ON mgi.category_id = c.category_id
+  GROUP BY
+    c.category_id, c.name
+  HAVING
+    SUM(ap.price_paid_cents) > 0
+  ORDER BY
+    total_spent_cents DESC;
+$$;
+
 -- Function to approve a suggested correction and apply it.
 DROP FUNCTION IF EXISTS public.approve_correction(BIGINT);
 
@@ -2557,16 +2613,21 @@ DROP FUNCTION IF EXISTS public.log_new_flyer();
 CREATE OR REPLACE FUNCTION public.log_new_flyer()
 RETURNS TRIGGER AS $$
 BEGIN
-    INSERT INTO public.activity_log (action, display_text, icon, details)
+    -- If the flyer was uploaded by a registered user, award the 'First-Upload' achievement.
+    -- The award_achievement function handles checking if the user already has it.
+    IF NEW.uploaded_by IS NOT NULL THEN
+        PERFORM public.award_achievement(NEW.uploaded_by, 'First-Upload');
+    END IF;
+
+    INSERT INTO public.activity_log (user_id, action, display_text, icon, details)
     VALUES (
+        NEW.uploaded_by, -- Log the user who uploaded it
         'flyer_uploaded',
         'A new flyer for ' || (SELECT name FROM public.stores WHERE store_id = NEW.store_id) || ' has been uploaded.',
         'file-text',
         jsonb_build_object(
             'flyer_id', NEW.flyer_id,
-            'store_name', (SELECT name FROM public.stores WHERE store_id = NEW.store_id),
-            'valid_from', to_char(NEW.valid_from, 'YYYY-MM-DD'),
-            'valid_to', to_char(NEW.valid_to, 'YYYY-MM-DD')
+            'store_name', (SELECT name FROM public.stores WHERE store_id = NEW.store_id)
         )
     );
     RETURN NEW;
@@ -2663,6 +2724,58 @@ CREATE TRIGGER on_new_recipe_collection_share
   AFTER INSERT ON public.shared_recipe_collections
   FOR EACH ROW EXECUTE FUNCTION public.log_new_recipe_collection_share();
 
+-- 10. Trigger function to geocode a store location's address.
+-- This function is designed to be extensible for external geocoding services.
+DROP FUNCTION IF EXISTS public.geocode_store_location();
+
+CREATE OR REPLACE FUNCTION public.geocode_store_location()
+RETURNS TRIGGER AS $$
+DECLARE
+    full_address TEXT;
+BEGIN
+    -- Only proceed if the address has actually changed.
+    -- Note: We check against the linked address fields via the NEW.address_id in a real scenario,
+    -- but for this trigger to work effectively, it usually requires a direct update on the address table
+    -- or this trigger should be moved to the 'addresses' table. 
+    -- However, based on the provided logic, we are keeping the placeholder structure.
+    
+    -- Placeholder logic:
+    IF TG_OP = 'INSERT' THEN
+       -- Logic to fetch address string based on NEW.address_id and geocode
+       NULL;
+    END IF;
+
+    RETURN NEW;
+END;
+$$ LANGUAGE plpgsql;
+
+-- Trigger to call the geocoding function.
+DROP TRIGGER IF EXISTS on_store_location_address_change ON public.store_locations;
+CREATE TRIGGER on_store_location_address_change
+  BEFORE INSERT OR UPDATE ON public.store_locations
+  FOR EACH ROW EXECUTE FUNCTION public.geocode_store_location();
+
+-- 11. Trigger function to increment the fork_count on the original recipe.
+DROP FUNCTION IF EXISTS public.increment_recipe_fork_count();
+
+CREATE OR REPLACE FUNCTION public.increment_recipe_fork_count()
+RETURNS TRIGGER AS $$
+BEGIN
+    -- Only run if the recipe is a fork (original_recipe_id is not null).
+    IF NEW.original_recipe_id IS NOT NULL THEN
+        UPDATE public.recipes SET fork_count = fork_count + 1 WHERE recipe_id = NEW.original_recipe_id;
+        -- Award 'First Fork' achievement.
+        PERFORM public.award_achievement(NEW.user_id, 'First Fork');
+    END IF;
+    RETURN NEW;
+END;
+$$ LANGUAGE plpgsql;
+
+DROP TRIGGER IF EXISTS on_recipe_fork ON public.recipes;
+CREATE TRIGGER on_recipe_fork
+  AFTER INSERT ON public.recipes
+  FOR EACH ROW EXECUTE FUNCTION public.increment_recipe_fork_count();
+
 -- =================================================================
 -- Function: get_best_sale_prices_for_all_users()
 -- Description: Retrieves the best sale price for every item on every user's watchlist.

src/components/AchievementsList.test.tsx

@@ -1,9 +1,10 @@
 // src/components/AchievementsList.test.tsx
 import React from 'react';
-import { render, screen } from '@testing-library/react';
+import { screen } from '@testing-library/react';
 import { describe, it, expect } from 'vitest';
 import { AchievementsList } from './AchievementsList';
 import { createMockUserAchievement } from '../tests/utils/mockFactories';
+import { renderWithProviders } from '../tests/utils/renderWithProviders';
 
 describe('AchievementsList', () => {
   it('should render the list of achievements with correct details', () => {
@@ -24,7 +25,7 @@ describe('AchievementsList', () => {
       createMockUserAchievement({ achievement_id: 3, name: 'Unknown Achievement', icon: 'star' }), // This icon is not in the component's map
     ];
 
-    render(<AchievementsList achievements={mockAchievements} />);
+    renderWithProviders(<AchievementsList achievements={mockAchievements} />);
 
     expect(screen.getByRole('heading', { name: /achievements/i })).toBeInTheDocument();
 
@@ -44,7 +45,7 @@ describe('AchievementsList', () => {
   });
 
   it('should render a message when there are no achievements', () => {
-    render(<AchievementsList achievements={[]} />);
+    renderWithProviders(<AchievementsList achievements={[]} />);
     expect(
       screen.getByText('No achievements earned yet. Keep exploring to unlock them!'),
     ).toBeInTheDocument();

src/components/AdminRoute.test.tsx

@@ -1,11 +1,12 @@
 // src/components/AdminRoute.test.tsx
 import React from 'react';
-import { render, screen } from '@testing-library/react';
-import { describe, it, expect } from 'vitest';
-import { MemoryRouter, Routes, Route } from 'react-router-dom';
+import { screen } from '@testing-library/react';
+import { describe, it, expect, vi } from 'vitest';
+import { Routes, Route } from 'react-router-dom';
 import { AdminRoute } from './AdminRoute';
 import type { Profile } from '../types';
 import { createMockProfile } from '../tests/utils/mockFactories';
+import { renderWithProviders } from '../tests/utils/renderWithProviders';
 
 // Unmock the component to test the real implementation
 vi.unmock('./AdminRoute');
@@ -14,15 +15,14 @@ const AdminContent = () => <div>Admin Page Content</div>;
 const HomePage = () => <div>Home Page</div>;
 
 const renderWithRouter = (profile: Profile | null, initialPath: string) => {
-  render(
-    <MemoryRouter initialEntries={[initialPath]}>
-      <Routes>
-        <Route path="/" element={<HomePage />} />
-        <Route path="/admin" element={<AdminRoute profile={profile} />}>
-          <Route index element={<AdminContent />} />
-        </Route>
-      </Routes>
-    </MemoryRouter>,
+  renderWithProviders(
+    <Routes>
+      <Route path="/" element={<HomePage />} />
+      <Route path="/admin" element={<AdminRoute profile={profile} />}>
+        <Route index element={<AdminContent />} />
+      </Route>
+    </Routes>,
+    { initialEntries: [initialPath] },
   );
 };
 

src/components/AnonymousUserBanner.test.tsx

@@ -1,8 +1,9 @@
 // src/components/AnonymousUserBanner.test.tsx
 import React from 'react';
-import { render, screen, fireEvent } from '@testing-library/react';
+import { screen, fireEvent } from '@testing-library/react';
 import { describe, it, expect, vi } from 'vitest';
 import { AnonymousUserBanner } from './AnonymousUserBanner';
+import { renderWithProviders } from '../tests/utils/renderWithProviders';
 
 // Mock the icon to ensure it is rendered correctly
 vi.mock('./icons/InformationCircleIcon', () => ({
@@ -14,7 +15,7 @@ vi.mock('./icons/InformationCircleIcon', () => ({
 describe('AnonymousUserBanner', () => {
   it('should render the banner with the correct text content and accessibility role', () => {
     const mockOnOpenProfile = vi.fn();
-    render(<AnonymousUserBanner onOpenProfile={mockOnOpenProfile} />);
+    renderWithProviders(<AnonymousUserBanner onOpenProfile={mockOnOpenProfile} />);
 
     // Check for accessibility role
     expect(screen.getByRole('alert')).toBeInTheDocument();
@@ -30,7 +31,7 @@ describe('AnonymousUserBanner', () => {
 
   it('should call onOpenProfile when the "sign up or log in" button is clicked', () => {
     const mockOnOpenProfile = vi.fn();
-    render(<AnonymousUserBanner onOpenProfile={mockOnOpenProfile} />);
+    renderWithProviders(<AnonymousUserBanner onOpenProfile={mockOnOpenProfile} />);
 
     const loginButton = screen.getByRole('button', { name: /sign up or log in/i });
     fireEvent.click(loginButton);

src/components/AppGuard.test.tsx

@@ -1,12 +1,15 @@
 // src/components/AppGuard.test.tsx
 import React from 'react';
-import { render, screen, waitFor } from '@testing-library/react';
+import { screen, waitFor } from '@testing-library/react';
 import { describe, it, expect, vi, beforeEach } from 'vitest';
 import { AppGuard } from './AppGuard';
 import { useAppInitialization } from '../hooks/useAppInitialization';
+import * as apiClient from '../services/apiClient';
 import { useModal } from '../hooks/useModal';
+import { renderWithProviders } from '../tests/utils/renderWithProviders';
 
 // Mock dependencies
+// The apiClient is mocked globally in `src/tests/setup/globalApiMock.ts`.
 vi.mock('../hooks/useAppInitialization');
 vi.mock('../hooks/useModal');
 vi.mock('./WhatsNewModal', () => ({
@@ -19,6 +22,7 @@ vi.mock('../config', () => ({
   },
 }));
 
+const mockedApiClient = vi.mocked(apiClient);
 const mockedUseAppInitialization = vi.mocked(useAppInitialization);
 const mockedUseModal = vi.mocked(useModal);
 
@@ -38,7 +42,7 @@ describe('AppGuard', () => {
   });
 
   it('should render children', () => {
-    render(
+    renderWithProviders(
       <AppGuard>
         <div>Child Content</div>
       </AppGuard>,
@@ -51,7 +55,7 @@ describe('AppGuard', () => {
       ...mockedUseModal(),
       isModalOpen: (modalId) => modalId === 'whatsNew',
     });
-    render(
+    renderWithProviders(
       <AppGuard>
         <div>Child</div>
       </AppGuard>,
@@ -64,7 +68,7 @@ describe('AppGuard', () => {
       isDarkMode: true,
       unitSystem: 'imperial',
     });
-    render(
+    renderWithProviders(
       <AppGuard>
         <div>Child</div>
       </AppGuard>,
@@ -78,7 +82,7 @@ describe('AppGuard', () => {
   });
 
   it('should set light mode styles for toaster', async () => {
-    render(
+    renderWithProviders(
       <AppGuard>
         <div>Child</div>
       </AppGuard>,

src/components/ConfirmationModal.test.tsx

@@ -1,8 +1,9 @@
 // src/components/ConfirmationModal.test.tsx
 import React from 'react';
-import { render, screen, fireEvent } from '@testing-library/react';
+import { screen, fireEvent } from '@testing-library/react';
 import { describe, it, expect, vi, beforeEach } from 'vitest';
 import { ConfirmationModal } from './ConfirmationModal';
+import { renderWithProviders } from '../tests/utils/renderWithProviders';
 
 describe('ConfirmationModal (in components)', () => {
   const mockOnClose = vi.fn();
@@ -21,12 +22,12 @@ describe('ConfirmationModal (in components)', () => {
   });
 
   it('should not render when isOpen is false', () => {
-    const { container } = render(<ConfirmationModal {...defaultProps} isOpen={false} />);
+    const { container } = renderWithProviders(<ConfirmationModal {...defaultProps} isOpen={false} />);
     expect(container.firstChild).toBeNull();
   });
 
   it('should render correctly when isOpen is true', () => {
-    render(<ConfirmationModal {...defaultProps} />);
+    renderWithProviders(<ConfirmationModal {...defaultProps} />);
     expect(screen.getByRole('heading', { name: 'Confirm Action' })).toBeInTheDocument();
     expect(screen.getByText('Are you sure you want to do this?')).toBeInTheDocument();
     expect(screen.getByRole('button', { name: 'Confirm' })).toBeInTheDocument();
@@ -34,38 +35,38 @@ describe('ConfirmationModal (in components)', () => {
   });
 
   it('should call onConfirm when the confirm button is clicked', () => {
-    render(<ConfirmationModal {...defaultProps} />);
+    renderWithProviders(<ConfirmationModal {...defaultProps} />);
     fireEvent.click(screen.getByRole('button', { name: 'Confirm' }));
     expect(mockOnConfirm).toHaveBeenCalledTimes(1);
   });
 
   it('should call onClose when the cancel button is clicked', () => {
-    render(<ConfirmationModal {...defaultProps} />);
+    renderWithProviders(<ConfirmationModal {...defaultProps} />);
     fireEvent.click(screen.getByRole('button', { name: 'Cancel' }));
     expect(mockOnClose).toHaveBeenCalledTimes(1);
   });
 
   it('should call onClose when the close icon is clicked', () => {
-    render(<ConfirmationModal {...defaultProps} />);
+    renderWithProviders(<ConfirmationModal {...defaultProps} />);
     fireEvent.click(screen.getByLabelText('Close confirmation modal'));
     expect(mockOnClose).toHaveBeenCalledTimes(1);
   });
 
   it('should call onClose when the overlay is clicked', () => {
-    render(<ConfirmationModal {...defaultProps} />);
+    renderWithProviders(<ConfirmationModal {...defaultProps} />);
     // The overlay is the parent of the modal content div
     fireEvent.click(screen.getByRole('dialog'));
     expect(mockOnClose).toHaveBeenCalledTimes(1);
   });
 
   it('should not call onClose when clicking inside the modal content', () => {
-    render(<ConfirmationModal {...defaultProps} />);
+    renderWithProviders(<ConfirmationModal {...defaultProps} />);
     fireEvent.click(screen.getByText('Are you sure you want to do this?'));
     expect(mockOnClose).not.toHaveBeenCalled();
   });
 
   it('should render custom button text and classes', () => {
-    render(
+    renderWithProviders(
       <ConfirmationModal
         {...defaultProps}
         confirmButtonText="Yes, Delete"

src/components/DarkModeToggle.test.tsx

@@ -1,8 +1,9 @@
 // src/components/DarkModeToggle.test.tsx
 import React from 'react';
-import { render, screen, fireEvent } from '@testing-library/react';
+import { screen, fireEvent } from '@testing-library/react';
 import { describe, it, expect, vi, beforeEach } from 'vitest';
 import { DarkModeToggle } from './DarkModeToggle';
+import { renderWithProviders } from '../tests/utils/renderWithProviders';
 
 // Mock the icon components to isolate the toggle's logic
 vi.mock('./icons/SunIcon', () => ({
@@ -20,7 +21,7 @@ describe('DarkModeToggle', () => {
   });
 
   it('should render in light mode state', () => {
-    render(<DarkModeToggle isDarkMode={false} onToggle={mockOnToggle} />);
+    renderWithProviders(<DarkModeToggle isDarkMode={false} onToggle={mockOnToggle} />);
 
     const checkbox = screen.getByRole('checkbox');
     expect(checkbox).not.toBeChecked();
@@ -29,7 +30,7 @@ describe('DarkModeToggle', () => {
   });
 
   it('should render in dark mode state', () => {
-    render(<DarkModeToggle isDarkMode={true} onToggle={mockOnToggle} />);
+    renderWithProviders(<DarkModeToggle isDarkMode={true} onToggle={mockOnToggle} />);
 
     const checkbox = screen.getByRole('checkbox');
     expect(checkbox).toBeChecked();
@@ -38,7 +39,7 @@ describe('DarkModeToggle', () => {
   });
 
   it('should call onToggle when the label is clicked', () => {
-    render(<DarkModeToggle isDarkMode={false} onToggle={mockOnToggle} />);
+    renderWithProviders(<DarkModeToggle isDarkMode={false} onToggle={mockOnToggle} />);
 
     // Clicking the label triggers the checkbox change
     const label = screen.getByTitle('Switch to Dark Mode');

src/components/Dashboard.test.tsx

@@ -0,0 +1,67 @@
+// src/components/Dashboard.test.tsx
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { screen } from '@testing-library/react';
+import { Dashboard } from './Dashboard';
+import { renderWithProviders } from '../tests/utils/renderWithProviders';
+
+// Mock child components to isolate Dashboard logic
+// Note: The Dashboard component imports these using '../components/RecipeSuggester'
+// which resolves to the same file as './RecipeSuggester' when inside src/components.
+vi.mock('./RecipeSuggester', () => ({
+  RecipeSuggester: () => <div data-testid="recipe-suggester-mock">Recipe Suggester</div>,
+}));
+
+vi.mock('./FlyerCountDisplay', () => ({
+  FlyerCountDisplay: () => <div data-testid="flyer-count-display-mock">Flyer Count Display</div>,
+}));
+
+vi.mock('./Leaderboard', () => ({
+  Leaderboard: () => <div data-testid="leaderboard-mock">Leaderboard</div>,
+}));
+
+describe('Dashboard Component', () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  it('renders the dashboard title', () => {
+    console.log('TEST: Verifying dashboard title render');
+    renderWithProviders(<Dashboard />);
+    expect(screen.getByRole('heading', { name: /dashboard/i, level: 1 })).toBeInTheDocument();
+  });
+
+  it('renders the RecipeSuggester widget', () => {
+    console.log('TEST: Verifying RecipeSuggester presence');
+    renderWithProviders(<Dashboard />);
+    expect(screen.getByTestId('recipe-suggester-mock')).toBeInTheDocument();
+  });
+
+  it('renders the FlyerCountDisplay widget within the "Your Flyers" section', () => {
+    console.log('TEST: Verifying FlyerCountDisplay presence and section title');
+    renderWithProviders(<Dashboard />);
+
+    // Check for the section heading
+    expect(screen.getByRole('heading', { name: /your flyers/i, level: 2 })).toBeInTheDocument();
+
+    // Check for the component
+    expect(screen.getByTestId('flyer-count-display-mock')).toBeInTheDocument();
+  });
+
+  it('renders the Leaderboard widget in the sidebar area', () => {
+    console.log('TEST: Verifying Leaderboard presence');
+    renderWithProviders(<Dashboard />);
+    expect(screen.getByTestId('leaderboard-mock')).toBeInTheDocument();
+  });
+
+  it('renders with the correct grid layout classes', () => {
+    console.log('TEST: Verifying layout classes');
+    const { container } = renderWithProviders(<Dashboard />);
+
+    // The main grid container
+    const gridContainer = container.querySelector('.grid');
+    expect(gridContainer).toBeInTheDocument();
+    expect(gridContainer).toHaveClass('grid-cols-1');
+    expect(gridContainer).toHaveClass('lg:grid-cols-3');
+    expect(gridContainer).toHaveClass('gap-6');
+  });
+});

src/components/Dashboard.tsx

@@ -0,0 +1,33 @@
+import React from 'react';
+import { RecipeSuggester } from '../components/RecipeSuggester';
+import { FlyerCountDisplay } from '../components/FlyerCountDisplay';
+import { Leaderboard } from '../components/Leaderboard';
+
+export const Dashboard: React.FC = () => {
+  return (
+    <div className="max-w-7xl mx-auto px-4 sm:px-6 lg:px-8 py-8">
+      <h1 className="text-2xl font-bold text-gray-900 dark:text-white mb-6">Dashboard</h1>
+      
+      <div className="grid grid-cols-1 lg:grid-cols-3 gap-6">
+        {/* Main Content Area */}
+        <div className="lg:col-span-2 space-y-6">
+          {/* Recipe Suggester Section */}
+          <RecipeSuggester />
+
+          {/* Other Dashboard Widgets */}
+          <div className="bg-white dark:bg-gray-800 shadow rounded-lg p-6">
+            <h2 className="text-lg font-medium text-gray-900 dark:text-white mb-4">Your Flyers</h2>
+            <FlyerCountDisplay />
+          </div>
+        </div>
+
+        {/* Sidebar Area */}
+        <div className="space-y-6">
+          <Leaderboard />
+        </div>
+      </div>
+    </div>
+  );
+};
+
+export default Dashboard;

src/components/ErrorDisplay.test.tsx

@@ -1,24 +1,25 @@
 // src/components/ErrorDisplay.test.tsx
 import React from 'react';
-import { render, screen } from '@testing-library/react';
+import { screen } from '@testing-library/react';
 import { describe, it, expect } from 'vitest';
 import { ErrorDisplay } from './ErrorDisplay';
+import { renderWithProviders } from '../tests/utils/renderWithProviders';
 
 describe('ErrorDisplay (in components)', () => {
   it('should not render when the message is empty', () => {
-    const { container } = render(<ErrorDisplay message="" />);
+    const { container } = renderWithProviders(<ErrorDisplay message="" />);
     expect(container.firstChild).toBeNull();
   });
 
   it('should not render when the message is null', () => {
     // The component expects a string, but we test for nullish values as a safeguard.
-    const { container } = render(<ErrorDisplay message={null as unknown as string} />);
+    const { container } = renderWithProviders(<ErrorDisplay message={null as unknown as string} />);
     expect(container.firstChild).toBeNull();
   });
 
   it('should render the error message when provided', () => {
     const errorMessage = 'Something went terribly wrong.';
-    render(<ErrorDisplay message={errorMessage} />);
+    renderWithProviders(<ErrorDisplay message={errorMessage} />);
 
     const alert = screen.getByRole('alert');
     expect(alert).toBeInTheDocument();

src/components/FlyerCorrectionTool.test.tsx

@@ -1,24 +1,18 @@
 // src/components/FlyerCorrectionTool.test.tsx
 import React from 'react';
-import { render, screen, fireEvent, waitFor, act } from '@testing-library/react';
+import { screen, fireEvent, waitFor, act } from '@testing-library/react';
 import { describe, it, expect, vi, beforeEach, type Mocked } from 'vitest';
 import { FlyerCorrectionTool } from './FlyerCorrectionTool';
 import * as aiApiClient from '../services/aiApiClient';
 import { notifyError, notifySuccess } from '../services/notificationService';
+import { renderWithProviders } from '../tests/utils/renderWithProviders';
 
 // Unmock the component to test the real implementation
 vi.unmock('./FlyerCorrectionTool');
 
-// Mock dependencies
-vi.mock('../services/aiApiClient');
-vi.mock('../services/notificationService');
-vi.mock('../services/logger', () => ({
-  logger: {
-    error: vi.fn(),
-  },
-}));
-
-const mockedAiApiClient = aiApiClient as Mocked<typeof aiApiClient>;
+// The aiApiClient, notificationService, and logger are mocked globally.
+// We can get a typed reference to the aiApiClient for individual test overrides.
+const mockedAiApiClient = vi.mocked(aiApiClient);
 const mockedNotifySuccess = notifySuccess as Mocked<typeof notifySuccess>;
 const mockedNotifyError = notifyError as Mocked<typeof notifyError>;
 
@@ -54,12 +48,12 @@ describe('FlyerCorrectionTool', () => {
   });
 
   it('should not render when isOpen is false', () => {
-    const { container } = render(<FlyerCorrectionTool {...defaultProps} isOpen={false} />);
+    const { container } = renderWithProviders(<FlyerCorrectionTool {...defaultProps} isOpen={false} />);
     expect(container.firstChild).toBeNull();
   });
 
   it('should render correctly when isOpen is true', () => {
-    render(<FlyerCorrectionTool {...defaultProps} />);
+    renderWithProviders(<FlyerCorrectionTool {...defaultProps} />);
     expect(screen.getByRole('heading', { name: /flyer correction tool/i })).toBeInTheDocument();
     expect(screen.getByAltText('Flyer for correction')).toBeInTheDocument();
     expect(screen.getByRole('button', { name: /extract store name/i })).toBeInTheDocument();
@@ -67,7 +61,7 @@ describe('FlyerCorrectionTool', () => {
   });
 
   it('should call onClose when the close button is clicked', () => {
-    render(<FlyerCorrectionTool {...defaultProps} />);
+    renderWithProviders(<FlyerCorrectionTool {...defaultProps} />);
     // Use the specific aria-label defined in the component to find the close button
     const closeButton = screen.getByLabelText(/close correction tool/i);
     fireEvent.click(closeButton);
@@ -75,13 +69,13 @@ describe('FlyerCorrectionTool', () => {
   });
 
   it('should have disabled extraction buttons initially', () => {
-    render(<FlyerCorrectionTool {...defaultProps} />);
+    renderWithProviders(<FlyerCorrectionTool {...defaultProps} />);
     expect(screen.getByRole('button', { name: /extract store name/i })).toBeDisabled();
     expect(screen.getByRole('button', { name: /extract sale dates/i })).toBeDisabled();
   });
 
   it('should enable extraction buttons after a selection is made', () => {
-    render(<FlyerCorrectionTool {...defaultProps} />);
+    renderWithProviders(<FlyerCorrectionTool {...defaultProps} />);
     const canvas = screen.getByRole('dialog').querySelector('canvas')!;
 
     // Simulate drawing a rectangle
@@ -94,7 +88,7 @@ describe('FlyerCorrectionTool', () => {
   });
 
   it('should stop drawing when the mouse leaves the canvas', () => {
-    render(<FlyerCorrectionTool {...defaultProps} />);
+    renderWithProviders(<FlyerCorrectionTool {...defaultProps} />);
     const canvas = screen.getByRole('dialog').querySelector('canvas')!;
 
     fireEvent.mouseDown(canvas, { clientX: 10, clientY: 10 });
@@ -114,7 +108,7 @@ describe('FlyerCorrectionTool', () => {
     });
     mockedAiApiClient.rescanImageArea.mockReturnValue(rescanPromise);
 
-    render(<FlyerCorrectionTool {...defaultProps} />);
+    renderWithProviders(<FlyerCorrectionTool {...defaultProps} />);
 
     // Wait for the image fetch to complete to ensure 'imageFile' state is populated
     console.log('--- [TEST LOG] ---: Awaiting image fetch inside component...');
@@ -192,7 +186,7 @@ describe('FlyerCorrectionTool', () => {
     // Mock fetch to reject
     global.fetch = vi.fn(() => Promise.reject(new Error('Network error'))) as Mocked<typeof fetch>;
 
-    render(<FlyerCorrectionTool {...defaultProps} />);
+    renderWithProviders(<FlyerCorrectionTool {...defaultProps} />);
 
     await waitFor(() => {
       expect(mockedNotifyError).toHaveBeenCalledWith('Could not load the image for correction.');
@@ -211,7 +205,7 @@ describe('FlyerCorrectionTool', () => {
       return new Promise(() => {});
     }) as Mocked<typeof fetch>;
 
-    render(<FlyerCorrectionTool {...defaultProps} />);
+    renderWithProviders(<FlyerCorrectionTool {...defaultProps} />);
 
     const canvas = screen.getByRole('dialog').querySelector('canvas')!;
 
@@ -238,7 +232,7 @@ describe('FlyerCorrectionTool', () => {
   it('should handle non-standard API errors during rescan', async () => {
     console.log('TEST: Starting "should handle non-standard API errors during rescan"');
     mockedAiApiClient.rescanImageArea.mockRejectedValue('A plain string error');
-    render(<FlyerCorrectionTool {...defaultProps} />);
+    renderWithProviders(<FlyerCorrectionTool {...defaultProps} />);
 
     // Wait for image fetch to ensure imageFile is set before we interact
     await waitFor(() => expect(global.fetch).toHaveBeenCalled());

src/components/FlyerCountDisplay.test.tsx

@@ -1,11 +1,12 @@
 // src/components/FlyerCountDisplay.test.tsx
 import React from 'react';
-import { render, screen } from '@testing-library/react';
+import { screen } from '@testing-library/react';
 import { describe, it, expect, vi, beforeEach } from 'vitest';
 import { FlyerCountDisplay } from './FlyerCountDisplay';
 import { useFlyers } from '../hooks/useFlyers';
 import type { Flyer } from '../types';
 import { createMockFlyer } from '../tests/utils/mockFactories';
+import { renderWithProviders } from '../tests/utils/renderWithProviders';
 
 // Mock the dependencies
 vi.mock('../hooks/useFlyers');
@@ -32,7 +33,7 @@ describe('FlyerCountDisplay', () => {
     });
 
     // Act: Render the component.
-    render(<FlyerCountDisplay />);
+    renderWithProviders(<FlyerCountDisplay />);
 
     // Assert: Check that the loading spinner is visible.
     expect(screen.getByTestId('loading-spinner')).toBeInTheDocument();
@@ -53,7 +54,7 @@ describe('FlyerCountDisplay', () => {
     });
 
     // Act
-    render(<FlyerCountDisplay />);
+    renderWithProviders(<FlyerCountDisplay />);
 
     // Assert: Check that the error message is displayed.
     expect(screen.getByRole('alert')).toHaveTextContent(errorMessage);
@@ -73,7 +74,7 @@ describe('FlyerCountDisplay', () => {
     });
 
     // Act
-    render(<FlyerCountDisplay />);
+    renderWithProviders(<FlyerCountDisplay />);
 
     // Assert: Check that the correct count is displayed.
     const countDisplay = screen.getByTestId('flyer-count');

src/components/Footer.test.tsx

@@ -1,8 +1,9 @@
 // src/components/Footer.test.tsx
 import React from 'react';
-import { render, screen } from '@testing-library/react';
+import { screen } from '@testing-library/react';
 import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
 import { Footer } from './Footer';
+import { renderWithProviders } from '../tests/utils/renderWithProviders';
 
 describe('Footer', () => {
   beforeEach(() => {
@@ -21,7 +22,7 @@ describe('Footer', () => {
     vi.setSystemTime(mockDate);
 
     // Act: Render the component
-    render(<Footer />);
+    renderWithProviders(<Footer />);
 
     // Assert: Check that the rendered text includes the mocked year
     expect(screen.getByText('Copyright 2025-2025')).toBeInTheDocument();
@@ -29,7 +30,7 @@ describe('Footer', () => {
 
   it('should display the correct year when it changes', () => {
     vi.setSystemTime(new Date('2030-01-01T00:00:00Z'));
-    render(<Footer />);
+    renderWithProviders(<Footer />);
     expect(screen.getByText('Copyright 2025-2030')).toBeInTheDocument();
   });
 });

src/components/Header.test.tsx

@@ -1,11 +1,11 @@
 // src/components/Header.test.tsx
 import React from 'react';
-import { render, screen, fireEvent } from '@testing-library/react';
+import { screen, fireEvent } from '@testing-library/react';
 import { describe, it, expect, vi, beforeEach } from 'vitest';
-import { MemoryRouter } from 'react-router-dom';
 import { Header } from './Header';
 import type { UserProfile } from '../types';
 import { createMockUserProfile } from '../tests/utils/mockFactories';
+import { renderWithProviders } from '../tests/utils/renderWithProviders';
 
 // Unmock the component to test the real implementation
 vi.unmock('./Header');
@@ -34,12 +34,8 @@ const defaultProps = {
 };
 
 // Helper to render with router context
-const renderWithRouter = (props: Partial<React.ComponentProps<typeof Header>>) => {
-  return render(
-    <MemoryRouter>
-      <Header {...defaultProps} {...props} />
-    </MemoryRouter>,
-  );
+const renderHeader = (props: Partial<React.ComponentProps<typeof Header>>) => {
+  return renderWithProviders(<Header {...defaultProps} {...props} />);
 };
 
 describe('Header', () => {
@@ -48,30 +44,30 @@ describe('Header', () => {
   });
 
   it('should render the application title', () => {
-    renderWithRouter({});
+    renderHeader({});
     expect(screen.getByRole('heading', { name: /flyer crawler/i })).toBeInTheDocument();
   });
 
   it('should display unit system and theme mode', () => {
-    renderWithRouter({ isDarkMode: true, unitSystem: 'metric' });
+    renderHeader({ isDarkMode: true, unitSystem: 'metric' });
     expect(screen.getByText(/metric/i)).toBeInTheDocument();
     expect(screen.getByText(/dark mode/i)).toBeInTheDocument();
   });
 
   describe('When user is logged out', () => {
     it('should show a Login button', () => {
-      renderWithRouter({ userProfile: null, authStatus: 'SIGNED_OUT' });
+      renderHeader({ userProfile: null, authStatus: 'SIGNED_OUT' });
       expect(screen.getByRole('button', { name: /login/i })).toBeInTheDocument();
     });
 
     it('should call onOpenProfile when Login button is clicked', () => {
-      renderWithRouter({ userProfile: null, authStatus: 'SIGNED_OUT' });
+      renderHeader({ userProfile: null, authStatus: 'SIGNED_OUT' });
       fireEvent.click(screen.getByRole('button', { name: /login/i }));
       expect(mockOnOpenProfile).toHaveBeenCalledTimes(1);
     });
 
     it('should not show user-specific buttons', () => {
-      renderWithRouter({ userProfile: null, authStatus: 'SIGNED_OUT' });
+      renderHeader({ userProfile: null, authStatus: 'SIGNED_OUT' });
       expect(screen.queryByLabelText(/open voice assistant/i)).not.toBeInTheDocument();
       expect(screen.queryByLabelText(/open my account settings/i)).not.toBeInTheDocument();
       expect(screen.queryByRole('button', { name: /logout/i })).not.toBeInTheDocument();
@@ -80,29 +76,29 @@ describe('Header', () => {
 
   describe('When user is authenticated', () => {
     it('should display the user email', () => {
-      renderWithRouter({ userProfile: mockUserProfile, authStatus: 'AUTHENTICATED' });
+      renderHeader({ userProfile: mockUserProfile, authStatus: 'AUTHENTICATED' });
       expect(screen.getByText(mockUserProfile.user.email)).toBeInTheDocument();
     });
 
     it('should display "Guest" for anonymous users', () => {
-      renderWithRouter({ userProfile: mockUserProfile, authStatus: 'SIGNED_OUT' });
+      renderHeader({ userProfile: mockUserProfile, authStatus: 'SIGNED_OUT' });
       expect(screen.getByText(/guest/i)).toBeInTheDocument();
     });
 
     it('should call onOpenVoiceAssistant when microphone icon is clicked', () => {
-      renderWithRouter({ userProfile: mockUserProfile, authStatus: 'AUTHENTICATED' });
+      renderHeader({ userProfile: mockUserProfile, authStatus: 'AUTHENTICATED' });
       fireEvent.click(screen.getByLabelText(/open voice assistant/i));
       expect(mockOnOpenVoiceAssistant).toHaveBeenCalledTimes(1);
     });
 
     it('should call onOpenProfile when cog icon is clicked', () => {
-      renderWithRouter({ userProfile: mockUserProfile, authStatus: 'AUTHENTICATED' });
+      renderHeader({ userProfile: mockUserProfile, authStatus: 'AUTHENTICATED' });
       fireEvent.click(screen.getByLabelText(/open my account settings/i));
       expect(mockOnOpenProfile).toHaveBeenCalledTimes(1);
     });
 
     it('should call onSignOut when Logout button is clicked', () => {
-      renderWithRouter({ userProfile: mockUserProfile, authStatus: 'AUTHENTICATED' });
+      renderHeader({ userProfile: mockUserProfile, authStatus: 'AUTHENTICATED' });
       fireEvent.click(screen.getByRole('button', { name: /logout/i }));
       expect(mockOnSignOut).toHaveBeenCalledTimes(1);
     });
@@ -110,14 +106,14 @@ describe('Header', () => {
 
   describe('Admin user', () => {
     it('should show the Admin Area link for admin users', () => {
-      renderWithRouter({ userProfile: mockAdminProfile, authStatus: 'AUTHENTICATED' });
+      renderHeader({ userProfile: mockAdminProfile, authStatus: 'AUTHENTICATED' });
       const adminLink = screen.getByTitle(/admin area/i);
       expect(adminLink).toBeInTheDocument();
       expect(adminLink.closest('a')).toHaveAttribute('href', '/admin');
     });
 
     it('should not show the Admin Area link for non-admin users', () => {
-      renderWithRouter({ userProfile: mockUserProfile, authStatus: 'AUTHENTICATED' });
+      renderHeader({ userProfile: mockUserProfile, authStatus: 'AUTHENTICATED' });
       expect(screen.queryByTitle(/admin area/i)).not.toBeInTheDocument();
     });
   });

src/components/Leaderboard.test.tsx

@@ -1,21 +1,17 @@
 // src/components/Leaderboard.test.tsx
 import React from 'react';
-import { render, screen, waitFor } from '@testing-library/react';
+import { screen, waitFor } from '@testing-library/react';
 import { describe, it, expect, vi, beforeEach, type Mocked } from 'vitest';
 import Leaderboard from './Leaderboard';
 import * as apiClient from '../services/apiClient';
 import { LeaderboardUser } from '../types';
 import { createMockLeaderboardUser } from '../tests/utils/mockFactories';
 import { createMockLogger } from '../tests/utils/mockLogger';
+import { renderWithProviders } from '../tests/utils/renderWithProviders';
 
-// Mock the apiClient
-vi.mock('../services/apiClient'); // This was correct
-const mockedApiClient = apiClient as Mocked<typeof apiClient>;
-
-// Mock the logger
-vi.mock('../services/logger', () => ({
-  logger: createMockLogger(),
-}));
+// The apiClient and logger are mocked globally.
+// We can get a typed reference to the apiClient for individual test overrides.
+const mockedApiClient = vi.mocked(apiClient);
 
 // Mock lucide-react icons to prevent rendering errors in the test environment
 vi.mock('lucide-react', () => ({
@@ -45,13 +41,13 @@ describe('Leaderboard', () => {
   it('should display a loading message initially', () => {
     // Mock a pending promise that never resolves to keep it in the loading state
     mockedApiClient.fetchLeaderboard.mockReturnValue(new Promise(() => {}));
-    render(<Leaderboard />);
+    renderWithProviders(<Leaderboard />);
     expect(screen.getByText('Loading Leaderboard...')).toBeInTheDocument();
   });
 
   it('should display an error message if the API call fails', async () => {
     mockedApiClient.fetchLeaderboard.mockResolvedValue(new Response(null, { status: 500 }));
-    render(<Leaderboard />);
+    renderWithProviders(<Leaderboard />);
 
     await waitFor(() => {
       expect(screen.getByRole('alert')).toBeInTheDocument();
@@ -62,7 +58,7 @@ describe('Leaderboard', () => {
   it('should display a generic error for unknown error types', async () => {
     const unknownError = 'A string error';
     mockedApiClient.fetchLeaderboard.mockRejectedValue(unknownError);
-    render(<Leaderboard />);
+    renderWithProviders(<Leaderboard />);
 
     await waitFor(() => {
       expect(screen.getByRole('alert')).toBeInTheDocument();
@@ -72,7 +68,7 @@ describe('Leaderboard', () => {
 
   it('should display a message when the leaderboard is empty', async () => {
     mockedApiClient.fetchLeaderboard.mockResolvedValue(new Response(JSON.stringify([])));
-    render(<Leaderboard />);
+    renderWithProviders(<Leaderboard />);
 
     await waitFor(() => {
       expect(
@@ -85,7 +81,7 @@ describe('Leaderboard', () => {
     mockedApiClient.fetchLeaderboard.mockResolvedValue(
       new Response(JSON.stringify(mockLeaderboardData)),
     );
-    render(<Leaderboard />);
+    renderWithProviders(<Leaderboard />);
 
     await waitFor(() => {
       expect(screen.getByRole('heading', { name: 'Top Users' })).toBeInTheDocument();
@@ -110,7 +106,7 @@ describe('Leaderboard', () => {
     mockedApiClient.fetchLeaderboard.mockResolvedValue(
       new Response(JSON.stringify(mockLeaderboardData)),
     );
-    render(<Leaderboard />);
+    renderWithProviders(<Leaderboard />);
 
     await waitFor(() => {
       // Rank 1, 2, and 3 should have a crown icon
@@ -129,7 +125,7 @@ describe('Leaderboard', () => {
     mockedApiClient.fetchLeaderboard.mockResolvedValue(
       new Response(JSON.stringify(dataWithMissingNames)),
     );
-    render(<Leaderboard />);
+    renderWithProviders(<Leaderboard />);
 
     await waitFor(() => {
       // Check for fallback name

src/components/LoadingSpinner.test.tsx

@@ -1,19 +1,19 @@
 // src/components/LoadingSpinner.test.tsx
 import React from 'react';
-import { render } from '@testing-library/react';
 import { describe, it, expect } from 'vitest';
 import { LoadingSpinner } from './LoadingSpinner';
+import { renderWithProviders } from '../tests/utils/renderWithProviders';
 
 describe('LoadingSpinner (in components)', () => {
   it('should render the SVG with animation classes', () => {
-    const { container } = render(<LoadingSpinner />);
+    const { container } = renderWithProviders(<LoadingSpinner />);
     const svgElement = container.querySelector('svg');
     expect(svgElement).toBeInTheDocument();
     expect(svgElement).toHaveClass('animate-spin');
   });
 
   it('should contain the correct SVG paths for the spinner graphic', () => {
-    const { container } = render(<LoadingSpinner />);
+    const { container } = renderWithProviders(<LoadingSpinner />);
     const circle = container.querySelector('circle');
     const path = container.querySelector('path');
     expect(circle).toBeInTheDocument();

src/components/MapView.test.tsx

@@ -1,9 +1,10 @@
 // src/components/MapView.test.tsx
 import React from 'react';
-import { render, screen } from '@testing-library/react';
+import { screen } from '@testing-library/react';
 import { describe, it, expect, vi, beforeEach } from 'vitest';
 import { MapView } from './MapView';
 import config from '../config';
+import { renderWithProviders } from '../tests/utils/renderWithProviders';
 
 // Create a type-safe mocked version of the config for easier manipulation
 const mockedConfig = vi.mocked(config);
@@ -40,14 +41,14 @@ describe('MapView', () => {
 
   describe('when API key is not configured', () => {
     it('should render a disabled message', () => {
-      render(<MapView {...defaultProps} />);
+      renderWithProviders(<MapView {...defaultProps} />);
       expect(
         screen.getByText('Map view is disabled: API key is not configured.'),
       ).toBeInTheDocument();
     });
 
     it('should not render the iframe', () => {
-      render(<MapView {...defaultProps} />);
+      renderWithProviders(<MapView {...defaultProps} />);
       // Use queryByTitle because iframes don't have a default "iframe" role
       expect(screen.queryByTitle('Map view')).not.toBeInTheDocument();
     });
@@ -62,7 +63,7 @@ describe('MapView', () => {
     });
 
     it('should render the iframe with the correct src URL', () => {
-      render(<MapView {...defaultProps} />);
+      renderWithProviders(<MapView {...defaultProps} />);
 
       // Use getByTitle to access the iframe
       const iframe = screen.getByTitle('Map view');

src/components/PasswordInput.test.tsx

@@ -1,8 +1,9 @@
 // src/components/PasswordInput.test.tsx
 import React from 'react';
-import { render, screen, fireEvent } from '@testing-library/react';
+import { screen, fireEvent } from '@testing-library/react';
 import { describe, it, expect, vi } from 'vitest';
 import { PasswordInput } from './PasswordInput';
+import { renderWithProviders } from '../tests/utils/renderWithProviders';
 // Mock the child PasswordStrengthIndicator component to isolate the test (relative to new location)
 vi.mock('./PasswordStrengthIndicator', () => ({
   PasswordStrengthIndicator: ({ password }: { password?: string }) => (
@@ -12,13 +13,13 @@ vi.mock('./PasswordStrengthIndicator', () => ({
 
 describe('PasswordInput (in auth feature)', () => {
   it('should render as a password input by default', () => {
-    render(<PasswordInput placeholder="Enter password" />);
+    renderWithProviders(<PasswordInput placeholder="Enter password" />);
     const input = screen.getByPlaceholderText('Enter password');
     expect(input).toHaveAttribute('type', 'password');
   });
 
   it('should toggle input type between password and text when the eye icon is clicked', () => {
-    render(<PasswordInput placeholder="Enter password" />);
+    renderWithProviders(<PasswordInput placeholder="Enter password" />);
     const input = screen.getByPlaceholderText('Enter password');
     const toggleButton = screen.getByRole('button', { name: /show password/i });
 
@@ -38,7 +39,7 @@ describe('PasswordInput (in auth feature)', () => {
 
   it('should pass through standard input attributes', () => {
     const handleChange = vi.fn();
-    render(
+    renderWithProviders(
       <PasswordInput
         value="test"
         onChange={handleChange}
@@ -56,38 +57,38 @@ describe('PasswordInput (in auth feature)', () => {
   });
 
   it('should not show strength indicator by default', () => {
-    render(<PasswordInput value="some-password" onChange={() => {}} />);
+    renderWithProviders(<PasswordInput value="some-password" onChange={() => {}} />);
     expect(screen.queryByTestId('strength-indicator')).not.toBeInTheDocument();
   });
 
   it('should show strength indicator when showStrength is true and there is a value', () => {
-    render(<PasswordInput value="some-password" showStrength onChange={() => {}} />);
+    renderWithProviders(<PasswordInput value="some-password" showStrength onChange={() => {}} />);
     const indicator = screen.getByTestId('strength-indicator');
     expect(indicator).toBeInTheDocument();
     expect(indicator).toHaveTextContent('Strength for: some-password');
   });
 
   it('should not show strength indicator when showStrength is true but value is empty', () => {
-    render(<PasswordInput value="" showStrength onChange={() => {}} />);
+    renderWithProviders(<PasswordInput value="" showStrength onChange={() => {}} />);
     expect(screen.queryByTestId('strength-indicator')).not.toBeInTheDocument();
   });
 
   it('should handle undefined className gracefully', () => {
-    render(<PasswordInput placeholder="No class" />);
+    renderWithProviders(<PasswordInput placeholder="No class" />);
     const input = screen.getByPlaceholderText('No class');
     expect(input.className).not.toContain('undefined');
     expect(input.className).toContain('block w-full');
   });
 
   it('should not show strength indicator if value is undefined', () => {
-    render(<PasswordInput showStrength onChange={() => {}} />);
+    renderWithProviders(<PasswordInput showStrength onChange={() => {}} />);
     expect(screen.queryByTestId('strength-indicator')).not.toBeInTheDocument();
   });
 
   it('should not show strength indicator if value is not a string', () => {
     // Force a non-string value to test the typeof check
     const props = { value: 12345, showStrength: true, onChange: () => {} } as any;
-    render(<PasswordInput {...props} />);
+    renderWithProviders(<PasswordInput {...props} />);
     expect(screen.queryByTestId('strength-indicator')).not.toBeInTheDocument();
   });
 });

src/components/PasswordStrengthIndicator.test.tsx

@@ -1,8 +1,9 @@
 // src/pages/admin/components/PasswordStrengthIndicator.test.tsx
 import React from 'react';
-import { render, screen } from '@testing-library/react';
+import { screen } from '@testing-library/react';
 import { describe, it, expect, vi, type Mock } from 'vitest';
 import { PasswordStrengthIndicator } from './PasswordStrengthIndicator';
+import { renderWithProviders } from '../tests/utils/renderWithProviders';
 import zxcvbn from 'zxcvbn';
 
 // Mock the zxcvbn library to control its output for testing
@@ -11,7 +12,7 @@ vi.mock('zxcvbn');
 describe('PasswordStrengthIndicator', () => {
   it('should render 5 gray bars when no password is provided', () => {
     (zxcvbn as Mock).mockReturnValue({ score: -1, feedback: { warning: '', suggestions: [] } });
-    const { container } = render(<PasswordStrengthIndicator password="" />);
+    const { container } = renderWithProviders(<PasswordStrengthIndicator password="" />);
     const bars = container.querySelectorAll('.h-1\\.5');
     expect(bars).toHaveLength(5);
     bars.forEach((bar) => {
@@ -28,7 +29,7 @@ describe('PasswordStrengthIndicator', () => {
     { score: 4, label: 'Strong', color: 'bg-green-500', bars: 5 },
   ])('should render correctly for score $score ($label)', ({ score, label, color, bars }) => {
     (zxcvbn as Mock).mockReturnValue({ score, feedback: { warning: '', suggestions: [] } });
-    const { container } = render(<PasswordStrengthIndicator password="some-password" />);
+    const { container } = renderWithProviders(<PasswordStrengthIndicator password="some-password" />);
 
     // Check the label
     expect(screen.getByText(label)).toBeInTheDocument();
@@ -54,7 +55,7 @@ describe('PasswordStrengthIndicator', () => {
         suggestions: [],
       },
     });
-    render(<PasswordStrengthIndicator password="password" />);
+    renderWithProviders(<PasswordStrengthIndicator password="password" />);
     expect(screen.getByText(/this is a very common password/i)).toBeInTheDocument();
   });
 
@@ -66,7 +67,7 @@ describe('PasswordStrengthIndicator', () => {
         suggestions: ['Add another word or two'],
       },
     });
-    render(<PasswordStrengthIndicator password="pass" />);
+    renderWithProviders(<PasswordStrengthIndicator password="pass" />);
     expect(screen.getByText(/add another word or two/i)).toBeInTheDocument();
   });
 
@@ -75,14 +76,14 @@ describe('PasswordStrengthIndicator', () => {
       score: 1,
       feedback: { warning: 'A warning here', suggestions: ['A suggestion here'] },
     });
-    render(<PasswordStrengthIndicator password="password" />);
+    renderWithProviders(<PasswordStrengthIndicator password="password" />);
     expect(screen.getByText(/a warning here/i)).toBeInTheDocument();
     expect(screen.queryByText(/a suggestion here/i)).not.toBeInTheDocument();
   });
 
   it('should use default empty string if password prop is undefined', () => {
     (zxcvbn as Mock).mockReturnValue({ score: 0, feedback: { warning: '', suggestions: [] } });
-    const { container } = render(<PasswordStrengthIndicator />);
+    const { container } = renderWithProviders(<PasswordStrengthIndicator />);
     const bars = container.querySelectorAll('.h-1\\.5');
     expect(bars).toHaveLength(5);
     bars.forEach((bar) => {
@@ -94,7 +95,7 @@ describe('PasswordStrengthIndicator', () => {
   it('should handle out-of-range scores gracefully (defensive)', () => {
     // Mock a score that isn't 0-4 to hit default switch cases
     (zxcvbn as Mock).mockReturnValue({ score: 99, feedback: { warning: '', suggestions: [] } });
-    const { container } = render(<PasswordStrengthIndicator password="test" />);
+    const { container } = renderWithProviders(<PasswordStrengthIndicator password="test" />);
 
     // Check bars - should hit default case in getBarColor which returns gray
     const bars = container.querySelectorAll('.h-1\\.5');

src/components/RecipeSuggester.test.tsx

@@ -0,0 +1,156 @@
+// src/components/RecipeSuggester.test.tsx
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { screen, waitFor } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import { RecipeSuggester } from './RecipeSuggester'; // This should be after mocks
+import * as apiClient from '../services/apiClient';
+import { logger } from '../services/logger.client';
+import { renderWithProviders } from '../tests/utils/renderWithProviders';
+import '@testing-library/jest-dom';
+
+// The apiClient is mocked globally in `src/tests/setup/globalApiMock.ts`.
+// We can get a typed reference to it for individual test overrides.
+const mockedApiClient = vi.mocked(apiClient);
+
+describe('RecipeSuggester Component', () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    // Reset console logs if needed, or just keep them for debug visibility
+  });
+
+  it('renders correctly with initial state', () => {
+    console.log('TEST: Verifying initial render state');
+    renderWithProviders(<RecipeSuggester />);
+
+    expect(screen.getByText('Get a Recipe Suggestion')).toBeInTheDocument();
+    expect(screen.getByLabelText(/Ingredients:/i)).toBeInTheDocument();
+    expect(screen.getByRole('button', { name: /Suggest a Recipe/i })).toBeInTheDocument();
+    expect(screen.queryByText('Getting suggestion...')).not.toBeInTheDocument();
+  });
+
+  it('shows validation error if no ingredients are entered', async () => {
+    console.log('TEST: Verifying validation for empty input');
+    const user = userEvent.setup();
+    renderWithProviders(<RecipeSuggester />);
+
+    const button = screen.getByRole('button', { name: /Suggest a Recipe/i });
+    await user.click(button);
+
+    expect(await screen.findByText('Please enter at least one ingredient.')).toBeInTheDocument();
+    expect(mockedApiClient.suggestRecipe).not.toHaveBeenCalled();
+    console.log('TEST: Validation error displayed correctly');
+  });
+
+  it('calls suggestRecipe and displays suggestion on success', async () => {
+    console.log('TEST: Verifying successful recipe suggestion flow');
+    const user = userEvent.setup();
+    renderWithProviders(<RecipeSuggester />);
+
+    const input = screen.getByLabelText(/Ingredients:/i);
+    await user.type(input, 'chicken, rice');
+
+    // Mock successful API response
+    const mockSuggestion = 'Here is a nice Chicken and Rice recipe...';
+    // Add a delay to ensure the loading state is visible during the test
+    mockedApiClient.suggestRecipe.mockImplementation(async () => {
+      await new Promise((resolve) => setTimeout(resolve, 50));
+      return { ok: true, json: async () => ({ suggestion: mockSuggestion }) } as Response;
+    });
+
+    const button = screen.getByRole('button', { name: /Suggest a Recipe/i });
+    await user.click(button);
+
+    // Check loading state
+    expect(screen.getByRole('button')).toBeDisabled();
+    expect(screen.getByText('Getting suggestion...')).toBeInTheDocument();
+
+    await waitFor(() => {
+      expect(screen.getByText(mockSuggestion)).toBeInTheDocument();
+    });
+
+    expect(mockedApiClient.suggestRecipe).toHaveBeenCalledWith(['chicken', 'rice']);
+    console.log('TEST: Suggestion displayed and API called with correct args');
+  });
+
+  it('handles API errors (non-200 response) gracefully', async () => {
+    console.log('TEST: Verifying API error handling (400/500 responses)');
+    const user = userEvent.setup();
+    renderWithProviders(<RecipeSuggester />);
+
+    const input = screen.getByLabelText(/Ingredients:/i);
+    await user.type(input, 'rocks');
+
+    // Mock API failure response
+    const errorMessage = 'Invalid ingredients provided.';
+    mockedApiClient.suggestRecipe.mockResolvedValue({
+      ok: false,
+      json: async () => ({ message: errorMessage }),
+    } as Response);
+
+    const button = screen.getByRole('button', { name: /Suggest a Recipe/i });
+    await user.click(button);
+
+    await waitFor(() => {
+      expect(screen.getByText(errorMessage)).toBeInTheDocument();
+    });
+
+    // Ensure loading state is reset
+    expect(screen.getByRole('button', { name: /Suggest a Recipe/i })).toBeEnabled();
+    console.log('TEST: API error message displayed to user');
+  });
+
+  it('handles network exceptions and logs them', async () => {
+    console.log('TEST: Verifying network exception handling');
+    const user = userEvent.setup();
+    renderWithProviders(<RecipeSuggester />);
+
+    const input = screen.getByLabelText(/Ingredients:/i);
+    await user.type(input, 'beef');
+
+    // Mock network error
+    const networkError = new Error('Network Error');
+    mockedApiClient.suggestRecipe.mockRejectedValue(networkError);
+
+    const button = screen.getByRole('button', { name: /Suggest a Recipe/i });
+    await user.click(button);
+
+    await waitFor(() => {
+      expect(screen.getByText('Network Error')).toBeInTheDocument();
+    });
+
+    expect(logger.error).toHaveBeenCalledWith(
+      { error: networkError },
+      'Failed to fetch recipe suggestion.'
+    );
+    console.log('TEST: Network error caught and logged');
+  });
+
+  it('clears previous errors when submitting again', async () => {
+    console.log('TEST: Verifying error clearing on re-submit');
+    const user = userEvent.setup();
+    renderWithProviders(<RecipeSuggester />);
+
+    // Trigger validation error first
+    const button = screen.getByRole('button', { name: /Suggest a Recipe/i });
+    await user.click(button);
+    expect(screen.getByText('Please enter at least one ingredient.')).toBeInTheDocument();
+
+    // Now type something to clear it (state change doesn't clear it, submit does)
+    const input = screen.getByLabelText(/Ingredients:/i);
+    await user.type(input, 'tofu');
+
+    // Mock success for the second click
+    mockedApiClient.suggestRecipe.mockResolvedValue({
+      ok: true,
+      json: async () => ({ suggestion: 'Tofu Stir Fry' }),
+    } as Response);
+
+    await user.click(button);
+
+    await waitFor(() => {
+      expect(screen.queryByText('Please enter at least one ingredient.')).not.toBeInTheDocument();
+      expect(screen.getByText('Tofu Stir Fry')).toBeInTheDocument();
+    });
+    console.log('TEST: Previous error cleared successfully');
+  });
+});

src/components/RecipeSuggester.tsx

@@ -0,0 +1,80 @@
+// src/components/RecipeSuggester.tsx
+import React, { useState, useCallback } from 'react';
+import { suggestRecipe } from '../services/apiClient';
+import { logger } from '../services/logger.client';
+
+export const RecipeSuggester: React.FC = () => {
+  const [ingredients, setIngredients] = useState<string>('');
+  const [suggestion, setSuggestion] = useState<string | null>(null);
+  const [isLoading, setIsLoading] = useState<boolean>(false);
+  const [error, setError] = useState<string | null>(null);
+
+  const handleSubmit = useCallback(async (event: React.FormEvent<HTMLFormElement>) => {
+    event.preventDefault();
+    setIsLoading(true);
+    setError(null);
+    setSuggestion(null);
+
+    const ingredientList = ingredients.split(',').map(item => item.trim()).filter(Boolean);
+
+    if (ingredientList.length === 0) {
+      setError('Please enter at least one ingredient.');
+      setIsLoading(false);
+      return;
+    }
+
+    try {
+      const response = await suggestRecipe(ingredientList);
+      const data = await response.json();
+
+      if (!response.ok) {
+        throw new Error(data.message || 'Failed to get suggestion.');
+      }
+
+      setSuggestion(data.suggestion);
+    } catch (err) {
+      const errorMessage = err instanceof Error ? err.message : 'An unknown error occurred.';
+      logger.error({ error: err }, 'Failed to fetch recipe suggestion.');
+      setError(errorMessage);
+    } finally {
+      setIsLoading(false);
+    }
+  }, [ingredients]);
+
+  return (
+    <div className="bg-white dark:bg-gray-800 shadow rounded-lg p-6">
+      <h2 className="text-xl font-semibold text-gray-900 dark:text-white mb-2">Get a Recipe Suggestion</h2>
+      <p className="text-gray-600 dark:text-gray-400 mb-4">Enter some ingredients you have, separated by commas.</p>
+      <form onSubmit={handleSubmit}>
+        <div className="mb-4">
+          <label htmlFor="ingredients-input" className="block text-sm font-medium text-gray-700 dark:text-gray-300 mb-1">Ingredients:</label>
+          <input
+            id="ingredients-input"
+            type="text"
+            value={ingredients}
+            onChange={(e) => setIngredients(e.target.value)}
+            placeholder="e.g., chicken, rice, broccoli"
+            disabled={isLoading}
+            className="block w-full rounded-md border-gray-300 shadow-sm focus:border-blue-500 focus:ring-blue-500 dark:bg-gray-700 dark:border-gray-600 dark:text-white sm:text-sm p-2 border"
+          />
+        </div>
+        <button type="submit" disabled={isLoading} className="w-full flex justify-center py-2 px-4 border border-transparent rounded-md shadow-sm text-sm font-medium text-white bg-blue-600 hover:bg-blue-700 focus:outline-none focus:ring-2 focus:ring-offset-2 focus:ring-blue-500 disabled:opacity-50 transition-colors">
+          {isLoading ? 'Getting suggestion...' : 'Suggest a Recipe'}
+        </button>
+      </form>
+
+      {error && (
+        <div className="mt-4 p-4 bg-red-50 dark:bg-red-900/50 text-red-700 dark:text-red-200 rounded-md text-sm">{error}</div>
+      )}
+
+      {suggestion && (
+        <div className="mt-6 bg-gray-50 dark:bg-gray-700/50 rounded-lg p-4 border border-gray-200 dark:border-gray-600">
+          <div className="prose dark:prose-invert max-w-none">
+            <h5 className="text-lg font-medium text-gray-900 dark:text-white mb-2">Recipe Suggestion</h5>
+            <p className="text-gray-700 dark:text-gray-300 whitespace-pre-wrap">{suggestion}</p>
+          </div>
+        </div>
+      )}
+    </div>
+  );
+};

src/components/StatCard.test.tsx

@@ -0,0 +1,34 @@
+// src/components/StatCard.test.tsx
+import React from 'react';
+import { screen } from '@testing-library/react';
+import { describe, it, expect } from 'vitest';
+import { StatCard } from './StatCard';
+import { renderWithProviders } from '../tests/utils/renderWithProviders';
+import '@testing-library/jest-dom';
+
+describe('StatCard', () => {
+  it('renders title and value correctly', () => {
+    renderWithProviders(
+      <StatCard
+        title="Total Users"
+        value="1,234"
+        icon={<div data-testid="mock-icon">Icon</div>}
+      />,
+    );
+
+    expect(screen.getByText('Total Users')).toBeInTheDocument();
+    expect(screen.getByText('1,234')).toBeInTheDocument();
+  });
+
+  it('renders the icon', () => {
+    renderWithProviders(
+      <StatCard
+        title="Total Users"
+        value="1,234"
+        icon={<div data-testid="mock-icon">Icon</div>}
+      />,
+    );
+
+    expect(screen.getByTestId('mock-icon')).toBeInTheDocument();
+  });
+});

src/components/StatCard.tsx

@@ -0,0 +1,32 @@
+// src/components/StatCard.tsx
+import React, { ReactNode } from 'react';
+
+interface StatCardProps {
+  title: string;
+  value: string;
+  icon: ReactNode;
+}
+
+export const StatCard: React.FC<StatCardProps> = ({ title, value, icon }) => {
+  return (
+    <div className="bg-white dark:bg-gray-800 overflow-hidden shadow rounded-lg">
+      <div className="p-5">
+        <div className="flex items-center">
+          <div className="flex-shrink-0">
+            <div className="flex items-center justify-center h-12 w-12 rounded-md bg-blue-500 text-white">
+              {icon}
+            </div>
+          </div>
+          <div className="ml-5 w-0 flex-1">
+            <dl>
+              <dt className="text-sm font-medium text-gray-500 dark:text-gray-400 truncate">{title}</dt>
+              <dd>
+                <div className="text-lg font-medium text-gray-900 dark:text-white">{value}</div>
+              </dd>
+            </dl>
+          </div>
+        </div>
+      </div>
+    </div>
+  );
+};

src/components/UnitSystemToggle.test.tsx

@@ -1,8 +1,9 @@
 // src/components/UnitSystemToggle.test.tsx
 import React from 'react';
-import { render, screen, fireEvent } from '@testing-library/react';
+import { screen, fireEvent } from '@testing-library/react';
 import { describe, it, expect, vi, beforeEach } from 'vitest';
 import { UnitSystemToggle } from './UnitSystemToggle';
+import { renderWithProviders } from '../tests/utils/renderWithProviders';
 
 describe('UnitSystemToggle', () => {
   const mockOnToggle = vi.fn();
@@ -12,7 +13,7 @@ describe('UnitSystemToggle', () => {
   });
 
   it('should render correctly for imperial system', () => {
-    render(<UnitSystemToggle currentSystem="imperial" onToggle={mockOnToggle} />);
+    renderWithProviders(<UnitSystemToggle currentSystem="imperial" onToggle={mockOnToggle} />);
 
     const checkbox = screen.getByRole('checkbox');
     expect(checkbox).toBeChecked();
@@ -23,7 +24,7 @@ describe('UnitSystemToggle', () => {
   });
 
   it('should render correctly for metric system', () => {
-    render(<UnitSystemToggle currentSystem="metric" onToggle={mockOnToggle} />);
+    renderWithProviders(<UnitSystemToggle currentSystem="metric" onToggle={mockOnToggle} />);
 
     const checkbox = screen.getByRole('checkbox');
     expect(checkbox).not.toBeChecked();
@@ -34,7 +35,7 @@ describe('UnitSystemToggle', () => {
   });
 
   it('should call onToggle when the toggle is clicked', () => {
-    render(<UnitSystemToggle currentSystem="metric" onToggle={mockOnToggle} />);
+    renderWithProviders(<UnitSystemToggle currentSystem="metric" onToggle={mockOnToggle} />);
     fireEvent.click(screen.getByRole('checkbox'));
     expect(mockOnToggle).toHaveBeenCalledTimes(1);
   });

src/components/UserMenuSkeleton.test.tsx

@@ -1,34 +1,34 @@
 // src/components/UserMenuSkeleton.test.tsx
 import React from 'react';
-import { render } from '@testing-library/react';
 import { describe, it, expect } from 'vitest';
 import { UserMenuSkeleton } from './UserMenuSkeleton';
+import { renderWithProviders } from '../tests/utils/renderWithProviders';
 
 describe('UserMenuSkeleton', () => {
   it('should render without crashing', () => {
-    const { container } = render(<UserMenuSkeleton />);
+    const { container } = renderWithProviders(<UserMenuSkeleton />);
     expect(container.firstChild).toBeInTheDocument();
   });
 
   it('should have the main container with pulse animation', () => {
-    const { container } = render(<UserMenuSkeleton />);
+    const { container } = renderWithProviders(<UserMenuSkeleton />);
     expect(container.firstChild).toHaveClass('animate-pulse');
   });
 
   it('should render two child placeholder elements', () => {
-    const { container } = render(<UserMenuSkeleton />);
+    const { container } = renderWithProviders(<UserMenuSkeleton />);
     expect(container.firstChild?.childNodes.length).toBe(2);
   });
 
   it('should render a rectangular placeholder with correct styles', () => {
-    const { container } = render(<UserMenuSkeleton />);
+    const { container } = renderWithProviders(<UserMenuSkeleton />);
     expect(container.querySelector('.rounded-md')).toHaveClass(
       'h-8 w-24 bg-gray-200 dark:bg-gray-700',
     );
   });
 
   it('should render a circular placeholder with correct styles', () => {
-    const { container } = render(<UserMenuSkeleton />);
+    const { container } = renderWithProviders(<UserMenuSkeleton />);
     expect(container.querySelector('.rounded-full')).toHaveClass(
       'h-10 w-10 bg-gray-200 dark:bg-gray-700',
     );

src/components/WhatsNewModal.test.tsx

@@ -1,8 +1,9 @@
 // src/components/WhatsNewModal.test.tsx
 import React from 'react';
-import { render, screen, fireEvent } from '@testing-library/react';
+import { screen, fireEvent } from '@testing-library/react';
 import { describe, it, expect, vi, beforeEach } from 'vitest';
 import { WhatsNewModal } from './WhatsNewModal';
+import { renderWithProviders } from '../tests/utils/renderWithProviders';
 
 // Unmock the component to test the real implementation
 vi.unmock('./WhatsNewModal');
@@ -21,13 +22,13 @@ describe('WhatsNewModal', () => {
   });
 
   it('should not render when isOpen is false', () => {
-    const { container } = render(<WhatsNewModal {...defaultProps} isOpen={false} />);
+    const { container } = renderWithProviders(<WhatsNewModal {...defaultProps} isOpen={false} />);
     // The component returns null, so the container should be empty.
     expect(container.firstChild).toBeNull();
   });
 
   it('should render correctly when isOpen is true', () => {
-    render(<WhatsNewModal {...defaultProps} />);
+    renderWithProviders(<WhatsNewModal {...defaultProps} />);
 
     expect(screen.getByRole('heading', { name: /what's new/i })).toBeInTheDocument();
     expect(screen.getByText(`Version: ${defaultProps.version}`)).toBeInTheDocument();
@@ -36,13 +37,13 @@ describe('WhatsNewModal', () => {
   });
 
   it('should call onClose when the "Got it!" button is clicked', () => {
-    render(<WhatsNewModal {...defaultProps} />);
+    renderWithProviders(<WhatsNewModal {...defaultProps} />);
     fireEvent.click(screen.getByRole('button', { name: /got it/i }));
     expect(mockOnClose).toHaveBeenCalledTimes(1);
   });
 
   it('should call onClose when the close icon button is clicked', () => {
-    render(<WhatsNewModal {...defaultProps} />);
+    renderWithProviders(<WhatsNewModal {...defaultProps} />);
     // The close button is an SVG icon inside a button, best queried by its aria-label.
     const closeButton = screen.getByRole('button', { name: /close/i });
     fireEvent.click(closeButton);
@@ -50,7 +51,7 @@ describe('WhatsNewModal', () => {
   });
 
   it('should call onClose when clicking on the overlay', () => {
-    render(<WhatsNewModal {...defaultProps} />);
+    renderWithProviders(<WhatsNewModal {...defaultProps} />);
     // The overlay is the root div with the background color.
     const overlay = screen.getByRole('dialog').parentElement;
     fireEvent.click(overlay!);
@@ -58,7 +59,7 @@ describe('WhatsNewModal', () => {
   });
 
   it('should not call onClose when clicking inside the modal content', () => {
-    render(<WhatsNewModal {...defaultProps} />);
+    renderWithProviders(<WhatsNewModal {...defaultProps} />);
     fireEvent.click(screen.getByText(defaultProps.commitMessage));
     expect(mockOnClose).not.toHaveBeenCalled();
   });

src/db/seed.ts

@@ -111,7 +111,7 @@ async function main() {
 
     const flyerQuery = `
         INSERT INTO public.flyers (file_name, image_url, checksum, store_id, valid_from, valid_to)
-        VALUES ('safeway-flyer.jpg', '/sample-assets/safeway-flyer.jpg', 'sample-checksum-123', ${storeMap.get('Safeway')}, $1, $2)
+        VALUES ('safeway-flyer.jpg', 'https://example.com/flyer-images/safeway-flyer.jpg', 'a0a0a0a0a0a0a0a0a0a0a0a0a0a0a0a0a0a0a0a0a0a0a0a0a0a0a0a0a0a0a0a0', ${storeMap.get('Safeway')}, $1, $2)
         RETURNING flyer_id;
     `;
     const flyerRes = await client.query<{ flyer_id: number }>(flyerQuery, [

src/hooks/useActiveDeals.test.tsx

@@ -12,12 +12,7 @@ import {
 } from '../tests/utils/mockFactories';
 import { mockUseFlyers, mockUseUserData } from '../tests/setup/mockHooks';
 
-// Explicitly mock apiClient to ensure stable spies are used
-vi.mock('../services/apiClient', () => ({
-  countFlyerItemsForFlyers: vi.fn(),
-  fetchFlyerItemsForFlyers: vi.fn(),
-}));
-
+// The apiClient is mocked globally in `src/tests/setup/globalApiMock.ts`.
 // Mock the hooks to avoid Missing Context errors
 vi.mock('./useFlyers', () => ({
   useFlyers: () => mockUseFlyers(),
@@ -30,14 +25,6 @@ vi.mock('../hooks/useUserData', () => ({
 // The apiClient is globally mocked in our test setup, so we just need to cast it
 const mockedApiClient = vi.mocked(apiClient);
 
-// Mock the logger to prevent console noise
-vi.mock('../services/logger.client', () => ({
-  logger: {
-    error: vi.fn(),
-    info: vi.fn(), // Added to prevent crashes on abort logging
-  },
-}));
-
 // Set a consistent "today" for testing flyer validity to make tests deterministic
 const TODAY = new Date('2024-01-15T12:00:00.000Z');
 

src/hooks/useAuth.test.tsx

@@ -11,21 +11,9 @@ import { createMockUserProfile } from '../tests/utils/mockFactories';
 import { logger } from '../services/logger.client';
 
 // Mock the dependencies
-vi.mock('../services/apiClient', () => ({
-  // Mock other functions if needed
-  getAuthenticatedUserProfile: vi.fn(),
-}));
+// The apiClient is mocked globally in `src/tests/setup/globalApiMock.ts`.
 vi.mock('../services/tokenStorage');
 
-// Mock the logger to spy on its methods
-vi.mock('../services/logger.client', () => ({
-  logger: {
-    info: vi.fn(),
-    warn: vi.fn(),
-    error: vi.fn(),
-  },
-}));
-
 const mockedApiClient = vi.mocked(apiClient);
 const mockedTokenStorage = vi.mocked(tokenStorage);
 

src/hooks/useFlyerItems.test.ts

@@ -3,12 +3,11 @@ import { renderHook } from '@testing-library/react';
 import { describe, it, expect, vi, beforeEach } from 'vitest';
 import { useFlyerItems } from './useFlyerItems';
 import { useApiOnMount } from './useApiOnMount';
-import { createMockFlyer, createMockFlyerItem } from '../tests/utils/mockFactories';
 import * as apiClient from '../services/apiClient';
+import { createMockFlyer, createMockFlyerItem } from '../tests/utils/mockFactories';
 
 // Mock the underlying useApiOnMount hook to isolate the useFlyerItems hook's logic.
 vi.mock('./useApiOnMount');
-vi.mock('../services/apiClient');
 
 const mockedUseApiOnMount = vi.mocked(useApiOnMount);
 
@@ -61,7 +60,6 @@ describe('useFlyerItems Hook', () => {
     expect(result.current.flyerItems).toEqual([]);
     expect(result.current.isLoading).toBe(false);
     expect(result.current.error).toBeNull();
-
     // Assert: Check that useApiOnMount was called with `enabled: false`.
     expect(mockedUseApiOnMount).toHaveBeenCalledWith(
       expect.any(Function), // the wrapped fetcher function
@@ -171,11 +169,11 @@ describe('useFlyerItems Hook', () => {
 
       const wrappedFetcher = mockedUseApiOnMount.mock.calls[0][0];
       const mockResponse = new Response();
-      vi.mocked(apiClient.fetchFlyerItems).mockResolvedValue(mockResponse);
-
+      const mockedApiClient = vi.mocked(apiClient);
+      mockedApiClient.fetchFlyerItems.mockResolvedValue(mockResponse);
       const response = await wrappedFetcher(123);
 
-      expect(apiClient.fetchFlyerItems).toHaveBeenCalledWith(123);
+      expect(mockedApiClient.fetchFlyerItems).toHaveBeenCalledWith(123);
       expect(response).toBe(mockResponse);
     });
   });

src/hooks/useShoppingLists.test.tsx

@@ -29,7 +29,6 @@ type MockApiResult = {
 vi.mock('./useApi');
 vi.mock('../hooks/useAuth');
 vi.mock('../hooks/useUserData');
-vi.mock('../services/apiClient');
 
 // The apiClient is globally mocked in our test setup, so we just need to cast it
 const mockedUseApi = vi.mocked(useApi);

src/hooks/useWatchedItems.test.tsx

@@ -17,7 +17,6 @@ import {
 vi.mock('./useApi');
 vi.mock('../hooks/useAuth');
 vi.mock('../hooks/useUserData');
-vi.mock('../services/apiClient');
 
 // The apiClient is globally mocked in our test setup, so we just need to cast it
 const mockedUseApi = vi.mocked(useApi);

src/pages/MyDealsPage.test.tsx

@@ -1,25 +1,15 @@
-// src/components/MyDealsPage.test.tsx
+// src/pages/MyDealsPage.test.tsx
 import React from 'react';
 import { render, screen, waitFor } from '@testing-library/react';
 import { describe, it, expect, vi, beforeEach, type Mocked } from 'vitest';
 import MyDealsPage from './MyDealsPage';
 import * as apiClient from '../services/apiClient';
-import { WatchedItemDeal } from '../types';
+import type { WatchedItemDeal } from '../types';
 import { logger } from '../services/logger.client';
 import { createMockWatchedItemDeal } from '../tests/utils/mockFactories';
 
-// Mock the apiClient. The component now directly uses `fetchBestSalePrices`.
-// By mocking the entire module, we can control the behavior of `fetchBestSalePrices`
-// for our tests.
-vi.mock('../services/apiClient');
-const mockedApiClient = apiClient as Mocked<typeof apiClient>;
-
-// Mock the logger
-vi.mock('../services/logger.client', () => ({
-  logger: {
-    error: vi.fn(),
-  },
-}));
+// The apiClient is mocked globally in `src/tests/setup/globalApiMock.ts`.
+const mockedApiClient = vi.mocked(apiClient);
 
 // Mock lucide-react icons to prevent rendering errors in the test environment
 vi.mock('lucide-react', () => ({

src/pages/ResetPasswordPage.test.tsx

@@ -10,13 +10,7 @@ import { logger } from '../services/logger.client';
 // The apiClient and logger are now mocked globally.
 const mockedApiClient = vi.mocked(apiClient);
 
-vi.mock('../services/logger.client', () => ({
-  logger: {
-    info: vi.fn(),
-    error: vi.fn(),
-  },
-}));
-
+// The logger is mocked globally.
 // Helper function to render the component within a router context
 const renderWithRouter = (token: string) => {
   return render(

src/pages/UserProfilePage.test.tsx

@@ -11,16 +11,8 @@ import {
   createMockUser,
 } from '../tests/utils/mockFactories';
 
-// Mock dependencies
-vi.mock('../services/apiClient'); // This was correct
-vi.mock('../services/logger.client', () => ({
-  logger: {
-    info: vi.fn(),
-    error: vi.fn(),
-  },
-}));
-vi.mock('../services/notificationService');
-vi.mock('../services/aiApiClient'); // Mock aiApiClient as it's used in the component
+// The apiClient, logger, notificationService, and aiApiClient are all mocked globally.
+// We can get a typed reference to the notificationService for individual test overrides.
 const mockedNotificationService = vi.mocked(await import('../services/notificationService'));
 vi.mock('../components/AchievementsList', () => ({
   AchievementsList: ({ achievements }: { achievements: (UserAchievement & Achievement)[] }) => (
@@ -28,7 +20,7 @@ vi.mock('../components/AchievementsList', () => ({
   ),
 }));
 
-const mockedApiClient = apiClient as Mocked<typeof apiClient>;
+const mockedApiClient = vi.mocked(apiClient);
 
 // --- Mock Data ---
 const mockProfile: UserProfile = createMockUserProfile({

src/pages/VoiceLabPage.test.tsx

@@ -10,21 +10,10 @@ import { logger } from '../services/logger.client';
 // Extensive logging for debugging
 const LOG_PREFIX = '[TEST DEBUG]';
 
-vi.mock('../services/notificationService');
-
-// 1. Mock the module to replace its exports with mock functions.
-vi.mock('../services/aiApiClient');
-// 2. Get a typed reference to the mocked module to control its functions in tests.
+// The aiApiClient, notificationService, and logger are mocked globally.
+// We can get a typed reference to the aiApiClient for individual test overrides.
 const mockedAiApiClient = vi.mocked(aiApiClient);
 
-// Mock the logger
-vi.mock('../services/logger.client', () => ({
-  logger: {
-    info: vi.fn(),
-    error: vi.fn(),
-  },
-}));
-
 // Define mock at module level so it can be referenced in the implementation
 const mockAudioPlay = vi.fn(() => {
   console.log(`${LOG_PREFIX} mockAudioPlay executed`);

src/pages/admin/AdminStatsPage.test.tsx

@@ -7,13 +7,13 @@ import { AdminStatsPage } from './AdminStatsPage';
 import * as apiClient from '../../services/apiClient';
 import type { AppStats } from '../../services/apiClient';
 import { createMockAppStats } from '../../tests/utils/mockFactories';
-import { StatCard } from './components/StatCard';
+import { StatCard } from '../../components/StatCard';
 
 // The apiClient and logger are now mocked globally via src/tests/setup/tests-setup-unit.ts.
 const mockedApiClient = vi.mocked(apiClient);
 
 // Mock the child StatCard component to use the shared mock and allow spying
-vi.mock('./components/StatCard', async () => {
+vi.mock('../../components/StatCard', async () => {
   const { MockStatCard } = await import('../../tests/utils/componentMocks');
   return { StatCard: vi.fn(MockStatCard) };
 });

src/pages/admin/AdminStatsPage.tsx

@@ -10,7 +10,7 @@ import { DocumentDuplicateIcon } from '../../components/icons/DocumentDuplicateI
 import { BuildingStorefrontIcon } from '../../components/icons/BuildingStorefrontIcon';
 import { BellAlertIcon } from '../../components/icons/BellAlertIcon';
 import { BookOpenIcon } from '../../components/icons/BookOpenIcon';
-import { StatCard } from './components/StatCard';
+import { StatCard } from '../../components/StatCard';
 
 export const AdminStatsPage: React.FC = () => {
   const [stats, setStats] = useState<AppStats | null>(null);

src/pages/admin/FlyerReviewPage.test.tsx

@@ -6,16 +6,9 @@ import { MemoryRouter } from 'react-router-dom';
 import * as apiClient from '../../services/apiClient';
 import { logger } from '../../services/logger.client';
 
-// Mock dependencies
-vi.mock('../../services/apiClient', () => ({
-  getFlyersForReview: vi.fn(),
-}));
-
-vi.mock('../../services/logger.client', () => ({
-  logger: {
-    error: vi.fn(),
-  },
-}));
+// The apiClient and logger are mocked globally.
+// We can get a typed reference to the apiClient for individual test overrides.
+const mockedApiClient = vi.mocked(apiClient);
 
 // Mock LoadingSpinner to simplify DOM and avoid potential issues
 vi.mock('../../components/LoadingSpinner', () => ({
@@ -29,7 +22,7 @@ describe('FlyerReviewPage', () => {
 
   it('renders loading spinner initially', () => {
     // Mock a promise that doesn't resolve immediately to check loading state
-    vi.mocked(apiClient.getFlyersForReview).mockReturnValue(new Promise(() => {}));
+    mockedApiClient.getFlyersForReview.mockReturnValue(new Promise(() => {}));
 
     render(
       <MemoryRouter>
@@ -41,7 +34,7 @@ describe('FlyerReviewPage', () => {
   });
 
   it('renders empty state when no flyers are returned', async () => {
-    vi.mocked(apiClient.getFlyersForReview).mockResolvedValue({
+    mockedApiClient.getFlyersForReview.mockResolvedValue({
       ok: true,
       json: async () => [],
     } as Response);
@@ -84,7 +77,7 @@ describe('FlyerReviewPage', () => {
       },
     ];
 
-    vi.mocked(apiClient.getFlyersForReview).mockResolvedValue({
+    mockedApiClient.getFlyersForReview.mockResolvedValue({
       ok: true,
       json: async () => mockFlyers,
     } as Response);
@@ -114,7 +107,7 @@ describe('FlyerReviewPage', () => {
   });
 
   it('renders error message when API response is not ok', async () => {
-    vi.mocked(apiClient.getFlyersForReview).mockResolvedValue({
+    mockedApiClient.getFlyersForReview.mockResolvedValue({
       ok: false,
       json: async () => ({ message: 'Server error' }),
     } as Response);
@@ -138,7 +131,7 @@ describe('FlyerReviewPage', () => {
 
   it('renders error message when API throws an error', async () => {
     const networkError = new Error('Network error');
-    vi.mocked(apiClient.getFlyersForReview).mockRejectedValue(networkError);
+    mockedApiClient.getFlyersForReview.mockRejectedValue(networkError);
 
     render(
       <MemoryRouter>
@@ -159,7 +152,7 @@ describe('FlyerReviewPage', () => {
 
   it('renders a generic error for non-Error rejections', async () => {
     const nonErrorRejection = { message: 'This is not an Error object' };
-    vi.mocked(apiClient.getFlyersForReview).mockRejectedValue(nonErrorRejection);
+    mockedApiClient.getFlyersForReview.mockRejectedValue(nonErrorRejection);
 
     render(
       <MemoryRouter>

src/pages/admin/components/AddressForm.test.tsx

@@ -1,9 +1,10 @@
 // src/pages/admin/components/AddressForm.test.tsx
 import React from 'react';
-import { render, screen, fireEvent } from '@testing-library/react';
+import { screen, fireEvent } from '@testing-library/react';
 import { describe, it, expect, vi, beforeEach } from 'vitest';
 import { AddressForm } from './AddressForm';
 import { createMockAddress } from '../../../tests/utils/mockFactories';
+import { renderWithProviders } from '../../../tests/utils/renderWithProviders';
 
 // Mock child components and icons to isolate the form's logic
 vi.mock('lucide-react', () => ({
@@ -30,7 +31,7 @@ describe('AddressForm', () => {
   });
 
   it('should render all address fields correctly', () => {
-    render(<AddressForm {...defaultProps} />);
+    renderWithProviders(<AddressForm {...defaultProps} />);
 
     expect(screen.getByRole('heading', { name: /home address/i })).toBeInTheDocument();
     expect(screen.getByLabelText(/address line 1/i)).toBeInTheDocument();
@@ -48,7 +49,7 @@ describe('AddressForm', () => {
       city: 'Anytown',
       country: 'Canada',
     });
-    render(<AddressForm {...defaultProps} address={fullAddress} />);
+    renderWithProviders(<AddressForm {...defaultProps} address={fullAddress} />);
 
     expect(screen.getByLabelText(/address line 1/i)).toHaveValue('123 Main St');
     expect(screen.getByLabelText(/city/i)).toHaveValue('Anytown');
@@ -56,7 +57,7 @@ describe('AddressForm', () => {
   });
 
   it('should call onAddressChange with the correct field and value for all inputs', () => {
-    render(<AddressForm {...defaultProps} />);
+    renderWithProviders(<AddressForm {...defaultProps} />);
 
     const inputs = [
       { label: /address line 1/i, name: 'address_line_1', value: '123 St' },
@@ -75,7 +76,7 @@ describe('AddressForm', () => {
   });
 
   it('should call onGeocode when the "Re-Geocode" button is clicked', () => {
-    render(<AddressForm {...defaultProps} />);
+    renderWithProviders(<AddressForm {...defaultProps} />);
 
     const geocodeButton = screen.getByRole('button', { name: /re-geocode/i });
     fireEvent.click(geocodeButton);
@@ -84,14 +85,14 @@ describe('AddressForm', () => {
   });
 
   it('should show MapPinIcon when not geocoding', () => {
-    render(<AddressForm {...defaultProps} isGeocoding={false} />);
+    renderWithProviders(<AddressForm {...defaultProps} isGeocoding={false} />);
     expect(screen.getByTestId('map-pin-icon')).toBeInTheDocument();
     expect(screen.queryByTestId('loading-spinner')).not.toBeInTheDocument();
   });
 
   describe('when isGeocoding is true', () => {
     it('should disable the button and show a loading spinner', () => {
-      render(<AddressForm {...defaultProps} isGeocoding={true} />);
+      renderWithProviders(<AddressForm {...defaultProps} isGeocoding={true} />);
 
       const geocodeButton = screen.getByRole('button', { name: /re-geocode/i });
       expect(geocodeButton).toBeDisabled();

src/pages/admin/components/AdminBrandManager.test.tsx

@@ -1,11 +1,12 @@
 // src/pages/admin/components/AdminBrandManager.test.tsx
 import React from 'react';
-import { render, screen, fireEvent, waitFor } from '@testing-library/react';
+import { screen, fireEvent, waitFor } from '@testing-library/react';
 import { describe, it, expect, vi, beforeEach } from 'vitest';
 import toast from 'react-hot-toast';
 import { AdminBrandManager } from './AdminBrandManager';
 import * as apiClient from '../../../services/apiClient';
 import { createMockBrand } from '../../../tests/utils/mockFactories';
+import { renderWithProviders } from '../../../tests/utils/renderWithProviders';
 
 // After mocking, we can get a type-safe mocked version of the module.
 // This allows us to use .mockResolvedValue, .mockRejectedValue, etc. on the functions.
@@ -34,7 +35,7 @@ describe('AdminBrandManager', () => {
     mockedApiClient.fetchAllBrands.mockReturnValue(new Promise(() => {}));
 
     console.log('TEST ACTION: Rendering AdminBrandManager component.');
-    render(<AdminBrandManager />);
+    renderWithProviders(<AdminBrandManager />);
 
     console.log('TEST ASSERTION: Checking for the loading text.');
     expect(screen.getByText('Loading brands...')).toBeInTheDocument();
@@ -49,7 +50,7 @@ describe('AdminBrandManager', () => {
     mockedApiClient.fetchAllBrands.mockRejectedValue(new Error('Network Error'));
 
     console.log('TEST ACTION: Rendering AdminBrandManager component.');
-    render(<AdminBrandManager />);
+    renderWithProviders(<AdminBrandManager />);
 
     console.log('TEST ASSERTION: Waiting for error message to be displayed.');
     await waitFor(() => {
@@ -69,7 +70,7 @@ describe('AdminBrandManager', () => {
     );
 
     console.log('TEST ACTION: Rendering AdminBrandManager component.');
-    render(<AdminBrandManager />);
+    renderWithProviders(<AdminBrandManager />);
 
     console.log('TEST ASSERTION: Waiting for brand list to render.');
     await waitFor(() => {
@@ -98,7 +99,7 @@ describe('AdminBrandManager', () => {
     mockedToast.loading.mockReturnValue('toast-1');
 
     console.log('TEST ACTION: Rendering AdminBrandManager component.');
-    render(<AdminBrandManager />);
+    renderWithProviders(<AdminBrandManager />);
     console.log('TEST ACTION: Waiting for initial brands to render.');
     await waitFor(() => expect(screen.getByText('No Frills')).toBeInTheDocument());
 
@@ -135,7 +136,7 @@ describe('AdminBrandManager', () => {
     mockedApiClient.uploadBrandLogo.mockRejectedValue('A string error');
     mockedToast.loading.mockReturnValue('toast-non-error');
 
-    render(<AdminBrandManager />);
+    renderWithProviders(<AdminBrandManager />);
     await waitFor(() => expect(screen.getByText('No Frills')).toBeInTheDocument());
 
     const file = new File(['logo'], 'logo.png', { type: 'image/png' });
@@ -162,7 +163,7 @@ describe('AdminBrandManager', () => {
     mockedToast.loading.mockReturnValue('toast-2');
 
     console.log('TEST ACTION: Rendering AdminBrandManager component.');
-    render(<AdminBrandManager />);
+    renderWithProviders(<AdminBrandManager />);
     console.log('TEST ACTION: Waiting for initial brands to render.');
     await waitFor(() => expect(screen.getByText('No Frills')).toBeInTheDocument());
 
@@ -189,7 +190,7 @@ describe('AdminBrandManager', () => {
       async () => new Response(JSON.stringify(mockBrands), { status: 200 }),
     );
     console.log('TEST ACTION: Rendering AdminBrandManager component.');
-    render(<AdminBrandManager />);
+    renderWithProviders(<AdminBrandManager />);
     console.log('TEST ACTION: Waiting for initial brands to render.');
     await waitFor(() => expect(screen.getByText('No Frills')).toBeInTheDocument());
 
@@ -217,7 +218,7 @@ describe('AdminBrandManager', () => {
       async () => new Response(JSON.stringify(mockBrands), { status: 200 }),
     );
     console.log('TEST ACTION: Rendering AdminBrandManager component.');
-    render(<AdminBrandManager />);
+    renderWithProviders(<AdminBrandManager />);
     console.log('TEST ACTION: Waiting for initial brands to render.');
     await waitFor(() => expect(screen.getByText('No Frills')).toBeInTheDocument());
 
@@ -247,7 +248,7 @@ describe('AdminBrandManager', () => {
     );
     mockedToast.loading.mockReturnValue('toast-3');
 
-    render(<AdminBrandManager />);
+    renderWithProviders(<AdminBrandManager />);
     await waitFor(() => expect(screen.getByText('No Frills')).toBeInTheDocument());
 
     const file = new File(['logo'], 'logo.png', { type: 'image/png' });
@@ -270,7 +271,7 @@ describe('AdminBrandManager', () => {
     mockedApiClient.fetchAllBrands.mockImplementation(
       async () => new Response(JSON.stringify(mockBrands), { status: 200 }),
     );
-    render(<AdminBrandManager />);
+    renderWithProviders(<AdminBrandManager />);
     console.log('TEST ACTION: Waiting for initial brands to render.');
     await waitFor(() => expect(screen.getByText('No Frills')).toBeInTheDocument());
 
@@ -291,7 +292,7 @@ describe('AdminBrandManager', () => {
     mockedApiClient.fetchAllBrands.mockImplementation(
       async () => new Response(JSON.stringify([]), { status: 200 }),
     );
-    render(<AdminBrandManager />);
+    renderWithProviders(<AdminBrandManager />);
 
     await waitFor(() => {
       expect(screen.getByRole('heading', { name: /brand management/i })).toBeInTheDocument();
@@ -309,7 +310,7 @@ describe('AdminBrandManager', () => {
     );
     mockedToast.loading.mockReturnValue('toast-fallback');
 
-    render(<AdminBrandManager />);
+    renderWithProviders(<AdminBrandManager />);
     await waitFor(() => expect(screen.getByText('No Frills')).toBeInTheDocument());
 
     const file = new File(['logo'], 'logo.png', { type: 'image/png' });
@@ -333,7 +334,7 @@ describe('AdminBrandManager', () => {
     );
     mockedToast.loading.mockReturnValue('toast-opt');
 
-    render(<AdminBrandManager />);
+    renderWithProviders(<AdminBrandManager />);
     await waitFor(() => expect(screen.getByText('No Frills')).toBeInTheDocument());
 
     // Brand 1: No Frills (initially null logo)

src/pages/admin/components/AuthView.test.tsx

@@ -1,11 +1,12 @@
 // src/pages/admin/components/AuthView.test.tsx
 import React from 'react';
-import { render, screen, fireEvent, waitFor, act } from '@testing-library/react';
+import { screen, fireEvent, waitFor } from '@testing-library/react';
 import { describe, it, expect, vi, beforeEach, type Mock } from 'vitest';
 import { AuthView } from './AuthView';
 import * as apiClient from '../../../services/apiClient';
 import { notifySuccess, notifyError } from '../../../services/notificationService';
 import { createMockUserProfile } from '../../../tests/utils/mockFactories';
+import { renderWithProviders } from '../../../tests/utils/renderWithProviders';
 
 const mockedApiClient = vi.mocked(apiClient, true);
 
@@ -46,7 +47,7 @@ describe('AuthView', () => {
 
   describe('Initial Render and Login', () => {
     it('should render the Sign In form by default', () => {
-      render(<AuthView {...defaultProps} />);
+      renderWithProviders(<AuthView {...defaultProps} />);
       expect(screen.getByRole('heading', { name: /sign in/i })).toBeInTheDocument();
       expect(screen.getByLabelText(/email address/i)).toBeInTheDocument();
       expect(screen.getByLabelText(/^password$/i)).toBeInTheDocument();
@@ -54,7 +55,7 @@ describe('AuthView', () => {
     });
 
     it('should allow typing in email and password fields', () => {
-      render(<AuthView {...defaultProps} />);
+      renderWithProviders(<AuthView {...defaultProps} />);
       const emailInput = screen.getByLabelText(/email address/i);
       const passwordInput = screen.getByLabelText(/^password$/i);
 
@@ -66,7 +67,7 @@ describe('AuthView', () => {
     });
 
     it('should call loginUser and onLoginSuccess on successful login', async () => {
-      render(<AuthView {...defaultProps} />);
+      renderWithProviders(<AuthView {...defaultProps} />);
       fireEvent.change(screen.getByLabelText(/email address/i), {
         target: { value: 'test@example.com' },
       });
@@ -94,7 +95,7 @@ describe('AuthView', () => {
 
     it('should display an error on failed login', async () => {
       (mockedApiClient.loginUser as Mock).mockRejectedValueOnce(new Error('Invalid credentials'));
-      render(<AuthView {...defaultProps} />);
+      renderWithProviders(<AuthView {...defaultProps} />);
       fireEvent.submit(screen.getByTestId('auth-form'));
 
       await waitFor(() => {
@@ -107,7 +108,7 @@ describe('AuthView', () => {
       (mockedApiClient.loginUser as Mock).mockResolvedValueOnce(
         new Response(JSON.stringify({ message: 'Unauthorized' }), { status: 401 }),
       );
-      render(<AuthView {...defaultProps} />);
+      renderWithProviders(<AuthView {...defaultProps} />);
       fireEvent.submit(screen.getByTestId('auth-form'));
 
       await waitFor(() => {
@@ -120,7 +121,7 @@ describe('AuthView', () => {
 
   describe('Registration', () => {
     it('should switch to the registration form', () => {
-      render(<AuthView {...defaultProps} />);
+      renderWithProviders(<AuthView {...defaultProps} />);
       fireEvent.click(screen.getByRole('button', { name: /don't have an account\? register/i }));
 
       expect(screen.getByRole('heading', { name: /create an account/i })).toBeInTheDocument();
@@ -129,7 +130,7 @@ describe('AuthView', () => {
     });
 
     it('should call registerUser on successful registration', async () => {
-      render(<AuthView {...defaultProps} />);
+      renderWithProviders(<AuthView {...defaultProps} />);
       fireEvent.click(screen.getByRole('button', { name: /don't have an account\? register/i }));
 
       fireEvent.change(screen.getByLabelText(/full name/i), { target: { value: 'Test User' } });
@@ -157,7 +158,7 @@ describe('AuthView', () => {
     });
 
     it('should allow registration without providing a full name', async () => {
-      render(<AuthView {...defaultProps} />);
+      renderWithProviders(<AuthView {...defaultProps} />);
       fireEvent.click(screen.getByRole('button', { name: /don't have an account\? register/i }));
 
       // Do not fill in the full name, which is marked as optional
@@ -184,7 +185,7 @@ describe('AuthView', () => {
       (mockedApiClient.registerUser as Mock).mockRejectedValueOnce(
         new Error('Email already exists'),
       );
-      render(<AuthView {...defaultProps} />);
+      renderWithProviders(<AuthView {...defaultProps} />);
       fireEvent.click(screen.getByRole('button', { name: /don't have an account\? register/i }));
       fireEvent.submit(screen.getByTestId('auth-form'));
 
@@ -197,7 +198,7 @@ describe('AuthView', () => {
       (mockedApiClient.registerUser as Mock).mockResolvedValueOnce(
         new Response(JSON.stringify({ message: 'User exists' }), { status: 409 }),
       );
-      render(<AuthView {...defaultProps} />);
+      renderWithProviders(<AuthView {...defaultProps} />);
       fireEvent.click(screen.getByRole('button', { name: /don't have an account\? register/i }));
       fireEvent.submit(screen.getByTestId('auth-form'));
 
@@ -209,7 +210,7 @@ describe('AuthView', () => {
 
   describe('Forgot Password', () => {
     it('should switch to the reset password form', () => {
-      render(<AuthView {...defaultProps} />);
+      renderWithProviders(<AuthView {...defaultProps} />);
       fireEvent.click(screen.getByRole('button', { name: /forgot password\?/i }));
 
       expect(screen.getByRole('heading', { name: /reset password/i })).toBeInTheDocument();
@@ -217,7 +218,7 @@ describe('AuthView', () => {
     });
 
     it('should call requestPasswordReset and show success message', async () => {
-      render(<AuthView {...defaultProps} />);
+      renderWithProviders(<AuthView {...defaultProps} />);
       fireEvent.click(screen.getByRole('button', { name: /forgot password\?/i }));
 
       fireEvent.change(screen.getByLabelText(/email address/i), {
@@ -238,7 +239,7 @@ describe('AuthView', () => {
       (mockedApiClient.requestPasswordReset as Mock).mockRejectedValueOnce(
         new Error('User not found'),
       );
-      render(<AuthView {...defaultProps} />);
+      renderWithProviders(<AuthView {...defaultProps} />);
       fireEvent.click(screen.getByRole('button', { name: /forgot password\?/i }));
       fireEvent.submit(screen.getByTestId('reset-password-form'));
 
@@ -251,7 +252,7 @@ describe('AuthView', () => {
       (mockedApiClient.requestPasswordReset as Mock).mockResolvedValueOnce(
         new Response(JSON.stringify({ message: 'Rate limit exceeded' }), { status: 429 }),
       );
-      render(<AuthView {...defaultProps} />);
+      renderWithProviders(<AuthView {...defaultProps} />);
       fireEvent.click(screen.getByRole('button', { name: /forgot password\?/i }));
       fireEvent.submit(screen.getByTestId('reset-password-form'));
 
@@ -261,7 +262,7 @@ describe('AuthView', () => {
     });
 
     it('should switch back to sign in from forgot password', () => {
-      render(<AuthView {...defaultProps} />);
+      renderWithProviders(<AuthView {...defaultProps} />);
       fireEvent.click(screen.getByRole('button', { name: /forgot password\?/i }));
       fireEvent.click(screen.getByRole('button', { name: /back to sign in/i }));
 
@@ -287,13 +288,13 @@ describe('AuthView', () => {
     });
 
     it('should set window.location.href for Google OAuth', () => {
-      render(<AuthView {...defaultProps} />);
+      renderWithProviders(<AuthView {...defaultProps} />);
       fireEvent.click(screen.getByRole('button', { name: /sign in with google/i }));
       expect(window.location.href).toBe('/api/auth/google');
     });
 
     it('should set window.location.href for GitHub OAuth', () => {
-      render(<AuthView {...defaultProps} />);
+      renderWithProviders(<AuthView {...defaultProps} />);
       fireEvent.click(screen.getByRole('button', { name: /sign in with github/i }));
       expect(window.location.href).toBe('/api/auth/github');
     });
@@ -301,7 +302,7 @@ describe('AuthView', () => {
 
   describe('UI Logic and Loading States', () => {
     it('should toggle "Remember me" checkbox', () => {
-      render(<AuthView {...defaultProps} />);
+      renderWithProviders(<AuthView {...defaultProps} />);
       const rememberMeCheckbox = screen.getByRole('checkbox', { name: /remember me/i });
 
       expect(rememberMeCheckbox).not.toBeChecked();
@@ -316,7 +317,7 @@ describe('AuthView', () => {
     it('should show loading state during login submission', async () => {
       // Mock a promise that doesn't resolve immediately
       (mockedApiClient.loginUser as Mock).mockReturnValue(new Promise(() => {}));
-      render(<AuthView {...defaultProps} />);
+      renderWithProviders(<AuthView {...defaultProps} />);
 
       fireEvent.change(screen.getByLabelText(/email address/i), {
         target: { value: 'test@example.com' },
@@ -341,7 +342,7 @@ describe('AuthView', () => {
 
     it('should show loading state during password reset submission', async () => {
       (mockedApiClient.requestPasswordReset as Mock).mockReturnValue(new Promise(() => {}));
-      render(<AuthView {...defaultProps} />);
+      renderWithProviders(<AuthView {...defaultProps} />);
 
       fireEvent.click(screen.getByRole('button', { name: /forgot password\?/i }));
 
@@ -362,7 +363,7 @@ describe('AuthView', () => {
   it('should show loading state during registration submission', async () => {
     // Mock a promise that doesn't resolve immediately
     (mockedApiClient.registerUser as Mock).mockReturnValue(new Promise(() => {}));
-    render(<AuthView {...defaultProps} />);
+    renderWithProviders(<AuthView {...defaultProps} />);
 
     // Switch to registration view
     fireEvent.click(screen.getByRole('button', { name: /don't have an account\? register/i }));

src/pages/admin/components/CorrectionRow.test.tsx

@@ -1,7 +1,7 @@
 // src/pages/admin/components/CorrectionRow.test.tsx
 import React from 'react';
 import ReactDOM from 'react-dom';
-import { render, screen, fireEvent, waitFor } from '@testing-library/react';
+import { screen, fireEvent, waitFor } from '@testing-library/react';
 import { describe, it, expect, vi, beforeEach, type Mocked } from 'vitest';
 import { CorrectionRow } from './CorrectionRow';
 import * as apiClient from '../../../services/apiClient';
@@ -10,15 +10,11 @@ import {
   createMockMasterGroceryItem,
   createMockCategory,
 } from '../../../tests/utils/mockFactories';
+import { renderWithProviders } from '../../../tests/utils/renderWithProviders';
 
-// Cast the mocked module to its mocked type to retain type safety and autocompletion.
-// The apiClient is now mocked globally via src/tests/setup/tests-setup-unit.ts.
-const mockedApiClient = apiClient as Mocked<typeof apiClient>;
-
-// Mock the logger
-vi.mock('../../../services/logger', () => ({
-  logger: { info: vi.fn(), error: vi.fn() },
-}));
+// The apiClient and logger are mocked globally.
+// We can get a typed reference to the apiClient for individual test overrides.
+const mockedApiClient = vi.mocked(apiClient);
 
 // Mock the ConfirmationModal to test its props and interactions
 // The ConfirmationModal is now in a different directory.
@@ -80,7 +76,7 @@ const defaultProps = {
 
 // Helper to render the component inside a table structure
 const renderInTable = (props = defaultProps) => {
-  return render(
+  return renderWithProviders(
     <table>
       <tbody>
         <CorrectionRow {...props} />

src/pages/admin/components/ProfileManager.test.tsx

@@ -21,25 +21,10 @@ vi.mock('../../../components/PasswordInput', () => ({
   PasswordInput: (props: any) => <input {...props} data-testid="password-input" />,
 }));
 
+// The apiClient, notificationService, react-hot-toast, and logger are all mocked globally.
+// We can get a typed reference to the apiClient for individual test overrides.
 const mockedApiClient = vi.mocked(apiClient, true);
 
-vi.mock('../../../services/notificationService');
-vi.mock('react-hot-toast', () => ({
-  __esModule: true,
-  default: {
-    success: vi.fn(),
-    error: vi.fn(),
-  },
-}));
-vi.mock('../../../services/logger.client', () => ({
-  logger: {
-    debug: vi.fn(),
-    info: vi.fn(),
-    warn: vi.fn(),
-    error: vi.fn(),
-  },
-}));
-
 const mockOnClose = vi.fn();
 const mockOnLoginSuccess = vi.fn();
 const mockOnSignOut = vi.fn();
@@ -883,6 +868,12 @@ describe('ProfileManager', () => {
       });
     });
 
+    it('should not render auth views when the user is already authenticated', () => {
+      render(<ProfileManager {...defaultAuthenticatedProps} />);
+      expect(screen.queryByText('Sign In')).not.toBeInTheDocument();
+      expect(screen.queryByText('Create an Account')).not.toBeInTheDocument();
+    });
+
     it('should log warning if address fetch returns null', async () => {
       console.log('[TEST DEBUG] Running: should log warning if address fetch returns null');
       const loggerSpy = vi.spyOn(logger.logger, 'warn');
@@ -905,5 +896,113 @@ describe('ProfileManager', () => {
         );
       });
     });
+
+    it('should handle updating the user profile and address with empty strings', async () => {
+      mockedApiClient.updateUserProfile.mockImplementation(async (data) =>
+        new Response(JSON.stringify({ ...authenticatedProfile, ...data })),
+      );
+      mockedApiClient.updateUserAddress.mockImplementation(async (data) =>
+        new Response(JSON.stringify({ ...mockAddress, ...data })),
+      );
+
+      render(<ProfileManager {...defaultAuthenticatedProps} />);
+
+      await waitFor(() => {
+        expect(screen.getByLabelText(/full name/i)).toHaveValue(authenticatedProfile.full_name);
+      });
+      await waitFor(() => expect(screen.getByLabelText(/city/i)).toHaveValue(mockAddress.city));
+
+      fireEvent.change(screen.getByLabelText(/full name/i), { target: { value: '' } });
+      fireEvent.change(screen.getByLabelText(/city/i), { target: { value: '' } });
+
+      const saveButton = screen.getByRole('button', { name: /save profile/i });
+      fireEvent.click(saveButton);
+
+      await waitFor(() => {
+        expect(mockedApiClient.updateUserProfile).toHaveBeenCalledWith(
+          { full_name: '', avatar_url: authenticatedProfile.avatar_url },
+          expect.objectContaining({ signal: expect.anything() }),
+        );
+        expect(mockedApiClient.updateUserAddress).toHaveBeenCalledWith(
+          expect.objectContaining({ city: '' }),
+          expect.objectContaining({ signal: expect.anything() }),
+        );
+        expect(mockOnProfileUpdate).toHaveBeenCalledWith(
+          expect.objectContaining({ full_name: '' })
+        );
+        expect(notifySuccess).toHaveBeenCalledWith('Profile updated successfully!');
+      });
+    });
+
+    it('should correctly clear the form when userProfile.address_id is null', async () => {
+      const profileNoAddress = { ...authenticatedProfile, address_id: null };
+      render(
+        <ProfileManager
+          {...defaultAuthenticatedProps}
+          userProfile={profileNoAddress as any} // Forcefully override the type to simulate address_id: null
+        />,
+      );
+
+      await waitFor(() => {
+        expect(screen.getByLabelText(/address line 1/i)).toHaveValue('');
+        expect(screen.getByLabelText(/city/i)).toHaveValue('');
+        expect(screen.getByLabelText(/province \/ state/i)).toHaveValue('');
+        expect(screen.getByLabelText(/postal \/ zip code/i)).toHaveValue('');
+        expect(screen.getByLabelText(/country/i)).toHaveValue('');
+      });
+    });
+
+    it('should show error notification when manual geocoding fails', async () => {
+      render(<ProfileManager {...defaultAuthenticatedProps} />);
+      await waitFor(() => expect(screen.getByLabelText(/city/i)).toHaveValue(mockAddress.city));
+
+      (mockedApiClient.geocodeAddress as Mock).mockRejectedValue(new Error('Geocoding failed'));
+
+      fireEvent.click(screen.getByRole('button', { name: /re-geocode/i }));
+
+      await waitFor(() => {
+        expect(notifyError).toHaveBeenCalledWith('Geocoding failed');
+      });
+    });
+
+    it('should show error notification when auto-geocoding fails', async () => {
+      vi.useFakeTimers();
+      // FIX: Mock getUserAddress to return an address *without* coordinates.
+      // This is the condition required to trigger the auto-geocoding logic.
+      const addressWithoutCoords = { ...mockAddress, latitude: undefined, longitude: undefined };
+      mockedApiClient.getUserAddress.mockResolvedValue(
+        new Response(JSON.stringify(addressWithoutCoords)),
+      );
+
+      render(<ProfileManager {...defaultAuthenticatedProps} />);
+
+      // Wait for initial load
+      await act(async () => {
+        await vi.runAllTimersAsync();
+      });
+
+      (mockedApiClient.geocodeAddress as Mock).mockRejectedValue(new Error('Auto-geocode error'));
+
+      fireEvent.change(screen.getByLabelText(/city/i), { target: { value: 'ErrorCity' } });
+
+      await act(async () => {
+        await vi.runAllTimersAsync();
+      });
+
+      expect(notifyError).toHaveBeenCalledWith('Auto-geocode error');
+    });
+
+    it('should handle permission denied error during geocoding', async () => {
+      render(<ProfileManager {...defaultAuthenticatedProps} />);
+      await waitFor(() => expect(screen.getByLabelText(/city/i)).toHaveValue(mockAddress.city));
+
+      (mockedApiClient.geocodeAddress as Mock).mockRejectedValue(new Error('Permission denied'));
+
+      fireEvent.click(screen.getByRole('button', { name: /re-geocode/i }));
+
+      await waitFor(() => {
+        expect(notifyError).toHaveBeenCalledWith('Permission denied');
+      });
+    });
   });
 });

src/pages/admin/components/StatCard.test.tsx

@@ -1,18 +1,19 @@
 import React from 'react';
-import { render, screen } from '@testing-library/react';
+import { screen } from '@testing-library/react';
 import { describe, it, expect } from 'vitest';
 import { StatCard } from './StatCard';
+import { renderWithProviders } from '../../../tests/utils/renderWithProviders';
 
 describe('StatCard', () => {
   it('should render the title and value correctly', () => {
-    render(<StatCard title="Test Stat" value="1,234" icon={<div data-testid="icon" />} />);
+    renderWithProviders(<StatCard title="Test Stat" value="1,234" icon={<div data-testid="icon" />} />);
 
     expect(screen.getByText('Test Stat')).toBeInTheDocument();
     expect(screen.getByText('1,234')).toBeInTheDocument();
   });
 
   it('should render the icon', () => {
-    render(
+    renderWithProviders(
       <StatCard title="Test Stat" value={100} icon={<div data-testid="test-icon">Icon</div>} />,
     );
 

src/pages/admin/components/SystemCheck.test.tsx

@@ -1,47 +1,18 @@
 // src/pages/admin/components/SystemCheck.test.tsx
 import React from 'react';
-import { render, screen, waitFor, cleanup, fireEvent, act } from '@testing-library/react';
+import { screen, waitFor, cleanup, fireEvent, act } from '@testing-library/react';
 import { describe, it, expect, vi, beforeEach, afterEach, type Mock } from 'vitest';
 import { SystemCheck } from './SystemCheck';
 import * as apiClient from '../../../services/apiClient';
 import toast from 'react-hot-toast';
 import { createMockUser } from '../../../tests/utils/mockFactories';
+import { renderWithProviders } from '../../../tests/utils/renderWithProviders';
 
-// Mock the entire apiClient module to ensure all exports are defined.
-// This is the primary fix for the error: [vitest] No "..." export is defined on the mock.
-vi.mock('../../../services/apiClient', () => ({
-  pingBackend: vi.fn(),
-  checkStorage: vi.fn(),
-  checkDbPoolHealth: vi.fn(),
-  checkPm2Status: vi.fn(),
-  checkRedisHealth: vi.fn(),
-  checkDbSchema: vi.fn(),
-  loginUser: vi.fn(),
-  triggerFailingJob: vi.fn(),
-  clearGeocodeCache: vi.fn(),
-}));
-
-// Get a type-safe mocked version of the apiClient module.
+// The apiClient is mocked globally in `src/tests/setup/globalApiMock.ts`.
+// We can get a type-safe mocked version of the module to override functions for specific tests.
 const mockedApiClient = vi.mocked(apiClient);
 
-// Correct the relative path to the logger module.
-vi.mock('../../../services/logger', () => ({
-  logger: {
-    info: vi.fn(),
-    warn: vi.fn(),
-    error: vi.fn(),
-    debug: vi.fn(),
-  },
-}));
-
-// Mock toast to check for notifications
-vi.mock('react-hot-toast', () => ({
-  __esModule: true,
-  default: {
-    success: vi.fn(),
-    error: vi.fn(),
-  },
-}));
+// The logger and react-hot-toast are mocked globally.
 
 describe('SystemCheck', () => {
   // Store original env variable
@@ -100,7 +71,7 @@ describe('SystemCheck', () => {
 
   it('should render initial idle state and then run checks automatically on mount', async () => {
     setGeminiApiKey('mock-api-key');
-    render(<SystemCheck />);
+    renderWithProviders(<SystemCheck />);
 
     // Initially, all checks should be in 'running' state due to auto-run
     // However, the API key check is synchronous and resolves immediately.
@@ -126,7 +97,7 @@ describe('SystemCheck', () => {
 
   it('should show API key as failed if GEMINI_API_KEY is not set', async () => {
     setGeminiApiKey(undefined);
-    render(<SystemCheck />);
+    renderWithProviders(<SystemCheck />);
 
     // Wait for the specific error message to appear.
     expect(
@@ -139,7 +110,7 @@ describe('SystemCheck', () => {
   it('should show backend connection as failed if pingBackend fails', async () => {
     setGeminiApiKey('mock-api-key');
     (mockedApiClient.pingBackend as Mock).mockRejectedValueOnce(new Error('Network error'));
-    render(<SystemCheck />);
+    renderWithProviders(<SystemCheck />);
 
     await waitFor(() => {
       expect(screen.getByText('Network error')).toBeInTheDocument();
@@ -164,7 +135,7 @@ describe('SystemCheck', () => {
         new Response(JSON.stringify({ success: false, message: 'PM2 process not found' })),
       ),
     );
-    render(<SystemCheck />);
+    renderWithProviders(<SystemCheck />);
 
     await waitFor(() => {
       expect(screen.getByText('PM2 process not found')).toBeInTheDocument();
@@ -174,7 +145,7 @@ describe('SystemCheck', () => {
   it('should show database pool check as failed if checkDbPoolHealth fails', async () => {
     setGeminiApiKey('mock-api-key'); // This was missing
     mockedApiClient.checkDbPoolHealth.mockRejectedValueOnce(new Error('DB connection refused'));
-    render(<SystemCheck />);
+    renderWithProviders(<SystemCheck />);
 
     await waitFor(() => {
       expect(screen.getByText('DB connection refused')).toBeInTheDocument();
@@ -184,7 +155,7 @@ describe('SystemCheck', () => {
   it('should show Redis check as failed if checkRedisHealth fails', async () => {
     setGeminiApiKey('mock-api-key');
     mockedApiClient.checkRedisHealth.mockRejectedValueOnce(new Error('Redis connection refused'));
-    render(<SystemCheck />);
+    renderWithProviders(<SystemCheck />);
 
     await waitFor(() => {
       expect(screen.getByText('Redis connection refused')).toBeInTheDocument();
@@ -197,7 +168,7 @@ describe('SystemCheck', () => {
     mockedApiClient.checkDbPoolHealth.mockImplementationOnce(() =>
       Promise.reject(new Error('DB connection refused')),
     );
-    render(<SystemCheck />);
+    renderWithProviders(<SystemCheck />);
 
     await waitFor(() => {
       // Verify the specific "skipped" messages for DB-dependent checks
@@ -214,7 +185,7 @@ describe('SystemCheck', () => {
     mockedApiClient.checkDbSchema.mockImplementationOnce(() =>
       Promise.resolve(new Response(JSON.stringify({ success: false, message: 'Schema mismatch' }))),
     );
-    render(<SystemCheck />);
+    renderWithProviders(<SystemCheck />);
 
     await waitFor(() => {
       expect(screen.getByText('Schema mismatch')).toBeInTheDocument();
@@ -224,7 +195,7 @@ describe('SystemCheck', () => {
   it('should show seeded user check as failed if loginUser fails', async () => {
     setGeminiApiKey('mock-api-key');
     mockedApiClient.loginUser.mockRejectedValueOnce(new Error('Incorrect email or password'));
-    render(<SystemCheck />);
+    renderWithProviders(<SystemCheck />);
 
     await waitFor(() => {
       expect(
@@ -236,7 +207,7 @@ describe('SystemCheck', () => {
   it('should show a generic failure message for other login errors', async () => {
     setGeminiApiKey('mock-api-key');
     mockedApiClient.loginUser.mockRejectedValueOnce(new Error('Server is on fire'));
-    render(<SystemCheck />);
+    renderWithProviders(<SystemCheck />);
 
     await waitFor(() => {
       expect(screen.getByText('Failed: Server is on fire')).toBeInTheDocument();
@@ -246,7 +217,7 @@ describe('SystemCheck', () => {
   it('should show storage directory check as failed if checkStorage fails', async () => {
     setGeminiApiKey('mock-api-key');
     mockedApiClient.checkStorage.mockRejectedValueOnce(new Error('Storage not writable'));
-    render(<SystemCheck />);
+    renderWithProviders(<SystemCheck />);
 
     await waitFor(() => {
       expect(screen.getByText('Storage not writable')).toBeInTheDocument();
@@ -262,7 +233,7 @@ describe('SystemCheck', () => {
     });
     mockedApiClient.pingBackend.mockImplementation(() => mockPromise);
 
-    render(<SystemCheck />);
+    renderWithProviders(<SystemCheck />);
 
     // The button text changes to "Running Checks..."
     const runningButton = screen.getByRole('button', { name: /running checks/i });
@@ -283,7 +254,7 @@ describe('SystemCheck', () => {
 
   it('should re-run checks when the "Re-run Checks" button is clicked', async () => {
     setGeminiApiKey('mock-api-key');
-    render(<SystemCheck />);
+    renderWithProviders(<SystemCheck />);
 
     // Wait for initial auto-run to complete
     await waitFor(() => expect(screen.getByText(/finished in/i)).toBeInTheDocument());
@@ -328,7 +299,7 @@ describe('SystemCheck', () => {
     mockedApiClient.checkDbSchema.mockImplementationOnce(() =>
       Promise.resolve(new Response(JSON.stringify({ success: false, message: 'Schema mismatch' }))),
     );
-    const { container } = render(<SystemCheck />);
+    const { container } = renderWithProviders(<SystemCheck />);
 
     await waitFor(() => {
       // Instead of test-ids, we check for the result: the icon's color class.
@@ -344,7 +315,7 @@ describe('SystemCheck', () => {
 
   it('should display elapsed time after checks complete', async () => {
     setGeminiApiKey('mock-api-key');
-    render(<SystemCheck />);
+    renderWithProviders(<SystemCheck />);
 
     await waitFor(() => {
       const elapsedTimeText = screen.getByText(/finished in \d+\.\d{2} seconds\./i);
@@ -357,7 +328,7 @@ describe('SystemCheck', () => {
 
   describe('Integration: Job Queue Retries', () => {
     it('should call triggerFailingJob and show a success toast', async () => {
-      render(<SystemCheck />);
+      renderWithProviders(<SystemCheck />);
       const triggerButton = screen.getByRole('button', { name: /trigger failing job/i });
       fireEvent.click(triggerButton);
 
@@ -374,7 +345,7 @@ describe('SystemCheck', () => {
       });
       mockedApiClient.triggerFailingJob.mockImplementation(() => mockPromise);
 
-      render(<SystemCheck />);
+      renderWithProviders(<SystemCheck />);
       const triggerButton = screen.getByRole('button', { name: /trigger failing job/i });
       fireEvent.click(triggerButton);
 
@@ -390,7 +361,7 @@ describe('SystemCheck', () => {
 
     it('should show an error toast if triggering the job fails', async () => {
       mockedApiClient.triggerFailingJob.mockRejectedValueOnce(new Error('Queue is down'));
-      render(<SystemCheck />);
+      renderWithProviders(<SystemCheck />);
       const triggerButton = screen.getByRole('button', { name: /trigger failing job/i });
       fireEvent.click(triggerButton);
 
@@ -403,7 +374,7 @@ describe('SystemCheck', () => {
       mockedApiClient.triggerFailingJob.mockResolvedValueOnce(
         new Response(JSON.stringify({ message: 'Server error' }), { status: 500 }),
       );
-      render(<SystemCheck />);
+      renderWithProviders(<SystemCheck />);
       const triggerButton = screen.getByRole('button', { name: /trigger failing job/i });
       fireEvent.click(triggerButton);
 
@@ -420,7 +391,7 @@ describe('SystemCheck', () => {
     });
 
     it('should call clearGeocodeCache and show a success toast', async () => {
-      render(<SystemCheck />);
+      renderWithProviders(<SystemCheck />);
       // Wait for checks to run and Redis to be OK
       await waitFor(() => expect(screen.getByText('Redis OK')).toBeInTheDocument());
 
@@ -435,7 +406,7 @@ describe('SystemCheck', () => {
 
     it('should show an error toast if clearing the cache fails', async () => {
       mockedApiClient.clearGeocodeCache.mockRejectedValueOnce(new Error('Redis is busy'));
-      render(<SystemCheck />);
+      renderWithProviders(<SystemCheck />);
       await waitFor(() => expect(screen.getByText('Redis OK')).toBeInTheDocument());
       fireEvent.click(screen.getByRole('button', { name: /clear geocode cache/i }));
       await waitFor(() => expect(vi.mocked(toast).error).toHaveBeenCalledWith('Redis is busy'));
@@ -443,7 +414,7 @@ describe('SystemCheck', () => {
 
     it('should not call clearGeocodeCache if user cancels confirmation', async () => {
       vi.spyOn(window, 'confirm').mockReturnValue(false);
-      render(<SystemCheck />);
+      renderWithProviders(<SystemCheck />);
       await waitFor(() => expect(screen.getByText('Redis OK')).toBeInTheDocument());
 
       const clearButton = screen.getByRole('button', { name: /clear geocode cache/i });
@@ -456,7 +427,7 @@ describe('SystemCheck', () => {
       mockedApiClient.clearGeocodeCache.mockResolvedValueOnce(
         new Response(JSON.stringify({ message: 'Cache clear failed' }), { status: 500 }),
       );
-      render(<SystemCheck />);
+      renderWithProviders(<SystemCheck />);
       await waitFor(() => expect(screen.getByText('Redis OK')).toBeInTheDocument());
 
       fireEvent.click(screen.getByRole('button', { name: /clear geocode cache/i }));
@@ -470,7 +441,7 @@ describe('SystemCheck', () => {
       mockedApiClient.checkRedisHealth.mockResolvedValueOnce(
         new Response(JSON.stringify({ success: false, message: 'Redis down' })),
       );
-      render(<SystemCheck />);
+      renderWithProviders(<SystemCheck />);
 
       await waitFor(() => expect(screen.getByText('Redis down')).toBeInTheDocument());
 
@@ -486,7 +457,7 @@ describe('SystemCheck', () => {
       mockedApiClient.pingBackend.mockResolvedValueOnce(
         new Response('unexpected response', { status: 200 }),
       );
-      render(<SystemCheck />);
+      renderWithProviders(<SystemCheck />);
 
       await waitFor(() => {
         expect(
@@ -499,7 +470,7 @@ describe('SystemCheck', () => {
       mockedApiClient.checkStorage.mockResolvedValueOnce(
         new Response(JSON.stringify({ message: 'Permission denied' }), { status: 403 }),
       );
-      render(<SystemCheck />);
+      renderWithProviders(<SystemCheck />);
 
       await waitFor(() => {
         expect(screen.getByText('Permission denied')).toBeInTheDocument();
@@ -511,7 +482,7 @@ describe('SystemCheck', () => {
       mockedApiClient.checkDbSchema.mockResolvedValueOnce(
         new Response(JSON.stringify({ message: 'Schema check failed 500' }), { status: 500 }),
       );
-      render(<SystemCheck />);
+      renderWithProviders(<SystemCheck />);
 
       await waitFor(() => {
         expect(screen.getByText('Schema check failed 500')).toBeInTheDocument();
@@ -523,7 +494,7 @@ describe('SystemCheck', () => {
       mockedApiClient.checkDbPoolHealth.mockResolvedValueOnce(
         new Response(JSON.stringify({ message: 'DB Pool check failed 500' }), { status: 500 }),
       );
-      render(<SystemCheck />);
+      renderWithProviders(<SystemCheck />);
 
       await waitFor(() => {
         expect(screen.getByText('DB Pool check failed 500')).toBeInTheDocument();
@@ -535,7 +506,7 @@ describe('SystemCheck', () => {
       mockedApiClient.checkPm2Status.mockResolvedValueOnce(
         new Response(JSON.stringify({ message: 'PM2 check failed 500' }), { status: 500 }),
       );
-      render(<SystemCheck />);
+      renderWithProviders(<SystemCheck />);
 
       await waitFor(() => {
         expect(screen.getByText('PM2 check failed 500')).toBeInTheDocument();
@@ -547,7 +518,7 @@ describe('SystemCheck', () => {
       mockedApiClient.checkRedisHealth.mockResolvedValueOnce(
         new Response(JSON.stringify({ message: 'Redis check failed 500' }), { status: 500 }),
       );
-      render(<SystemCheck />);
+      renderWithProviders(<SystemCheck />);
 
       await waitFor(() => {
         expect(screen.getByText('Redis check failed 500')).toBeInTheDocument();
@@ -559,7 +530,7 @@ describe('SystemCheck', () => {
       mockedApiClient.checkRedisHealth.mockResolvedValueOnce(
         new Response(JSON.stringify({ success: false, message: 'Redis is down' })),
       );
-      render(<SystemCheck />);
+      renderWithProviders(<SystemCheck />);
 
       await waitFor(() => {
         expect(screen.getByText('Redis is down')).toBeInTheDocument();
@@ -571,7 +542,7 @@ describe('SystemCheck', () => {
       mockedApiClient.loginUser.mockResolvedValueOnce(
         new Response(JSON.stringify({ message: 'Invalid credentials' }), { status: 401 }),
       );
-      render(<SystemCheck />);
+      renderWithProviders(<SystemCheck />);
 
       await waitFor(() => {
         expect(screen.getByText('Failed: Invalid credentials')).toBeInTheDocument();

src/providers/ApiProvider.test.tsx

@@ -6,14 +6,8 @@ import { ApiProvider } from './ApiProvider';
 import { ApiContext } from '../contexts/ApiContext';
 import * as apiClient from '../services/apiClient';
 
-// Mock the apiClient module.
-// Since ApiProvider and ApiContext import * as apiClient, mocking it ensures
-// we control the reference identity and can verify it's being passed correctly.
-vi.mock('../services/apiClient', () => ({
-  fetchFlyers: vi.fn(),
-  fetchMasterItems: vi.fn(),
-  // Add other mocked methods as needed for the shape to be valid-ish
-}));
+// The apiClient is mocked globally in `src/tests/setup/globalApiMock.ts`.
+// This test verifies that the ApiProvider correctly provides this mocked module.
 
 describe('ApiProvider & ApiContext', () => {
   const TestConsumer = () => {

src/providers/AppProviders.test.tsx

@@ -0,0 +1,72 @@
+// src/providers/AppProviders.test.tsx
+import React from 'react';
+import { render, screen } from '@testing-library/react';
+import { describe, it, expect, vi } from 'vitest';
+import { AppProviders } from './AppProviders';
+
+// Mock all the providers to avoid their side effects and isolate AppProviders logic.
+// We render a simple div with a data-testid for each to verify nesting.
+vi.mock('./ModalProvider', () => ({
+  ModalProvider: ({ children }: { children: React.ReactNode }) => (
+    <div data-testid="modal-provider">{children}</div>
+  ),
+}));
+
+vi.mock('./AuthProvider', () => ({
+  AuthProvider: ({ children }: { children: React.ReactNode }) => (
+    <div data-testid="auth-provider">{children}</div>
+  ),
+}));
+
+vi.mock('./FlyersProvider', () => ({
+  FlyersProvider: ({ children }: { children: React.ReactNode }) => (
+    <div data-testid="flyers-provider">{children}</div>
+  ),
+}));
+
+vi.mock('./MasterItemsProvider', () => ({
+  MasterItemsProvider: ({ children }: { children: React.ReactNode }) => (
+    <div data-testid="master-items-provider">{children}</div>
+  ),
+}));
+
+vi.mock('./UserDataProvider', () => ({
+  UserDataProvider: ({ children }: { children: React.ReactNode }) => (
+    <div data-testid="user-data-provider">{children}</div>
+  ),
+}));
+
+describe('AppProviders', () => {
+  it('renders children correctly', () => {
+    render(
+      <AppProviders>
+        <div data-testid="test-child">Test Child</div>
+      </AppProviders>,
+    );
+
+    expect(screen.getByTestId('test-child')).toBeInTheDocument();
+    expect(screen.getByText('Test Child')).toBeInTheDocument();
+  });
+
+  it('renders providers in the correct nesting order', () => {
+    render(
+      <AppProviders>
+        <div data-testid="test-child">Test Child</div>
+      </AppProviders>,
+    );
+
+    const modalProvider = screen.getByTestId('modal-provider');
+    const authProvider = screen.getByTestId('auth-provider');
+    const flyersProvider = screen.getByTestId('flyers-provider');
+    const masterItemsProvider = screen.getByTestId('master-items-provider');
+    const userDataProvider = screen.getByTestId('user-data-provider');
+    const child = screen.getByTestId('test-child');
+
+    // Verify nesting structure: Modal -> Auth -> Flyers -> MasterItems -> UserData -> Child
+    expect(modalProvider).toContainElement(authProvider);
+    expect(authProvider).toContainElement(flyersProvider);
+    expect(flyersProvider).toContainElement(masterItemsProvider);
+    expect(masterItemsProvider).toContainElement(userDataProvider);
+    expect(userDataProvider).toContainElement(child);
+  });
+});

src/providers/AuthProvider.test.tsx

@@ -0,0 +1,245 @@
+// src/providers/AuthProvider.test.tsx
+import React, { useContext, useState } from 'react';
+import { render, screen, waitFor, fireEvent, act } from '@testing-library/react';
+import { describe, it, expect, vi, beforeEach, type Mocked } from 'vitest';
+import { AuthProvider } from './AuthProvider';
+import { AuthContext } from '../contexts/AuthContext';
+import * as tokenStorage from '../services/tokenStorage';
+import { createMockUserProfile } from '../tests/utils/mockFactories';
+import * as apiClient from '../services/apiClient';
+
+// Mocks
+// The apiClient is mocked globally in `src/tests/setup/globalApiMock.ts`.
+vi.mock('../services/tokenStorage');
+vi.mock('../services/logger.client', () => ({
+  logger: {
+    info: vi.fn(),
+    warn: vi.fn(),
+    error: vi.fn(),
+    debug: vi.fn(),
+  },
+}));
+
+const mockedApiClient = vi.mocked(apiClient);
+const mockedTokenStorage = tokenStorage as Mocked<typeof tokenStorage>;
+
+const mockProfile = createMockUserProfile({
+  user: { user_id: 'user-123', email: 'test@example.com' },
+});
+
+// A simple consumer component to access and display context values
+const TestConsumer = () => {
+  const context = useContext(AuthContext);
+  const [error, setError] = useState<string | null>(null);
+  if (!context) {
+    return <div>No Context</div>;
+  }
+
+  const handleLoginWithoutProfile = async () => {
+    try {
+      await context.login('test-token-no-profile');
+    } catch (e) {
+      setError(e instanceof Error ? e.message : String(e));
+    }
+  };
+
+  return (
+    <div>
+      <div data-testid="auth-status">{context.authStatus}</div>
+      <div data-testid="user-email">{context.userProfile?.user.email ?? 'No User'}</div>
+      <div data-testid="is-loading">{context.isLoading.toString()}</div>
+      {error && <div data-testid="error-display">{error}</div>}
+      <button onClick={() => context.login('test-token', mockProfile)}>Login with Profile</button>
+      <button onClick={handleLoginWithoutProfile}>Login without Profile</button>
+      <button onClick={context.logout}>Logout</button>
+      <button onClick={() => context.updateProfile({ full_name: 'Updated Name' })}>
+        Update Profile
+      </button>
+    </div>
+  );
+};
+
+const renderWithProvider = () => {
+  return render(
+    <AuthProvider>
+      <TestConsumer />
+    </AuthProvider>,
+  );
+};
+
+describe('AuthProvider', () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  it('should start in "Determining..." state and transition to "SIGNED_OUT" if no token exists', async () => {
+    mockedTokenStorage.getToken.mockReturnValue(null);
+    renderWithProvider();
+
+    // The transition happens synchronously in the effect when no token is present,
+    // so 'Determining...' might be skipped or flashed too quickly for the test runner.
+    // We check that it settles correctly.
+
+    await waitFor(() => {
+      expect(screen.getByTestId('auth-status')).toHaveTextContent('SIGNED_OUT');
+      expect(screen.getByTestId('is-loading')).toHaveTextContent('false');
+    });
+
+    expect(mockedApiClient.getAuthenticatedUserProfile).not.toHaveBeenCalled();
+  });
+
+  it('should transition to "AUTHENTICATED" if a valid token exists', async () => {
+    mockedTokenStorage.getToken.mockReturnValue('valid-token');
+    mockedApiClient.getAuthenticatedUserProfile.mockResolvedValue(
+      new Response(JSON.stringify(mockProfile)),
+    );
+
+    renderWithProvider();
+
+    await waitFor(() => {
+      expect(screen.getByTestId('auth-status')).toHaveTextContent('AUTHENTICATED');
+      expect(screen.getByTestId('user-email')).toHaveTextContent('test@example.com');
+      expect(screen.getByTestId('is-loading')).toHaveTextContent('false');
+    });
+
+    expect(mockedApiClient.getAuthenticatedUserProfile).toHaveBeenCalledTimes(1);
+  });
+
+  it('should handle token validation failure by signing out', async () => {
+    mockedTokenStorage.getToken.mockReturnValue('invalid-token');
+    mockedApiClient.getAuthenticatedUserProfile.mockRejectedValue(new Error('Invalid Token'));
+
+    renderWithProvider();
+
+    await waitFor(() => {
+      expect(screen.getByTestId('auth-status')).toHaveTextContent('SIGNED_OUT');
+    });
+
+    expect(mockedTokenStorage.removeToken).toHaveBeenCalled();
+  });
+
+  it('should handle a valid token that returns no profile by signing out', async () => {
+    // This test covers lines 51-55
+    mockedTokenStorage.getToken.mockReturnValue('valid-token-no-profile');
+    mockedApiClient.getAuthenticatedUserProfile.mockResolvedValue(
+      new Response(JSON.stringify(null)),
+    );
+
+    renderWithProvider();
+
+    expect(screen.getByTestId('auth-status')).toHaveTextContent('Determining...');
+
+    await waitFor(() => {
+      expect(screen.getByTestId('auth-status')).toHaveTextContent('SIGNED_OUT');
+    });
+
+    expect(mockedTokenStorage.removeToken).toHaveBeenCalled();
+    expect(screen.getByTestId('user-email')).toHaveTextContent('No User');
+    expect(screen.getByTestId('is-loading')).toHaveTextContent('false');
+  });
+
+  it('should log in a user with provided profile data', async () => {
+    mockedTokenStorage.getToken.mockReturnValue(null);
+    renderWithProvider();
+    await waitFor(() => expect(screen.getByTestId('auth-status')).toHaveTextContent('SIGNED_OUT'));
+
+    const loginButton = screen.getByRole('button', { name: 'Login with Profile' });
+    await act(async () => {
+      fireEvent.click(loginButton);
+    });
+
+    expect(mockedTokenStorage.setToken).toHaveBeenCalledWith('test-token');
+    expect(screen.getByTestId('auth-status')).toHaveTextContent('AUTHENTICATED');
+    expect(screen.getByTestId('user-email')).toHaveTextContent('test@example.com');
+    // API should not be called if profile is provided
+    expect(mockedApiClient.getAuthenticatedUserProfile).not.toHaveBeenCalled();
+  });
+
+  it('should log in a user and fetch profile if not provided', async () => {
+    mockedTokenStorage.getToken.mockReturnValue(null);
+    mockedApiClient.getAuthenticatedUserProfile.mockResolvedValue(
+      new Response(JSON.stringify(mockProfile)),
+    );
+    renderWithProvider();
+    await waitFor(() => expect(screen.getByTestId('auth-status')).toHaveTextContent('SIGNED_OUT'));
+
+    const loginButton = screen.getByRole('button', { name: 'Login without Profile' });
+    await act(async () => {
+      fireEvent.click(loginButton);
+    });
+
+    await waitFor(() => {
+      expect(screen.getByTestId('auth-status')).toHaveTextContent('AUTHENTICATED');
+      expect(screen.getByTestId('user-email')).toHaveTextContent('test@example.com');
+    });
+
+    expect(mockedTokenStorage.setToken).toHaveBeenCalledWith('test-token-no-profile');
+    expect(mockedApiClient.getAuthenticatedUserProfile).toHaveBeenCalledTimes(1);
+  });
+
+  it('should throw an error and log out if profile fetch fails after login', async () => {
+    // This test covers lines 109-111
+    mockedTokenStorage.getToken.mockReturnValue(null);
+    const fetchError = new Error('API is down');
+    mockedApiClient.getAuthenticatedUserProfile.mockRejectedValue(fetchError);
+
+    renderWithProvider();
+
+    await waitFor(() => {
+      expect(screen.getByTestId('auth-status')).toHaveTextContent('SIGNED_OUT');
+    });
+
+    const loginButton = screen.getByRole('button', { name: 'Login without Profile' });
+
+    // Click the button that triggers the failing login
+    fireEvent.click(loginButton);
+
+    // After the error is thrown, the state should be rolled back
+    await waitFor(() => {
+      // The error is now caught and displayed by the TestConsumer
+      expect(screen.getByTestId('error-display')).toHaveTextContent(
+        'Login succeeded, but failed to fetch your data: Received null or undefined profile from API.',
+      );
+
+      expect(mockedTokenStorage.setToken).toHaveBeenCalledWith('test-token-no-profile');
+      expect(mockedTokenStorage.removeToken).toHaveBeenCalled();
+      expect(screen.getByTestId('auth-status')).toHaveTextContent('SIGNED_OUT');
+    });
+  });
+
+  it('should log out the user', async () => {
+    mockedTokenStorage.getToken.mockReturnValue('valid-token');
+    mockedApiClient.getAuthenticatedUserProfile.mockResolvedValue(
+      new Response(JSON.stringify(mockProfile)),
+    );
+    renderWithProvider();
+    await waitFor(() => expect(screen.getByTestId('auth-status')).toHaveTextContent('AUTHENTICATED'));
+
+    const logoutButton = screen.getByRole('button', { name: 'Logout' });
+    fireEvent.click(logoutButton);
+
+    expect(screen.getByTestId('auth-status')).toHaveTextContent('SIGNED_OUT');
+    expect(screen.getByTestId('user-email')).toHaveTextContent('No User');
+    expect(mockedTokenStorage.removeToken).toHaveBeenCalled();
+  });
+
+  it('should update the user profile', async () => {
+    mockedTokenStorage.getToken.mockReturnValue('valid-token');
+    mockedApiClient.getAuthenticatedUserProfile.mockResolvedValue(
+      new Response(JSON.stringify(mockProfile)),
+    );
+    renderWithProvider();
+    await waitFor(() => expect(screen.getByTestId('auth-status')).toHaveTextContent('AUTHENTICATED'));
+
+    const updateButton = screen.getByRole('button', { name: 'Update Profile' });
+    fireEvent.click(updateButton);
+
+    await waitFor(() => {
+      // The profile object is internal, so we can't directly check it.
+      // A good proxy is to see if a component that uses it would re-render.
+      // Since our consumer doesn't display the name, we just confirm the function was called.
+      // In a real app, we'd check the updated UI element.
+      expect(screen.getByTestId('auth-status')).toHaveTextContent('AUTHENTICATED');
+    });
+  });
+});

src/routes/passport.routes.test.ts

@@ -482,8 +482,8 @@ describe('Passport Configuration', () => {
       const mockReq: Partial<Request> = {
         // An object that is not a valid UserProfile (e.g., missing 'role')
         user: {
-          user_id: 'invalid-user-id',
-        } as any,
+          user: { user_id: 'invalid-user-id' }, // Missing 'role' property
+        } as unknown as UserProfile, // Cast to UserProfile to satisfy req.user type, but it's intentionally malformed
       };
 
       // Act

src/routes/recipe.routes.ts

@@ -2,6 +2,8 @@
 import { Router } from 'express';
 import { z } from 'zod';
 import * as db from '../services/db/index.db';
+import { aiService } from '../services/aiService.server';
+import passport from './passport.routes';
 import { validateRequest } from '../middleware/validation.middleware';
 import { requiredString, numericIdParam, optionalNumeric } from '../utils/zodUtils';
 
@@ -28,6 +30,12 @@ const byIngredientAndTagSchema = z.object({
 
 const recipeIdParamsSchema = numericIdParam('recipeId');
 
+const suggestRecipeSchema = z.object({
+  body: z.object({
+    ingredients: z.array(z.string().min(1)).nonempty('At least one ingredient is required.'),
+  }),
+});
+
 /**
  * GET /api/recipes/by-sale-percentage - Get recipes based on the percentage of their ingredients on sale.
  */
@@ -121,4 +129,31 @@ router.get('/:recipeId', validateRequest(recipeIdParamsSchema), async (req, res,
   }
 });
 
+/**
+ * POST /api/recipes/suggest - Generates a simple recipe suggestion from a list of ingredients.
+ * This is a protected endpoint.
+ */
+router.post(
+  '/suggest',
+  passport.authenticate('jwt', { session: false }),
+  validateRequest(suggestRecipeSchema),
+  async (req, res, next) => {
+    try {
+      const { body } = req as unknown as z.infer<typeof suggestRecipeSchema>;
+      const suggestion = await aiService.generateRecipeSuggestion(body.ingredients, req.log);
+
+      if (!suggestion) {
+        return res
+          .status(503)
+          .json({ message: 'AI service is currently unavailable or failed to generate a suggestion.' });
+      }
+
+      res.json({ suggestion });
+    } catch (error) {
+      req.log.error({ error }, 'Error generating recipe suggestion');
+      next(error);
+    }
+  },
+);
+
 export default router;

src/routes/user.routes.test.ts

@@ -482,6 +482,12 @@ describe('User Routes (/api/users)', () => {
 
         expect(response.status).toBe(201);
         expect(response.body).toEqual(mockAddedItem);
+        expect(db.shoppingRepo.addShoppingListItem).toHaveBeenCalledWith(
+          listId,
+          mockUserProfile.user.user_id,
+          itemData,
+          expectLogger,
+        );
       });
 
       it('should return 400 on foreign key error when adding an item', async () => {
@@ -519,6 +525,12 @@ describe('User Routes (/api/users)', () => {
 
         expect(response.status).toBe(200);
         expect(response.body).toEqual(mockUpdatedItem);
+        expect(db.shoppingRepo.updateShoppingListItem).toHaveBeenCalledWith(
+          itemId,
+          mockUserProfile.user.user_id,
+          updates,
+          expectLogger,
+        );
       });
 
       it('should return 404 if item to update is not found', async () => {
@@ -554,6 +566,11 @@ describe('User Routes (/api/users)', () => {
           vi.mocked(db.shoppingRepo.removeShoppingListItem).mockResolvedValue(undefined);
           const response = await supertest(app).delete('/api/users/shopping-lists/items/101');
           expect(response.status).toBe(204);
+          expect(db.shoppingRepo.removeShoppingListItem).toHaveBeenCalledWith(
+            101,
+            mockUserProfile.user.user_id,
+            expectLogger,
+          );
         });
 
         it('should return 404 if item to delete is not found', async () => {

src/routes/user.routes.ts

@@ -478,10 +478,16 @@ router.post(
   validateRequest(addShoppingListItemSchema),
   async (req, res, next: NextFunction) => {
     logger.debug(`[ROUTE] POST /api/users/shopping-lists/:listId/items - ENTER`);
+    const userProfile = req.user as UserProfile;
     // Apply ADR-003 pattern for type safety
     const { params, body } = req as unknown as AddShoppingListItemRequest;
     try {
-      const newItem = await db.shoppingRepo.addShoppingListItem(params.listId, body, req.log);
+      const newItem = await db.shoppingRepo.addShoppingListItem(
+        params.listId,
+        userProfile.user.user_id,
+        body,
+        req.log,
+      );
       res.status(201).json(newItem);
     } catch (error) {
       if (error instanceof ForeignKeyConstraintError) {
@@ -512,11 +518,13 @@ router.put(
   validateRequest(updateShoppingListItemSchema),
   async (req, res, next: NextFunction) => {
     logger.debug(`[ROUTE] PUT /api/users/shopping-lists/items/:itemId - ENTER`);
+    const userProfile = req.user as UserProfile;
     // Apply ADR-003 pattern for type safety
     const { params, body } = req as unknown as UpdateShoppingListItemRequest;
     try {
       const updatedItem = await db.shoppingRepo.updateShoppingListItem(
         params.itemId,
+        userProfile.user.user_id,
         body,
         req.log,
       );
@@ -541,10 +549,11 @@ router.delete(
   validateRequest(shoppingListItemIdSchema),
   async (req, res, next: NextFunction) => {
     logger.debug(`[ROUTE] DELETE /api/users/shopping-lists/items/:itemId - ENTER`);
+    const userProfile = req.user as UserProfile;
     // Apply ADR-003 pattern for type safety
     const { params } = req as unknown as DeleteShoppingListItemRequest;
     try {
-      await db.shoppingRepo.removeShoppingListItem(params.itemId, req.log);
+      await db.shoppingRepo.removeShoppingListItem(params.itemId, userProfile.user.user_id, req.log);
       res.status(204).send();
     } catch (error: unknown) {
       logger.error(

src/services/aiService.server.test.ts

@@ -1,5 +1,6 @@
 // src/services/aiService.server.test.ts
 import { describe, it, expect, vi, beforeEach, afterEach, type Mock } from 'vitest';
+import type { Job } from 'bullmq';
 import { createMockLogger } from '../tests/utils/mockLogger';
 import type { Logger } from 'pino';
 import type { FlyerStatus, MasterGroceryItem, UserProfile } from '../types';
@@ -10,7 +11,7 @@ import {
   DuplicateFlyerError,
   type RawFlyerItem,
 } from './aiService.server';
-import { createMockMasterGroceryItem } from '../tests/utils/mockFactories';
+import { createMockMasterGroceryItem, createMockFlyer } from '../tests/utils/mockFactories';
 import { ValidationError } from './db/errors.db';
 import { AiFlyerDataSchema } from '../types/ai';
 
@@ -113,6 +114,7 @@ describe('AI Service (Server)', () => {
     // Restore all environment variables and clear all mocks before each test
     vi.restoreAllMocks();
     vi.clearAllMocks();
+    mockGenerateContent.mockReset();
     // Reset modules to ensure the service re-initializes with the mocks
 
     mockAiClient.generateContent.mockResolvedValue({
@@ -241,6 +243,7 @@ describe('AI Service (Server)', () => {
       vi.unstubAllEnvs();
       process.env = { ...originalEnv, GEMINI_API_KEY: 'test-key' };
       vi.resetModules(); // Re-import to use the new env var and re-instantiate the service
+      mockGenerateContent.mockReset();
     });
 
     afterEach(() => {
@@ -319,41 +322,174 @@ describe('AI Service (Server)', () => {
       const { logger } = await import('./logger.server');
       const serviceWithFallback = new AIService(logger);
 
-      const quotaError1 = new Error('Quota exhausted for model 1');
-      const quotaError2 = new Error('429 Too Many Requests for model 2');
-      const quotaError3 = new Error('RESOURCE_EXHAUSTED for model 3');
+      // Access private property for testing purposes to ensure test stays in sync with implementation
+      const models = (serviceWithFallback as any).models as string[];
+      // Use a quota error to trigger the fallback logic for each model
+      const errors = models.map((model, i) => new Error(`Quota error for model ${model} (${i})`));
+      const lastError = errors[errors.length - 1];
 
-      mockGenerateContent
-        .mockRejectedValueOnce(quotaError1)
-        .mockRejectedValueOnce(quotaError2)
-        .mockRejectedValueOnce(quotaError3);
+      // Dynamically setup mocks
+      errors.forEach((err) => {
+        mockGenerateContent.mockRejectedValueOnce(err);
+      });
 
       const request = { contents: [{ parts: [{ text: 'test prompt' }] }] };
 
       // Act & Assert
       await expect((serviceWithFallback as any).aiClient.generateContent(request)).rejects.toThrow(
-        quotaError3,
+        lastError,
       );
 
-      expect(mockGenerateContent).toHaveBeenCalledTimes(3);
-      expect(mockGenerateContent).toHaveBeenNthCalledWith(1, { // The first model in the list is now 'gemini-3-flash-preview'
-        model: 'gemini-3-flash-preview',
-        ...request,
-      });
-      expect(mockGenerateContent).toHaveBeenNthCalledWith(2, { // The second model in the list is 'gemini-2.5-flash'
-        model: 'gemini-2.5-flash',
-        ...request,
-      });
-      expect(mockGenerateContent).toHaveBeenNthCalledWith(3, { // The third model in the list is 'gemini-2.5-flash-lite'
-        model: 'gemini-2.5-flash-lite',
-        ...request,
+      expect(mockGenerateContent).toHaveBeenCalledTimes(models.length);
+
+      models.forEach((model, index) => {
+        expect(mockGenerateContent).toHaveBeenNthCalledWith(index + 1, {
+          model: model,
+          ...request,
+        });
       });
 
       expect(logger.error).toHaveBeenCalledWith(
-        { lastError: quotaError3 },
+        { lastError },
         '[AIService Adapter] All AI models failed. Throwing last known error.',
       );
     });
+
+    it('should use lite models and throw the last error if all lite models fail', async () => {
+      // Arrange
+      const { AIService } = await import('./aiService.server');
+      const { logger } = await import('./logger.server');
+      // We instantiate with the real logger to test the production fallback logic
+      const serviceWithFallback = new AIService(logger);
+
+      // Access private property for testing purposes
+      const modelsLite = (serviceWithFallback as any).models_lite as string[];
+      // Use a quota error to trigger the fallback logic for each model
+      const errors = modelsLite.map((model, i) => new Error(`Quota error for lite model ${model} (${i})`));
+      const lastError = errors[errors.length - 1];
+
+      // Dynamically setup mocks
+      errors.forEach((err) => {
+        mockGenerateContent.mockRejectedValueOnce(err);
+      });
+
+      const request = {
+        contents: [{ parts: [{ text: 'test prompt' }] }],
+        useLiteModels: true, // This is the key to trigger the lite model list
+      };
+      // The adapter strips `useLiteModels` before calling the underlying client,
+      // so we prepare the expected request shape for our assertions.
+      const { useLiteModels, ...apiReq } = request;
+
+      // Act & Assert
+      // Expect the entire operation to reject with the error from the very last model attempt.
+      await expect((serviceWithFallback as any).aiClient.generateContent(request)).rejects.toThrow(
+        lastError,
+      );
+
+      // Verify that all lite models were attempted in the correct order.
+      expect(mockGenerateContent).toHaveBeenCalledTimes(modelsLite.length);
+
+      modelsLite.forEach((model, index) => {
+        expect(mockGenerateContent).toHaveBeenNthCalledWith(index + 1, {
+          model: model,
+          ...apiReq,
+        });
+      });
+    });
+
+    it('should dynamically try the next model if the first one fails and succeed if the second one works', async () => {
+      // Arrange
+      const { AIService } = await import('./aiService.server');
+      const { logger } = await import('./logger.server');
+      const serviceWithFallback = new AIService(logger);
+
+      // Access private property for testing purposes
+      const models = (serviceWithFallback as any).models as string[];
+      // Ensure we have enough models to test fallback
+      expect(models.length).toBeGreaterThanOrEqual(2);
+
+      const error1 = new Error('Quota exceeded for model 1');
+      const successResponse = { text: 'Success', candidates: [] };
+
+      mockGenerateContent
+        .mockRejectedValueOnce(error1)
+        .mockResolvedValueOnce(successResponse);
+
+      const request = { contents: [{ parts: [{ text: 'test prompt' }] }] };
+
+      // Act
+      const result = await (serviceWithFallback as any).aiClient.generateContent(request);
+
+      // Assert
+      expect(result).toEqual(successResponse);
+      expect(mockGenerateContent).toHaveBeenCalledTimes(2);
+
+      expect(mockGenerateContent).toHaveBeenNthCalledWith(1, {
+        model: models[0],
+        ...request,
+      });
+      expect(mockGenerateContent).toHaveBeenNthCalledWith(2, {
+        model: models[1],
+        ...request,
+      });
+
+      expect(logger.warn).toHaveBeenCalledWith(
+        expect.stringContaining(`Model '${models[0]}' failed`),
+      );
+    });
+
+    it('should retry on a 429 error and succeed on the next model', async () => {
+      // Arrange
+      const { AIService } = await import('./aiService.server');
+      const { logger } = await import('./logger.server');
+      const serviceWithFallback = new AIService(logger);
+      const models = (serviceWithFallback as any).models as string[];
+
+      const retriableError = new Error('429 Too Many Requests');
+      const successResponse = { text: 'Success from second model', candidates: [] };
+
+      mockGenerateContent
+        .mockRejectedValueOnce(retriableError)
+        .mockResolvedValueOnce(successResponse);
+
+      const request = { contents: [{ parts: [{ text: 'test prompt' }] }] };
+
+      // Act
+      const result = await (serviceWithFallback as any).aiClient.generateContent(request);
+
+      // Assert
+      expect(result).toEqual(successResponse);
+      expect(mockGenerateContent).toHaveBeenCalledTimes(2);
+      expect(mockGenerateContent).toHaveBeenNthCalledWith(1, { model: models[0], ...request });
+      expect(mockGenerateContent).toHaveBeenNthCalledWith(2, { model: models[1], ...request });
+      expect(logger.warn).toHaveBeenCalledWith(expect.stringContaining(`Model '${models[0]}' failed due to quota/rate limit.`));
+    });
+
+    it('should fail immediately on a 400 Bad Request error without retrying', async () => {
+      // Arrange
+      const { AIService } = await import('./aiService.server');
+      const { logger } = await import('./logger.server');
+      const serviceWithFallback = new AIService(logger);
+      const models = (serviceWithFallback as any).models as string[];
+
+      const nonRetriableError = new Error('400 Bad Request: Invalid input');
+      mockGenerateContent.mockRejectedValueOnce(nonRetriableError);
+
+      const request = { contents: [{ parts: [{ text: 'test prompt' }] }] };
+
+      // Act & Assert
+      await expect((serviceWithFallback as any).aiClient.generateContent(request)).rejects.toThrow(nonRetriableError);
+
+      expect(mockGenerateContent).toHaveBeenCalledTimes(1);
+      expect(mockGenerateContent).toHaveBeenCalledWith({ model: models[0], ...request });
+      expect(logger.error).toHaveBeenCalledWith(
+        { error: nonRetriableError },
+        `[AIService Adapter] Model '${models[0]}' failed with a non-retriable error.`,
+      );
+      // Ensure it didn't log a warning about trying the next model
+      expect(logger.warn).not.toHaveBeenCalledWith(expect.stringContaining('Trying next model'));
+    });
   });
 
   describe('extractItemsFromReceiptImage', () => {
@@ -783,7 +919,7 @@ describe('AI Service (Server)', () => {
     } as UserProfile;
 
     it('should throw DuplicateFlyerError if flyer already exists', async () => {
-      vi.mocked(dbModule.flyerRepo.findFlyerByChecksum).mockResolvedValue({ flyer_id: 99 } as any);
+      vi.mocked(dbModule.flyerRepo.findFlyerByChecksum).mockResolvedValue({ flyer_id: 99, checksum: 'checksum123', file_name: 'test.pdf', image_url: '/flyer-images/test.pdf', icon_url: '/flyer-images/icons/test.webp', store_id: 1, status: 'processed', item_count: 0, created_at: new Date().toISOString(), updated_at: new Date().toISOString() });
 
       await expect(
         aiServiceInstance.enqueueFlyerProcessing(
@@ -798,7 +934,7 @@ describe('AI Service (Server)', () => {
 
     it('should enqueue job with user address if profile exists', async () => {
       vi.mocked(dbModule.flyerRepo.findFlyerByChecksum).mockResolvedValue(undefined);
-      vi.mocked(flyerQueue.add).mockResolvedValue({ id: 'job123' } as any);
+      vi.mocked(flyerQueue.add).mockResolvedValue({ id: 'job123' } as unknown as Job);
 
       const result = await aiServiceInstance.enqueueFlyerProcessing(
         mockFile,
@@ -821,7 +957,7 @@ describe('AI Service (Server)', () => {
 
     it('should enqueue job without address if profile is missing', async () => {
       vi.mocked(dbModule.flyerRepo.findFlyerByChecksum).mockResolvedValue(undefined);
-      vi.mocked(flyerQueue.add).mockResolvedValue({ id: 'job456' } as any);
+      vi.mocked(flyerQueue.add).mockResolvedValue({ id: 'job456' } as unknown as Job);
 
       await aiServiceInstance.enqueueFlyerProcessing(
         mockFile,
@@ -850,7 +986,7 @@ describe('AI Service (Server)', () => {
     const mockProfile = { user: { user_id: 'u1' } } as UserProfile;
 
     beforeEach(() => {
-      // Default success mocks
+      // Default success mocks. Use createMockFlyer for a more complete mock.
       vi.mocked(dbModule.flyerRepo.findFlyerByChecksum).mockResolvedValue(undefined);
       vi.mocked(generateFlyerIcon).mockResolvedValue('icon.jpg');
       vi.mocked(createFlyerAndItems).mockResolvedValue({
@@ -887,7 +1023,7 @@ describe('AI Service (Server)', () => {
     });
 
     it('should throw DuplicateFlyerError if checksum exists', async () => {
-      vi.mocked(dbModule.flyerRepo.findFlyerByChecksum).mockResolvedValue({ flyer_id: 55 } as any);
+      vi.mocked(dbModule.flyerRepo.findFlyerByChecksum).mockResolvedValue(createMockFlyer({ flyer_id: 55 }));
       const body = { checksum: 'dup-sum' };
 
       await expect(

src/services/aiService.server.ts

@@ -62,6 +62,7 @@ interface IAiClient {
   generateContent(request: {
     contents: Content[];
     tools?: Tool[];
+    useLiteModels?: boolean;
   }): Promise<GenerateContentResponse>;
 }
 
@@ -93,7 +94,8 @@ export class AIService {
   // The fallback list is ordered by preference (speed/cost vs. power).
   // We try the fastest models first, then the more powerful 'pro' model as a high-quality fallback,
   // and finally the 'lite' model as a last resort.
-  private readonly models = [ 'gemini-3-flash-preview', 'gemini-2.5-flash', 'gemini-2.5-flash-lite'];
+  private readonly models = [ 'gemini-3-flash-preview', 'gemini-2.5-flash', 'gemini-2.5-flash-lite', 'gemma-3-27b', 'gemma-3-12b'];
+  private readonly models_lite = ["gemma-3-4b", "gemma-3-2b", "gemma-3-1b"];
 
   constructor(logger: Logger, aiClient?: IAiClient, fs?: IFileSystem) {
     this.logger = logger;
@@ -156,7 +158,9 @@ export class AIService {
                 throw new Error('AIService.generateContent requires at least one content element.');
               }
 
-              return this._generateWithFallback(genAI, request);
+              const { useLiteModels, ...apiReq } = request;
+              const models = useLiteModels ? this.models_lite : this.models;
+              return this._generateWithFallback(genAI, apiReq, models);
             },
           }
         : {
@@ -194,10 +198,11 @@ export class AIService {
   private async _generateWithFallback(
     genAI: GoogleGenAI,
     request: { contents: Content[]; tools?: Tool[] },
+    models: string[] = this.models,
   ): Promise<GenerateContentResponse> {
     let lastError: Error | null = null;
 
-    for (const modelName of this.models) {
+    for (const modelName of models) {
       try {
         this.logger.info(
           `[AIService Adapter] Attempting to generate content with model: ${modelName}`,
@@ -668,6 +673,33 @@ export class AIService {
     }
   }
 
+  /**
+   * Generates a simple recipe suggestion based on a list of ingredients.
+   * Uses the 'lite' models for faster/cheaper generation.
+   * @param ingredients List of available ingredients.
+   * @param logger Logger instance.
+   * @returns The recipe suggestion text.
+   */
+  async generateRecipeSuggestion(
+    ingredients: string[],
+    logger: Logger = this.logger,
+  ): Promise<string | null> {
+    const prompt = `Suggest a simple recipe using these ingredients: ${ingredients.join(', ')}. Keep it brief.`;
+
+    try {
+      const result = await this.rateLimiter(() =>
+        this.aiClient.generateContent({
+          contents: [{ parts: [{ text: prompt }] }],
+          useLiteModels: true,
+        }),
+      );
+      return result.text || null;
+    } catch (error) {
+      logger.error({ err: error }, 'Failed to generate recipe suggestion');
+      return null;
+    }
+  }
+
   /**
    * SERVER-SIDE FUNCTION
    * Uses Google Maps grounding to find nearby stores and plan a shopping trip.

src/services/apiClient.test.ts

@@ -543,6 +543,13 @@ describe('API Client', () => {
       await apiClient.deleteRecipe(recipeId);
       expect(capturedUrl?.pathname).toBe(`/api/recipes/${recipeId}`);
     });
+
+    it('suggestRecipe should send a POST request with ingredients', async () => {
+      const ingredients = ['chicken', 'rice'];
+      await apiClient.suggestRecipe(ingredients);
+      expect(capturedUrl?.pathname).toBe('/api/recipes/suggest');
+      expect(capturedBody).toEqual({ ingredients });
+    });
   });
 
   describe('User Profile and Settings API Functions', () => {
@@ -933,7 +940,7 @@ describe('API Client', () => {
 
     it('logSearchQuery should send a POST request with query data', async () => {
       const queryData = createMockSearchQueryPayload({ query_text: 'apples', result_count: 10, was_successful: true });
-      await apiClient.logSearchQuery(queryData);
+      await apiClient.logSearchQuery(queryData as any);
       expect(capturedUrl?.pathname).toBe('/api/search/log');
       expect(capturedBody).toEqual(queryData);
     });
@@ -960,7 +967,7 @@ describe('API Client', () => {
         result_count: 0,
         was_successful: false,
       });
-      await apiClient.logSearchQuery(queryData);
+      await apiClient.logSearchQuery(queryData as any);
       expect(logger.warn).toHaveBeenCalledWith('Failed to log search query', { error: apiError });
     });
   });

src/services/apiClient.ts

@@ -636,6 +636,20 @@ export const addRecipeComment = (
 ): Promise<Response> =>
   authedPost(`/recipes/${recipeId}/comments`, { content, parentCommentId }, { tokenOverride });
 
+/**
+ * Requests a simple recipe suggestion from the AI based on a list of ingredients.
+ * @param ingredients An array of ingredient strings.
+ * @param tokenOverride Optional token for testing.
+ * @returns A promise that resolves to the API response containing the suggestion.
+ */
+export const suggestRecipe = (
+  ingredients: string[],
+  tokenOverride?: string,
+): Promise<Response> => {
+  // This is a protected endpoint, so we use authedPost.
+  return authedPost('/recipes/suggest', { ingredients }, { tokenOverride });
+};
+
 /**
  * Deletes a recipe.
  * @param recipeId The ID of the recipe to delete.

src/services/authService.test.ts

@@ -17,6 +17,11 @@ describe('AuthService', () => {
     user_id: 'user-123',
     email: 'test@example.com',
     password_hash: 'hashed-password',
+    failed_login_attempts: 0,
+    last_failed_login: null,
+    created_at: new Date().toISOString(),
+    updated_at: new Date().toISOString(),
+    refresh_token: null,
   };
   const mockUserProfile: UserProfile = {
     user: mockUser,
@@ -205,7 +210,7 @@ describe('AuthService', () => {
 
   describe('resetPassword', () => {
     it('should process password reset for existing user', async () => {
-      vi.mocked(userRepo.findUserByEmail).mockResolvedValue(mockUser as any);
+      vi.mocked(userRepo.findUserByEmail).mockResolvedValue(mockUser);
       vi.mocked(bcrypt.hash).mockImplementation(async () => 'hashed-token');
 
       const result = await authService.resetPassword('test@example.com', reqLog);
@@ -284,7 +289,7 @@ describe('AuthService', () => {
 
   describe('getUserByRefreshToken', () => {
     it('should return user profile if token exists', async () => {
-      vi.mocked(userRepo.findUserByRefreshToken).mockResolvedValue({ user_id: 'user-123' } as any);
+      vi.mocked(userRepo.findUserByRefreshToken).mockResolvedValue({ user_id: 'user-123', email: 'test@example.com', created_at: new Date().toISOString(), updated_at: new Date().toISOString() });
       vi.mocked(userRepo.findUserProfileById).mockResolvedValue(mockUserProfile);
 
       const result = await authService.getUserByRefreshToken('valid-token', reqLog);
@@ -318,7 +323,7 @@ describe('AuthService', () => {
 
   describe('refreshAccessToken', () => {
     it('should return new access token if user found', async () => {
-      vi.mocked(userRepo.findUserByRefreshToken).mockResolvedValue({ user_id: 'user-123' } as any);
+      vi.mocked(userRepo.findUserByRefreshToken).mockResolvedValue({ user_id: 'user-123', email: 'test@example.com', created_at: new Date().toISOString(), updated_at: new Date().toISOString() });
       vi.mocked(userRepo.findUserProfileById).mockResolvedValue(mockUserProfile);
       // FIX: The global mock for jsonwebtoken provides a `default` export.
       // The code under test (`authService`) uses `import jwt from 'jsonwebtoken'`, so it gets the default export.

src/services/db/admin.db.test.ts

@@ -203,7 +203,11 @@ describe('Admin DB Service', () => {
         .mockRejectedValueOnce(new Error('DB Read Error'));
 
       // The Promise.all should reject, and the function should re-throw the error
-      await expect(adminRepo.getApplicationStats(mockLogger)).rejects.toThrow('DB Read Error');
+      // The handleDbError function wraps the original error in a new one with a default message,
+      // so we should test for that specific message.
+      await expect(adminRepo.getApplicationStats(mockLogger)).rejects.toThrow(
+        'Failed to retrieve application statistics.',
+      );
       expect(mockLogger.error).toHaveBeenCalledWith(
         { err: expect.any(Error) },
         'Database error in getApplicationStats',
@@ -277,7 +281,7 @@ describe('Admin DB Service', () => {
         'Failed to get most frequent sale items.',
       );
       expect(mockLogger.error).toHaveBeenCalledWith(
-        { err: dbError },
+        { err: dbError, days: 30, limit: 10 },
         'Database error in getMostFrequentSaleItems',
       );
     });
@@ -688,7 +692,9 @@ describe('Admin DB Service', () => {
     it('should re-throw a generic error if the database query fails for other reasons', async () => {
       const dbError = new Error('DB Error');
       mockDb.query.mockRejectedValue(dbError);
-      await expect(adminRepo.updateUserRole('1', 'admin', mockLogger)).rejects.toThrow('DB Error');
+      await expect(adminRepo.updateUserRole('1', 'admin', mockLogger)).rejects.toThrow(
+        'Failed to update user role.',
+      );
       expect(mockLogger.error).toHaveBeenCalledWith(
         { err: dbError, userId: '1', role: 'admin' },
         'Database error in updateUserRole',

src/services/db/budget.db.test.ts

@@ -249,6 +249,17 @@ describe('Budget DB Service', () => {
       expect(result).toEqual(mockUpdatedBudget);
     });
 
+    it('should prevent a user from updating a budget they do not own', async () => {
+      // Arrange: Mock the query to return 0 rows affected
+      mockDb.query.mockResolvedValue({ rows: [], rowCount: 0 });
+
+      // Act & Assert: Attempt to update with a different user ID should throw an error.
+      await expect(
+        budgetRepo.updateBudget(1, 'another-user', { name: 'Updated Groceries' }, mockLogger),
+      ).rejects.toThrow('Budget not found or user does not have permission to update.');
+    });
+
+
     it('should throw an error if no rows are updated', async () => {
       // Arrange: Mock the query to return 0 rows affected
       mockDb.query.mockResolvedValue({ rows: [], rowCount: 0 });

src/services/db/deals.db.test.ts

@@ -82,15 +82,15 @@ describe('Deals DB Service', () => {
       expect(result).toEqual([]);
     });
 
-    it('should re-throw the error if the database query fails', async () => {
+    it('should throw a generic error if the database query fails', async () => {
       const dbError = new Error('DB Connection Error');
       mockDb.query.mockRejectedValue(dbError);
 
       await expect(dealsRepo.findBestPricesForWatchedItems('user-1', mockLogger)).rejects.toThrow(
-        dbError,
+        'Failed to find best prices for watched items.',
       );
       expect(mockLogger.error).toHaveBeenCalledWith(
-        { err: dbError },
+        { err: dbError, userId: 'user-1' },
         'Database error in findBestPricesForWatchedItems',
       );
     });

src/services/db/flyer.db.test.ts

@@ -274,7 +274,7 @@ describe('Flyer DB Service', () => {
         ForeignKeyConstraintError,
       );
       await expect(flyerRepo.insertFlyerItems(999, itemsData, mockLogger)).rejects.toThrow(
-        'The specified flyer does not exist.',
+        'The specified flyer, category, master item, or product does not exist.',
       );
       expect(mockLogger.error).toHaveBeenCalledWith(
         { err: dbError, flyerId: 999 },
@@ -285,10 +285,10 @@ describe('Flyer DB Service', () => {
     it('should throw a generic error if the database query fails', async () => {
       const dbError = new Error('DB Connection Error');
       mockPoolInstance.query.mockRejectedValue(dbError);
-      // The implementation now re-throws the original error, so we should expect that.
+      // The implementation wraps the error using handleDbError
       await expect(
         flyerRepo.insertFlyerItems(1, [{ item: 'Test' } as FlyerItemInsert], mockLogger),
-      ).rejects.toThrow(dbError);
+      ).rejects.toThrow('An unknown error occurred while inserting flyer items.');
       expect(mockLogger.error).toHaveBeenCalledWith(
         { err: dbError, flyerId: 1 },
         'Database error in insertFlyerItems',
@@ -691,11 +691,7 @@ describe('Flyer DB Service', () => {
       );
 
       await expect(flyerRepo.deleteFlyer(999, mockLogger)).rejects.toThrow(
-        'Failed to delete flyer.',
-      );
-      expect(mockLogger.error).toHaveBeenCalledWith(
-        { err: expect.any(NotFoundError), flyerId: 999 },
-        'Database transaction error in deleteFlyer',
+        'Flyer with ID 999 not found.',
       );
     });
 

src/services/db/flyer.db.ts

@@ -97,16 +97,28 @@ export class FlyerRepository {
         flyerData.store_address, // $8
         flyerData.status, // $9
         flyerData.item_count, // $10
-        flyerData.uploaded_by, // $11
+        flyerData.uploaded_by ?? null, // $11
       ];
 
       const result = await this.db.query<Flyer>(query, values);
       return result.rows[0];
     } catch (error) {
+      const errorMessage = error instanceof Error ? error.message : '';
+      let checkMsg = 'A database check constraint failed.';
+
+      if (errorMessage.includes('flyers_checksum_check')) {
+        checkMsg =
+          'The provided checksum is invalid or does not meet format requirements (e.g., must be a 64-character SHA-256 hash).';
+      } else if (errorMessage.includes('flyers_status_check')) {
+        checkMsg = 'Invalid status provided for flyer.';
+      } else if (errorMessage.includes('url_check')) {
+        checkMsg = 'Invalid URL format provided for image or icon.';
+      }
+
       handleDbError(error, logger, 'Database error in insertFlyer', { flyerData }, {
         uniqueMessage: 'A flyer with this checksum already exists.',
         fkMessage: 'The specified user or store for this flyer does not exist.',
-        checkMessage: 'Invalid status provided for flyer.',
+        checkMessage: checkMsg,
         defaultMessage: 'Failed to insert flyer into database.',
       });
     }

src/services/db/notification.db.test.ts

@@ -195,7 +195,7 @@ describe('Notification DB Service', () => {
         notificationRepo.createBulkNotifications(notificationsToCreate, mockLogger),
       ).rejects.toThrow(ForeignKeyConstraintError);
       expect(mockLogger.error).toHaveBeenCalledWith(
-        { err: dbError },
+        { err: dbError, notifications: notificationsToCreate },
         'Database error in createBulkNotifications',
       );
     });
@@ -208,7 +208,7 @@ describe('Notification DB Service', () => {
         notificationRepo.createBulkNotifications(notificationsToCreate, mockLogger),
       ).rejects.toThrow('Failed to create bulk notifications.');
       expect(mockLogger.error).toHaveBeenCalledWith(
-        { err: dbError },
+        { err: dbError, notifications: notificationsToCreate },
         'Database error in createBulkNotifications',
       );
     });
@@ -264,6 +264,16 @@ describe('Notification DB Service', () => {
     });
   });
 
+  describe('markNotificationAsRead - Ownership Check', () => {
+    it('should not mark a notification as read if the user does not own it', async () => {
+      mockPoolInstance.query.mockResolvedValue({ rowCount: 0 });
+
+      await expect(notificationRepo.markNotificationAsRead(1, 'wrong-user', mockLogger)).rejects.toThrow(
+        'Notification not found or user does not have permission.',
+      );
+    });
+  });
+
   describe('markAllNotificationsAsRead', () => {
     it('should execute an UPDATE query to mark all notifications as read for a user', async () => {
       mockPoolInstance.query.mockResolvedValue({ rowCount: 3 });

src/services/db/recipe.db.test.ts

@@ -268,6 +268,17 @@ describe('Recipe DB Service', () => {
       );
     });
   });
+   describe('deleteRecipe - Ownership Check', () => {
+    it('should not delete recipe if the user does not own it and is not an admin', async () => {
+      mockQuery.mockResolvedValue({ rowCount: 0 });
+
+      await expect(recipeRepo.deleteRecipe(1, 'wrong-user', false, mockLogger)).rejects.toThrow(
+        'Recipe not found or user does not have permission to delete.',
+      );
+    });
+
+  });
+
 
   describe('updateRecipe', () => {
     it('should execute an UPDATE query with the correct fields', async () => {
@@ -442,10 +453,6 @@ describe('Recipe DB Service', () => {
       await expect(recipeRepo.forkRecipe('user-123', 1, mockLogger)).rejects.toThrow(
         'Recipe is not public and cannot be forked.',
       );
-      expect(mockLogger.error).toHaveBeenCalledWith(
-        { err: dbError, userId: 'user-123', originalRecipeId: 1 },
-        'Database error in forkRecipe',
-      );
     });
 
     it('should throw a generic error if the database query fails', async () => {

src/services/db/recipe.db.ts

@@ -239,6 +239,10 @@ export class RecipeRepository {
       }
       return res.rows[0];
     } catch (error) {
+      // Explicitly re-throw the "No fields" error before it gets caught by the generic handler.
+      if (error instanceof Error && error.message === 'No fields provided to update.') {
+        throw error;
+      }
       handleDbError(error, logger, 'Database error in updateRecipe', { recipeId, userId, updates }, {
         defaultMessage: 'Failed to update recipe.',
       });

src/services/db/shopping.db.test.ts

@@ -190,13 +190,14 @@ describe('Shopping DB Service', () => {
 
       const result = await shoppingRepo.addShoppingListItem(
         1,
+        'user-1',
         { customItemName: 'Custom Item' },
         mockLogger,
       );
 
       expect(mockPoolInstance.query).toHaveBeenCalledWith(
         expect.stringContaining('INSERT INTO public.shopping_list_items'),
-        [1, null, 'Custom Item'],
+        [1, null, 'Custom Item', 'user-1'],
       );
       expect(result).toEqual(mockItem);
     });
@@ -205,11 +206,11 @@ describe('Shopping DB Service', () => {
       const mockItem = createMockShoppingListItem({ master_item_id: 123 });
       mockPoolInstance.query.mockResolvedValue({ rows: [mockItem] });
 
-      const result = await shoppingRepo.addShoppingListItem(1, { masterItemId: 123 }, mockLogger);
+      const result = await shoppingRepo.addShoppingListItem(1, 'user-1', { masterItemId: 123 }, mockLogger);
 
       expect(mockPoolInstance.query).toHaveBeenCalledWith(
         expect.stringContaining('INSERT INTO public.shopping_list_items'),
-        [1, 123, null],
+        [1, 123, null, 'user-1'],
       );
       expect(result).toEqual(mockItem);
     });
@@ -223,19 +224,20 @@ describe('Shopping DB Service', () => {
 
       const result = await shoppingRepo.addShoppingListItem(
         1,
+        'user-1',
         { masterItemId: 123, customItemName: 'Organic Apples' },
         mockLogger,
       );
 
       expect(mockPoolInstance.query).toHaveBeenCalledWith(
         expect.stringContaining('INSERT INTO public.shopping_list_items'),
-        [1, 123, 'Organic Apples'],
+        [1, 123, 'Organic Apples', 'user-1'],
       );
       expect(result).toEqual(mockItem);
     });
 
     it('should throw an error if both masterItemId and customItemName are missing', async () => {
-      await expect(shoppingRepo.addShoppingListItem(1, {}, mockLogger)).rejects.toThrow(
+      await expect(shoppingRepo.addShoppingListItem(1, 'user-1', {}, mockLogger)).rejects.toThrow(
         'Either masterItemId or customItemName must be provided.',
       );
     });
@@ -244,19 +246,19 @@ describe('Shopping DB Service', () => {
       const dbError = new Error('violates foreign key constraint');
       (dbError as Error & { code: string }).code = '23503';
       mockPoolInstance.query.mockRejectedValue(dbError);
-      await expect(
-        shoppingRepo.addShoppingListItem(999, { masterItemId: 999 }, mockLogger),
-      ).rejects.toThrow('Referenced list or item does not exist.');
+      await expect(shoppingRepo.addShoppingListItem(999, 'user-1', { masterItemId: 999 }, mockLogger)).rejects.toThrow(
+        'Referenced list or item does not exist.',
+      );
     });
 
     it('should throw a generic error if the database query fails', async () => {
       const dbError = new Error('DB Connection Error');
       mockPoolInstance.query.mockRejectedValue(dbError);
       await expect(
-        shoppingRepo.addShoppingListItem(1, { customItemName: 'Test' }, mockLogger),
+        shoppingRepo.addShoppingListItem(1, 'user-1', { customItemName: 'Test' }, mockLogger),
       ).rejects.toThrow('Failed to add item to shopping list.');
       expect(mockLogger.error).toHaveBeenCalledWith(
-        { err: dbError, listId: 1, item: { customItemName: 'Test' } },
+        { err: dbError, listId: 1, userId: 'user-1', item: { customItemName: 'Test' } },
         'Database error in addShoppingListItem',
       );
     });
@@ -269,13 +271,14 @@ describe('Shopping DB Service', () => {
 
       const result = await shoppingRepo.updateShoppingListItem(
         1,
+        'user-1',
         { is_purchased: true },
         mockLogger,
       );
 
       expect(mockPoolInstance.query).toHaveBeenCalledWith(
-        'UPDATE public.shopping_list_items SET is_purchased = $1 WHERE shopping_list_item_id = $2 RETURNING *',
-        [true, 1],
+        expect.stringContaining('UPDATE public.shopping_list_items sli'),
+        [true, 1, 'user-1'],
       );
       expect(result).toEqual(mockItem);
     });
@@ -285,11 +288,11 @@ describe('Shopping DB Service', () => {
       const mockItem = createMockShoppingListItem({ shopping_list_item_id: 1, ...updates });
       mockPoolInstance.query.mockResolvedValue({ rows: [mockItem], rowCount: 1 });
 
-      const result = await shoppingRepo.updateShoppingListItem(1, updates, mockLogger);
+      const result = await shoppingRepo.updateShoppingListItem(1, 'user-1', updates, mockLogger);
 
       expect(mockPoolInstance.query).toHaveBeenCalledWith(
-        'UPDATE public.shopping_list_items SET quantity = $1, is_purchased = $2, notes = $3 WHERE shopping_list_item_id = $4 RETURNING *',
-        [updates.quantity, updates.is_purchased, updates.notes, 1],
+        expect.stringContaining('UPDATE public.shopping_list_items sli'),
+        [updates.quantity, updates.is_purchased, updates.notes, 1, 'user-1'],
       );
       expect(result).toEqual(mockItem);
     });
@@ -297,13 +300,13 @@ describe('Shopping DB Service', () => {
     it('should throw an error if the item to update is not found', async () => {
       mockPoolInstance.query.mockResolvedValue({ rowCount: 0, rows: [], command: 'UPDATE' });
       await expect(
-        shoppingRepo.updateShoppingListItem(999, { quantity: 5 }, mockLogger),
+        shoppingRepo.updateShoppingListItem(999, 'user-1', { quantity: 5 }, mockLogger),
       ).rejects.toThrow('Shopping list item not found.');
     });
 
     it('should throw an error if no valid fields are provided to update', async () => {
       // The function should throw before even querying the database.
-      await expect(shoppingRepo.updateShoppingListItem(1, {}, mockLogger)).rejects.toThrow(
+      await expect(shoppingRepo.updateShoppingListItem(1, 'user-1', {}, mockLogger)).rejects.toThrow(
         'No valid fields to update.',
       );
     });
@@ -312,44 +315,65 @@ describe('Shopping DB Service', () => {
       const dbError = new Error('DB Connection Error');
       mockPoolInstance.query.mockRejectedValue(dbError);
       await expect(
-        shoppingRepo.updateShoppingListItem(1, { is_purchased: true }, mockLogger),
+        shoppingRepo.updateShoppingListItem(1, 'user-1', { is_purchased: true }, mockLogger),
       ).rejects.toThrow('Failed to update shopping list item.');
       expect(mockLogger.error).toHaveBeenCalledWith(
-        { err: dbError, itemId: 1, updates: { is_purchased: true } },
+        { err: dbError, itemId: 1, userId: 'user-1', updates: { is_purchased: true } },
         'Database error in updateShoppingListItem',
       );
     });
   });
 
+  describe('updateShoppingListItem - Ownership Check', () => {
+    it('should not update an item if the user does not own the shopping list', async () => {
+      mockPoolInstance.query.mockResolvedValue({ rowCount: 0 });
+
+      await expect(
+        shoppingRepo.updateShoppingListItem(1, 'wrong-user', { is_purchased: true }, mockLogger),
+      ).rejects.toThrow('Shopping list item not found.');
+    });
+  });
+
+
   describe('removeShoppingListItem', () => {
     it('should delete an item if rowCount is 1', async () => {
       mockPoolInstance.query.mockResolvedValue({ rowCount: 1, rows: [], command: 'DELETE' });
-      await expect(shoppingRepo.removeShoppingListItem(1, mockLogger)).resolves.toBeUndefined();
+      await expect(shoppingRepo.removeShoppingListItem(1, 'user-1', mockLogger)).resolves.toBeUndefined();
       expect(mockPoolInstance.query).toHaveBeenCalledWith(
-        'DELETE FROM public.shopping_list_items WHERE shopping_list_item_id = $1',
-        [1],
+        expect.stringContaining('DELETE FROM public.shopping_list_items sli'),
+        [1, 'user-1'],
       );
     });
 
     it('should throw an error if no rows are deleted (item not found)', async () => {
       mockPoolInstance.query.mockResolvedValue({ rowCount: 0, rows: [], command: 'DELETE' });
-      await expect(shoppingRepo.removeShoppingListItem(999, mockLogger)).rejects.toThrow(
-        'Shopping list item not found.',
+      await expect(shoppingRepo.removeShoppingListItem(999, 'user-1', mockLogger)).rejects.toThrow(
+        'Shopping list item not found or user does not have permission.',
       );
     });
 
     it('should throw a generic error if the database query fails', async () => {
       const dbError = new Error('DB Connection Error');
       mockPoolInstance.query.mockRejectedValue(dbError);
-      await expect(shoppingRepo.removeShoppingListItem(1, mockLogger)).rejects.toThrow(
+      await expect(shoppingRepo.removeShoppingListItem(1, 'user-1', mockLogger)).rejects.toThrow(
         'Failed to remove item from shopping list.',
       );
       expect(mockLogger.error).toHaveBeenCalledWith(
-        { err: dbError, itemId: 1 },
+        { err: dbError, itemId: 1, userId: 'user-1' },
         'Database error in removeShoppingListItem',
       );
     });
   });
+  describe('removeShoppingListItem - Ownership Check', () => {
+    it('should not remove an item if the user does not own the shopping list', async () => {
+      mockPoolInstance.query.mockResolvedValue({ rowCount: 0 });
+
+      await expect(shoppingRepo.removeShoppingListItem(1, 'wrong-user', mockLogger)).rejects.toThrow(
+        'Shopping list item not found or user does not have permission.',
+      );
+    });
+  });
+
 
   describe('completeShoppingList', () => {
     it('should call the complete_shopping_list database function', async () => {

src/services/db/shopping.db.ts

@@ -156,6 +156,7 @@ export class ShoppingRepository {
    */
   async addShoppingListItem(
     listId: number,
+    userId: string,
     item: { masterItemId?: number; customItemName?: string },
     logger: Logger,
   ): Promise<ShoppingListItem> {
@@ -165,13 +166,29 @@ export class ShoppingRepository {
     }
 
     try {
-      const res = await this.db.query<ShoppingListItem>(
-        'INSERT INTO public.shopping_list_items (shopping_list_id, master_item_id, custom_item_name) VALUES ($1, $2, $3) RETURNING *',
-        [listId, item.masterItemId ?? null, item.customItemName ?? null],
-      );
+      const query = `
+        INSERT INTO public.shopping_list_items (shopping_list_id, master_item_id, custom_item_name)
+        SELECT $1, $2, $3
+        WHERE EXISTS (
+          SELECT 1 FROM public.shopping_lists WHERE shopping_list_id = $1 AND user_id = $4
+        )
+        RETURNING *;
+      `;
+      const res = await this.db.query<ShoppingListItem>(query, [
+        listId,
+        item.masterItemId ?? null,
+        item.customItemName ?? null,
+        userId,
+      ]);
+
+      if (res.rowCount === 0) {
+        throw new NotFoundError('Shopping list not found or user does not have permission.');
+      }
+
       return res.rows[0];
     } catch (error) {
-      handleDbError(error, logger, 'Database error in addShoppingListItem', { listId, item }, {
+      if (error instanceof NotFoundError) throw error;
+      handleDbError(error, logger, 'Database error in addShoppingListItem', { listId, userId, item }, {
         fkMessage: 'Referenced list or item does not exist.',
         checkMessage: 'Shopping list item must have a master item or a custom name.',
         defaultMessage: 'Failed to add item to shopping list.',
@@ -183,19 +200,23 @@ export class ShoppingRepository {
    * Removes an item from a shopping list.
    * @param itemId The ID of the shopping list item to remove.
    */
-  async removeShoppingListItem(itemId: number, logger: Logger): Promise<void> {
+  async removeShoppingListItem(itemId: number, userId: string, logger: Logger): Promise<void> {
     try {
-      const res = await this.db.query(
-        'DELETE FROM public.shopping_list_items WHERE shopping_list_item_id = $1',
-        [itemId],
-      );
-      // The patch requested this specific error handling.
+      const query = `
+        DELETE FROM public.shopping_list_items sli
+        WHERE sli.shopping_list_item_id = $1
+          AND EXISTS (
+            SELECT 1 FROM public.shopping_lists sl
+            WHERE sl.shopping_list_id = sli.shopping_list_id AND sl.user_id = $2
+          );
+      `;
+      const res = await this.db.query(query, [itemId, userId]);
       if (res.rowCount === 0) {
-        throw new NotFoundError('Shopping list item not found.');
+        throw new NotFoundError('Shopping list item not found or user does not have permission.');
       }
     } catch (error) {
       if (error instanceof NotFoundError) throw error;
-      handleDbError(error, logger, 'Database error in removeShoppingListItem', { itemId }, {
+      handleDbError(error, logger, 'Database error in removeShoppingListItem', { itemId, userId }, {
         defaultMessage: 'Failed to remove item from shopping list.',
       });
     }
@@ -312,6 +333,7 @@ export class ShoppingRepository {
    */
   async updateShoppingListItem(
     itemId: number,
+    userId: string,
     updates: Partial<ShoppingListItem>,
     logger: Logger,
   ): Promise<ShoppingListItem> {
@@ -341,10 +363,19 @@ export class ShoppingRepository {
       }
 
       values.push(itemId);
-      const query = `UPDATE public.shopping_list_items SET ${setClauses.join(', ')} WHERE shopping_list_item_id = $${valueIndex} RETURNING *`;
+      values.push(userId);
+
+      const query = `
+        UPDATE public.shopping_list_items sli
+        SET ${setClauses.join(', ')}
+        FROM public.shopping_lists sl
+        WHERE sli.shopping_list_item_id = $${valueIndex}
+          AND sli.shopping_list_id = sl.shopping_list_id
+          AND sl.user_id = $${valueIndex + 1}
+        RETURNING sli.*;
+      `;
 
       const res = await this.db.query<ShoppingListItem>(query, values);
-      // The patch requested this specific error handling.
       if (res.rowCount === 0) {
         throw new NotFoundError('Shopping list item not found.');
       }
@@ -357,7 +388,7 @@ export class ShoppingRepository {
       ) {
         throw error;
       }
-      handleDbError(error, logger, 'Database error in updateShoppingListItem', { itemId, updates }, {
+      handleDbError(error, logger, 'Database error in updateShoppingListItem', { itemId, userId, updates }, {
         defaultMessage: 'Failed to update shopping list item.',
       });
     }

src/services/db/user.db.test.ts

@@ -73,8 +73,12 @@ describe('User DB Service', () => {
       const mockUser = {
         user_id: '123',
         email: 'test@example.com',
+        password_hash: 'some-hash',
+        failed_login_attempts: 0,
+        last_failed_login: null,
         created_at: new Date().toISOString(),
         updated_at: new Date().toISOString(),
+        refresh_token: null,
       };
       mockPoolInstance.query.mockResolvedValue({ rows: [mockUser] });
 
@@ -233,9 +237,7 @@ describe('User DB Service', () => {
       }
 
       expect(withTransaction).toHaveBeenCalledTimes(1);
-      expect(mockLogger.warn).toHaveBeenCalledWith(
-        `Attempted to create a user with an existing email: exists@example.com`,
-      );
+      expect(mockLogger.warn).toHaveBeenCalledWith(`Attempted to create a user with an existing email: exists@example.com`);
     });
 
     it('should throw an error if profile is not found after user creation', async () => {
@@ -836,9 +838,7 @@ describe('User DB Service', () => {
       );
 
       // Act & Assert: The outer function catches the NotFoundError and re-throws it.
-      await expect(exportUserData('123', mockLogger)).rejects.toThrow(
-        'Failed to export user data.',
-      );
+      await expect(exportUserData('123', mockLogger)).rejects.toThrow('Profile not found');
       expect(withTransaction).toHaveBeenCalledTimes(1);
     });
 

src/services/db/user.db.ts

@@ -2,7 +2,7 @@
 import { Pool, PoolClient } from 'pg';
 import { getPool } from './connection.db';
 import type { Logger } from 'pino';
-import { NotFoundError, handleDbError } from './errors.db';
+import { NotFoundError, handleDbError, UniqueConstraintError } from './errors.db';
 import {
   Profile,
   MasterGroceryItem,
@@ -127,6 +127,12 @@ export class UserRepository {
       logger.debug({ user: fullUserProfile }, `[DB createUser] Fetched full profile for new user:`);
       return fullUserProfile;
     }).catch((error) => {
+      // Specific handling for unique constraint violation on user creation
+      if (error instanceof Error && 'code' in error && (error as any).code === '23505') {
+        logger.warn(`Attempted to create a user with an existing email: ${email}`);
+        throw new UniqueConstraintError('A user with this email address already exists.');
+      }
+      // Fallback to generic handler for all other errors
       handleDbError(error, logger, 'Error during createUser transaction', { email }, {
         uniqueMessage: 'A user with this email address already exists.',
         defaultMessage: 'Failed to create user in database.',

src/services/flyerAiProcessor.server.test.ts

@@ -100,7 +100,7 @@ describe('FlyerAiProcessor', () => {
       valid_to: null,
       store_address: null,
     };
-    vi.mocked(mockAiService.extractCoreDataFromFlyerImage).mockResolvedValue(mockAiResponse as any);
+    vi.mocked(mockAiService.extractCoreDataFromFlyerImage).mockResolvedValue(mockAiResponse);
     const { logger } = await import('./logger.server');
 
     const imagePaths = [{ path: 'page1.jpg', mimetype: 'image/jpeg' }];

src/services/flyerDataTransformer.test.ts

@@ -70,6 +70,8 @@ describe('FlyerDataTransformer', () => {
       mockLogger,
     );
 
+    const baseUrl = `http://localhost:${process.env.PORT || 3000}`;
+
     // Assert
     // 0. Check logging
     expect(mockLogger.info).toHaveBeenCalledWith(
@@ -83,8 +85,8 @@ describe('FlyerDataTransformer', () => {
     // 1. Check flyer data
     expect(flyerData).toEqual({
       file_name: originalFileName,
-      image_url: '/flyer-images/flyer-page-1.jpg',
-      icon_url: '/flyer-images/icons/icon-flyer-page-1.webp',
+      image_url: `${baseUrl}/flyer-images/flyer-page-1.jpg`,
+      icon_url: `${baseUrl}/flyer-images/icons/icon-flyer-page-1.webp`,
       checksum,
       store_name: 'Test Store',
       valid_from: '2024-01-01',
@@ -151,6 +153,8 @@ describe('FlyerDataTransformer', () => {
       mockLogger,
     );
 
+    const baseUrl = `http://localhost:${process.env.PORT || 3000}`;
+
     // Assert
     // 0. Check logging
     expect(mockLogger.info).toHaveBeenCalledWith(
@@ -167,8 +171,8 @@ describe('FlyerDataTransformer', () => {
     expect(itemsForDb).toHaveLength(0);
     expect(flyerData).toEqual({
       file_name: originalFileName,
-      image_url: '/flyer-images/another.png',
-      icon_url: '/flyer-images/icons/icon-another.webp',
+      image_url: `${baseUrl}/flyer-images/another.png`,
+      icon_url: `${baseUrl}/flyer-images/icons/icon-another.webp`,
       checksum,
       store_name: 'Unknown Store (auto)', // Should use fallback
       valid_from: null,

src/services/flyerDataTransformer.ts

@@ -75,10 +75,13 @@ export class FlyerDataTransformer {
         logger.warn('AI did not return a store name. Using fallback "Unknown Store (auto)".');
       }
 
+      // Construct proper URLs including protocol and host to satisfy DB constraints
+      const baseUrl = process.env.BASE_URL || `http://localhost:${process.env.PORT || 3000}`;
+
       const flyerData: FlyerInsert = {
         file_name: originalFileName,
-        image_url: `/flyer-images/${path.basename(firstImage)}`,
-        icon_url: `/flyer-images/icons/${iconFileName}`,
+        image_url: new URL(`/flyer-images/${path.basename(firstImage)}`, baseUrl).href,
+        icon_url: new URL(`/flyer-images/icons/${iconFileName}`, baseUrl).href,
         checksum,
         store_name: storeName,
         valid_from: extractedData.valid_from,

src/tests/integration/admin.integration.test.ts

@@ -164,8 +164,10 @@ describe('Admin API Routes Integration Tests', () => {
     beforeEach(async () => {
       const flyerRes = await getPool().query(
         `INSERT INTO public.flyers (store_id, file_name, image_url, item_count, checksum) 
-         VALUES ($1, 'admin-test.jpg', 'http://test.com/img.jpg', 1, $2) RETURNING flyer_id`,
-        [testStoreId, `checksum-${Date.now()}-${Math.random()}`],
+         VALUES ($1, 'admin-test.jpg', 'https://example.com/flyer-images/asdmin-test.jpg', 1, $2) RETURNING flyer_id`,
+        // The checksum must be a unique 64-character string to satisfy the DB constraint.
+        // We generate a dynamic string and pad it to 64 characters.
+        [testStoreId, `checksum-${Date.now()}-${Math.random()}`.padEnd(64, '0')],
       );
       const flyerId = flyerRes.rows[0].flyer_id;
 

src/tests/integration/flyer-processing.integration.test.ts

@@ -1,5 +1,5 @@
 // src/tests/integration/flyer-processing.integration.test.ts
-import { describe, it, expect, beforeAll, afterAll } from 'vitest';
+import { describe, it, expect, beforeAll, afterAll, vi } from 'vitest';
 import supertest from 'supertest';
 import app from '../../../server';
 import fs from 'node:fs/promises';
@@ -8,7 +8,7 @@ import * as db from '../../services/db/index.db';
 import { getPool } from '../../services/db/connection.db';
 import { generateFileChecksum } from '../../utils/checksum';
 import { logger } from '../../services/logger.server';
-import type { UserProfile } from '../../types';
+import type { UserProfile, ExtractedFlyerItem } from '../../types';
 import { createAndLoginUser } from '../utils/testHelpers';
 import { cleanupDb } from '../utils/cleanup';
 import { cleanupFiles } from '../utils/cleanupFiles';
@@ -16,12 +16,16 @@ import piexif from 'piexifjs';
 import exifParser from 'exif-parser';
 import sharp from 'sharp';
 
+
 /**
  * @vitest-environment node
  */
 
 const request = supertest(app);
 
+// Import the mocked service to control its behavior in tests.
+import { aiService } from '../../services/aiService.server';
+
 describe('Flyer Processing Background Job Integration Test', () => {
   const createdUserIds: string[] = [];
   const createdFlyerIds: number[] = [];
@@ -29,6 +33,23 @@ describe('Flyer Processing Background Job Integration Test', () => {
 
   beforeAll(async () => {
     // This setup is now simpler as the worker handles fetching master items.
+    // Setup default mock response for AI service
+    const mockItems: ExtractedFlyerItem[] = [
+      {
+        item: 'Mocked Integration Item',
+        price_display: '$1.99',
+        price_in_cents: 199,
+        quantity: 'each',
+        category_name: 'Mock Category',
+      },
+    ];
+    vi.spyOn(aiService, 'extractCoreDataFromFlyerImage').mockResolvedValue({
+      store_name: 'Mock Store',
+      valid_from: null,
+      valid_to: null,
+      store_address: null,
+      items: mockItems,
+    });
   });
 
   afterAll(async () => {
@@ -80,7 +101,7 @@ describe('Flyer Processing Background Job Integration Test', () => {
 
     // Act 2: Poll for the job status until it completes.
     let jobStatus;
-    const maxRetries = 30; // Poll for up to 90 seconds (30 * 3s)
+    const maxRetries = 60; // Poll for up to 180 seconds (60 * 3s)
     for (let i = 0; i < maxRetries; i++) {
       console.log(`Polling attempt ${i + 1}...`);
       await new Promise((resolve) => setTimeout(resolve, 3000)); // Wait 3 seconds between polls
@@ -149,12 +170,12 @@ describe('Flyer Processing Background Job Integration Test', () => {
 
     // Act & Assert
     await runBackgroundProcessingTest(authUser, token);
-  }, 120000); // Increase timeout to 120 seconds for this long-running test
+  }, 240000); // Increase timeout to 240 seconds for this long-running test
 
   it('should successfully process a flyer for an ANONYMOUS user via the background queue', async () => {
     // Act & Assert: Call the test helper without a user or token.
     await runBackgroundProcessingTest();
-  }, 120000); // Increase timeout to 120 seconds for this long-running test
+  }, 240000); // Increase timeout to 240 seconds for this long-running test
 
   it(
     'should strip EXIF data from uploaded JPEG images during processing',
@@ -219,7 +240,7 @@ describe('Flyer Processing Background Job Integration Test', () => {
         console.error('[DEBUG] EXIF test job failed:', jobStatus.failedReason);
       }
       expect(jobStatus?.state).toBe('completed');
-      const flyerId = jobStatus?.returnValue?.flyerId;
+      const flyerId = jobStatus?.data?.flyerId;
       expect(flyerId).toBeTypeOf('number');
       createdFlyerIds.push(flyerId);
 
@@ -238,7 +259,7 @@ describe('Flyer Processing Background Job Integration Test', () => {
       expect(exifResult.tags).toEqual({});
       expect(exifResult.tags.Software).toBeUndefined();
     },
-    120000,
+    240000,
   );
 
   it(
@@ -305,7 +326,7 @@ describe('Flyer Processing Background Job Integration Test', () => {
         console.error('[DEBUG] PNG metadata test job failed:', jobStatus.failedReason);
       }
       expect(jobStatus?.state).toBe('completed');
-      const flyerId = jobStatus?.returnValue?.flyerId;
+      const flyerId = jobStatus?.data?.flyerId;
       expect(flyerId).toBeTypeOf('number');
       createdFlyerIds.push(flyerId);
 
@@ -322,6 +343,6 @@ describe('Flyer Processing Background Job Integration Test', () => {
       // The `exif` property should be undefined after the fix.
       expect(savedImageMetadata.exif).toBeUndefined();
     },
-    120000,
+    240000,
   );
 });

src/tests/integration/flyer.integration.test.ts

@@ -25,8 +25,8 @@ describe('Public Flyer API Routes Integration Tests', () => {
 
     const flyerRes = await getPool().query(
       `INSERT INTO public.flyers (store_id, file_name, image_url, item_count, checksum) 
-       VALUES ($1, 'integration-test.jpg', 'http://test.com/img.jpg', 1, $2) RETURNING flyer_id`,
-      [storeId, `checksum-${Date.now()}`],
+       VALUES ($1, 'integration-test.jpg', 'https://example.com/flyer-images/integration-test.jpg', 1, $2) RETURNING flyer_id`,
+      [storeId, `${Date.now().toString(16)}`.padEnd(64, '0')],
     );
     createdFlyerId = flyerRes.rows[0].flyer_id;
 

src/tests/integration/gamification.integration.test.ts

@@ -1,5 +1,5 @@
 // src/tests/integration/gamification.integration.test.ts
-import { describe, it, expect, beforeAll, afterAll } from 'vitest';
+import { describe, it, expect, beforeAll, afterAll, vi } from 'vitest';
 import supertest from 'supertest';
 import app from '../../../server';
 import path from 'path';
@@ -9,7 +9,13 @@ import { generateFileChecksum } from '../../utils/checksum';
 import * as db from '../../services/db/index.db';
 import { cleanupDb } from '../utils/cleanup';
 import { logger } from '../../services/logger.server';
-import type { UserProfile, UserAchievement, LeaderboardUser, Achievement  } from '../../types';
+import type {
+  UserProfile,
+  UserAchievement,
+  LeaderboardUser,
+  Achievement,
+  ExtractedFlyerItem,
+} from '../../types';
 import { cleanupFiles } from '../utils/cleanupFiles';
 
 /**
@@ -18,6 +24,9 @@ import { cleanupFiles } from '../utils/cleanupFiles';
 
 const request = supertest(app);
 
+// Import the mocked service to control its behavior in tests.
+import { aiService } from '../../services/aiService.server';
+
 describe('Gamification Flow Integration Test', () => {
   let testUser: UserProfile;
   let authToken: string;
@@ -31,6 +40,28 @@ describe('Gamification Flow Integration Test', () => {
       fullName: 'Gamification Tester',
       request,
     }));
+
+    // Mock the AI service's method to prevent actual API calls during integration tests.
+    // This is crucial for making the integration test reliable. We don't want to
+    // depend on the external Gemini API, which has quotas and can be slow.
+    // By mocking this, we test our application's internal flow:
+    // API -> Queue -> Worker -> DB -> Gamification Logic
+    const mockExtractedItems: ExtractedFlyerItem[] = [
+      {
+        item: 'Integration Test Milk',
+        price_display: '$4.99',
+        price_in_cents: 499,
+        quantity: '2L',
+        category_name: 'Dairy',
+      },
+    ];
+    vi.spyOn(aiService, 'extractCoreDataFromFlyerImage').mockResolvedValue({
+      store_name: 'Gamification Test Store',
+      valid_from: null,
+      valid_to: null,
+      store_address: null,
+      items: mockExtractedItems,
+    });
   });
 
   afterAll(async () => {
@@ -81,12 +112,17 @@ describe('Gamification Flow Integration Test', () => {
           break;
         }
       }
+    if (!jobStatus) {
+      console.error('[DEBUG] Gamification test job timed out: No job status received.');
+      throw new Error('Gamification test job timed out: No job status received.');
+    }
 
       // --- Assert 1: Verify the job completed successfully ---
       if (jobStatus?.state === 'failed') {
         console.error('[DEBUG] Gamification test job failed:', jobStatus.failedReason);
       }
       expect(jobStatus?.state).toBe('completed');
+
       const flyerId = jobStatus?.returnValue?.flyerId;
       expect(flyerId).toBeTypeOf('number');
       createdFlyerIds.push(flyerId); // Track for cleanup

src/tests/integration/price.integration.test.ts

@@ -35,22 +35,22 @@ describe('Price History API Integration Test (/api/price-history)', () => {
     // 3. Create two flyers with different dates
     const flyerRes1 = await pool.query(
       `INSERT INTO public.flyers (store_id, file_name, image_url, item_count, checksum, valid_from) 
-       VALUES ($1, 'price-test-1.jpg', 'http://test.com/price-1.jpg', 1, $2, '2025-01-01') RETURNING flyer_id`,
-      [storeId, `checksum-price-1-${Date.now()}`],
+       VALUES ($1, 'price-test-1.jpg', 'https://example.com/flyer-images/price-test-1.jpg', 1, $2, '2025-01-01') RETURNING flyer_id`,
+      [storeId, `${Date.now().toString(16)}1`.padEnd(64, '0')],
     );
     flyerId1 = flyerRes1.rows[0].flyer_id;
 
     const flyerRes2 = await pool.query(
       `INSERT INTO public.flyers (store_id, file_name, image_url, item_count, checksum, valid_from) 
-       VALUES ($1, 'price-test-2.jpg', 'http://test.com/price-2.jpg', 1, $2, '2025-01-08') RETURNING flyer_id`,
-      [storeId, `checksum-price-2-${Date.now()}`],
+       VALUES ($1, 'price-test-2.jpg', 'https://example.com/flyer-images/price-test-2.jpg', 1, $2, '2025-01-08') RETURNING flyer_id`,
+      [storeId, `${Date.now().toString(16)}2`.padEnd(64, '0')],
     );
     flyerId2 = flyerRes2.rows[0].flyer_id; // This was a duplicate, fixed.
 
     const flyerRes3 = await pool.query(
       `INSERT INTO public.flyers (store_id, file_name, image_url, item_count, checksum, valid_from) 
-       VALUES ($1, 'price-test-3.jpg', 'http://test.com/price-3.jpg', 1, $2, '2025-01-15') RETURNING flyer_id`,
-      [storeId, `checksum-price-3-${Date.now()}`],
+       VALUES ($1, 'price-test-3.jpg', 'https://example.com/flyer-images/price-test-3.jpg', 1, $2, '2025-01-15') RETURNING flyer_id`,
+      [storeId, `${Date.now().toString(16)}3`.padEnd(64, '0')],
     );
     flyerId3 = flyerRes3.rows[0].flyer_id;
 

src/tests/integration/public.routes.integration.test.ts

@@ -78,8 +78,8 @@ describe('Public API Routes Integration Tests', () => {
     testStoreId = storeRes.rows[0].store_id;
     const flyerRes = await pool.query(
       `INSERT INTO public.flyers (store_id, file_name, image_url, item_count, checksum) 
-       VALUES ($1, 'public-routes-test.jpg', 'http://test.com/public-routes.jpg', 1, $2) RETURNING *`,
-      [testStoreId, `checksum-public-routes-${Date.now()}`],
+       VALUES ($1, 'public-routes-test.jpg', 'https://example.com/flyer-images/public-routes-test.jpg', 1, $2) RETURNING *`,
+      [testStoreId, `${Date.now().toString(16)}`.padEnd(64, '0')],
     );
     testFlyer = flyerRes.rows[0];
 

src/tests/integration/recipe.integration.test.ts

@@ -1,5 +1,5 @@
 // src/tests/integration/recipe.integration.test.ts
-import { describe, it, expect, beforeAll, afterAll } from 'vitest';
+import { describe, it, expect, beforeAll, afterAll, vi } from 'vitest';
 import supertest from 'supertest';
 import app from '../../../server';
 import { createAndLoginUser } from '../utils/testHelpers';
@@ -7,6 +7,8 @@ import { cleanupDb } from '../utils/cleanup';
 import type { UserProfile, Recipe, RecipeComment } from '../../types';
 import { getPool } from '../../services/db/connection.db';
 
+import { aiService } from '../../services/aiService.server';
+
 /**
  * @vitest-environment node
  */
@@ -31,6 +33,9 @@ describe('Recipe API Routes Integration Tests', () => {
     authToken = token;
     createdUserIds.push(user.user.user_id);
 
+    // Mock the AI service method using spyOn to preserve other exports like DuplicateFlyerError
+    vi.spyOn(aiService, 'generateRecipeSuggestion').mockResolvedValue('Default Mock Suggestion');
+
     // Create a recipe owned by the test user
     const recipeRes = await getPool().query(
       `INSERT INTO public.recipes (name, instructions, user_id, status, description) 
@@ -124,4 +129,24 @@ describe('Recipe API Routes Integration Tests', () => {
   it.todo('should prevent a user from deleting another user\'s recipe');
   it.todo('should allow an authenticated user to post a comment on a recipe');
   it.todo('should allow an authenticated user to fork a recipe');
+
+  describe('POST /api/recipes/suggest', () => {
+    it('should return a recipe suggestion based on ingredients', async () => {
+      const ingredients = ['chicken', 'rice', 'broccoli'];
+      const mockSuggestion = 'Chicken and Broccoli Stir-fry with Rice';
+      vi.mocked(aiService.generateRecipeSuggestion).mockResolvedValue(mockSuggestion);
+
+      const response = await request
+        .post('/api/recipes/suggest')
+        .set('Authorization', `Bearer ${authToken}`)
+        .send({ ingredients });
+
+      expect(response.status).toBe(200);
+      expect(response.body).toEqual({ suggestion: mockSuggestion });
+      expect(aiService.generateRecipeSuggestion).toHaveBeenCalledWith(
+        ingredients,
+        expect.anything(),
+      );
+    });
+  });
 });

src/tests/setup/globalApiMock.ts

@@ -0,0 +1,80 @@
+// src/tests/setup/globalApiMock.ts
+import { vi } from 'vitest';
+
+/**
+ * Mocks the entire apiClient module.
+ * This global mock is loaded for all tests via the `setupFiles` config in vitest.config.ts.
+ * It prevents test failures in components that use providers (like FlyersProvider, AuthProvider)
+ * which make API calls on mount when using `renderWithProviders`.
+ *
+ * Individual tests can override specific functions as needed, for example:
+ *
+ * import { vi } from 'vitest';
+ * import * as apiClient from '../services/apiClient';
+ *
+ * const mockedApiClient = vi.mocked(apiClient);
+ *
+ * it('should test something', () => {
+ *   mockedApiClient.someFunction.mockResolvedValue({ ... });
+ *   // ... rest of the test
+ * });
+ */
+vi.mock('../../services/apiClient', () => ({
+  // --- Provider Mocks (with default successful responses) ---
+  // These are essential for any test using renderWithProviders, as AppProviders
+  // will mount all these data providers.
+  fetchFlyers: vi.fn(() => Promise.resolve(new Response(JSON.stringify({ flyers: [], hasMore: false })))),
+  fetchMasterItems: vi.fn(() => Promise.resolve(new Response(JSON.stringify([])))),
+  fetchWatchedItems: vi.fn(() => Promise.resolve(new Response(JSON.stringify([])))),
+  fetchShoppingLists: vi.fn(() => Promise.resolve(new Response(JSON.stringify([])))),
+  getAuthenticatedUserProfile: vi.fn(() => Promise.resolve(new Response(JSON.stringify(null)))),
+  fetchCategories: vi.fn(() => Promise.resolve(new Response(JSON.stringify([])))), // For CorrectionsPage
+  fetchAllBrands: vi.fn(() => Promise.resolve(new Response(JSON.stringify([])))), // For AdminBrandManager
+
+  // --- General Mocks (return empty vi.fn() by default) ---
+  // These functions are commonly used and can be implemented in specific tests.
+  suggestRecipe: vi.fn(),
+  getApplicationStats: vi.fn(),
+  getSuggestedCorrections: vi.fn(),
+  approveCorrection: vi.fn(),
+  rejectCorrection: vi.fn(),
+  updateSuggestedCorrection: vi.fn(),
+  pingBackend: vi.fn(),
+  checkStorage: vi.fn(),
+  checkDbPoolHealth: vi.fn(),
+  checkPm2Status: vi.fn(),
+  checkRedisHealth: vi.fn(),
+  checkDbSchema: vi.fn(),
+  loginUser: vi.fn(),
+  registerUser: vi.fn(),
+  requestPasswordReset: vi.fn(),
+  triggerFailingJob: vi.fn(),
+  clearGeocodeCache: vi.fn(),
+  uploadBrandLogo: vi.fn(),
+  fetchActivityLog: vi.fn(),
+  updateUserProfile: vi.fn(),
+  updateUserPassword: vi.fn(),
+  updateUserPreferences: vi.fn(),
+  exportUserData: vi.fn(),
+  deleteUserAccount: vi.fn(),
+  getUserAddress: vi.fn(),
+  updateUserAddress: vi.fn(),
+  geocodeAddress: vi.fn(),
+  getFlyersForReview: vi.fn(),
+  fetchLeaderboard: vi.fn(),
+  // --- Added to fix "No export is defined on the mock" errors ---
+  fetchFlyerItems: vi.fn(),
+  createShoppingList: vi.fn(),
+  deleteShoppingList: vi.fn(),
+  addShoppingListItem: vi.fn(),
+  updateShoppingListItem: vi.fn(),
+  removeShoppingListItem: vi.fn(),
+  addWatchedItem: vi.fn(),
+  removeWatchedItem: vi.fn(),
+  fetchBestSalePrices: vi.fn(),
+  resetPassword: vi.fn(),
+  getUserAchievements: vi.fn(),
+  uploadAvatar: vi.fn(),
+  countFlyerItemsForFlyers: vi.fn(),
+  fetchFlyerItemsForFlyers: vi.fn(),
+}));

src/tests/setup/tests-setup-unit.ts

@@ -257,67 +257,6 @@ vi.mock('@google/genai', () => {
   };
 });
 
-/**
- * Mocks the entire apiClient module.
- * This ensures that all test files that import from apiClient will get this mocked version.
- */
-vi.mock('../../services/apiClient', () => ({
-  // --- Auth ---
-  registerUser: vi.fn(),
-  loginUser: vi.fn(),
-  getAuthenticatedUserProfile: vi.fn(),
-  requestPasswordReset: vi.fn(),
-  resetPassword: vi.fn(),
-  updateUserPassword: vi.fn(),
-  deleteUserAccount: vi.fn(),
-  updateUserPreferences: vi.fn(),
-  updateUserProfile: vi.fn(),
-  // --- Data Fetching & Manipulation ---
-  fetchFlyers: vi.fn(),
-  fetchFlyerItems: vi.fn(),
-  // Provide a default implementation that returns a valid Response object to prevent timeouts.
-  fetchFlyerItemsForFlyers: vi.fn(() => Promise.resolve(new Response(JSON.stringify([])))),
-  countFlyerItemsForFlyers: vi.fn(() =>
-    Promise.resolve(new Response(JSON.stringify({ count: 0 }))),
-  ),
-  fetchMasterItems: vi.fn(),
-  fetchWatchedItems: vi.fn(),
-  addWatchedItem: vi.fn(),
-  removeWatchedItem: vi.fn(),
-  fetchShoppingLists: vi.fn(),
-  createShoppingList: vi.fn(),
-  deleteShoppingList: vi.fn(),
-  addShoppingListItem: vi.fn(),
-  updateShoppingListItem: vi.fn(),
-  removeShoppingListItem: vi.fn(),
-  fetchHistoricalPriceData: vi.fn(),
-  processFlyerFile: vi.fn(),
-  uploadLogoAndUpdateStore: vi.fn(),
-  exportUserData: vi.fn(),
-  // --- Address ---
-  getUserAddress: vi.fn(),
-  updateUserAddress: vi.fn(),
-  geocodeAddress: vi.fn(() => Promise.resolve(new Response(JSON.stringify({ lat: 0, lng: 0 })))),
-  // --- Admin ---
-  getSuggestedCorrections: vi.fn(),
-  fetchCategories: vi.fn(),
-  approveCorrection: vi.fn(),
-  rejectCorrection: vi.fn(),
-  updateSuggestedCorrection: vi.fn(),
-  getApplicationStats: vi.fn(),
-  fetchActivityLog: vi.fn(),
-  fetchAllBrands: vi.fn(),
-  uploadBrandLogo: vi.fn(),
-  // --- System ---
-  pingBackend: vi.fn(),
-  checkDbSchema: vi.fn(),
-  checkStorage: vi.fn(),
-  checkDbPoolHealth: vi.fn(),
-  checkRedisHealth: vi.fn(),
-  checkPm2Status: vi.fn(),
-  fetchLeaderboard: vi.fn(),
-}));
-
 // FIX: Mock the aiApiClient module as well, which is used by AnalysisPanel
 vi.mock('../../services/aiApiClient', () => ({
   // Provide a default implementation that returns a valid Response object to prevent timeouts.

src/tests/utils/mockFactories.ts

@@ -109,7 +109,7 @@ export const createMockUser = (overrides: Partial<User> = {}): User => {
  * @returns A complete and type-safe UserProfile object.
  */
 export const createMockUserProfile = (
-  overrides: Partial<UserProfile & { user: Partial<User> }> = {},
+  overrides: Partial<Omit<UserProfile, 'user'>> & { user?: Partial<User> } = {},
 ): UserProfile => {
   // The user object is the source of truth for user_id and email.
   const user = createMockUser(overrides.user);

src/tests/utils/renderWithProviders.tsx

@@ -0,0 +1,31 @@
+// src/tests/utils/renderWithProviders.tsx
+import React, { ReactElement } from 'react';
+import { render, RenderOptions } from '@testing-library/react';
+import { AppProviders } from '../../providers/AppProviders';
+import { MemoryRouter } from 'react-router-dom';
+
+interface ExtendedRenderOptions extends Omit<RenderOptions, 'wrapper'> {
+  initialEntries?: string[];
+}
+
+/**
+ * A custom render function that wraps the component with all application providers.
+ * This is useful for testing components that rely on context values (Auth, Modal, etc.).
+ *
+ * @param ui The component to render
+ * @param options Additional render options
+ * @returns The result of the render function
+ */
+export const renderWithProviders = (
+  ui: ReactElement,
+  options?: ExtendedRenderOptions,
+) => {
+  const { initialEntries, ...renderOptions } = options || {};
+  // console.log('[renderWithProviders] Wrapping component with AppProviders context.');
+  const Wrapper = ({ children }: { children: React.ReactNode }) => (
+    <MemoryRouter initialEntries={initialEntries}>
+      <AppProviders>{children}</AppProviders>
+    </MemoryRouter>
+  );
+  return render(ui, { wrapper: Wrapper, ...renderOptions });
+};

src/types/exif-parser.d.ts

@@ -5,4 +5,104 @@
  * which does not ship with its own TypeScript types. This allows TypeScript
  * to recognize it as a module and avoids "implicit any" errors.
  */
-declare module 'exif-parser';
+declare module 'exif-parser' {
+  /**
+   * Represents the size of the image.
+   */
+  export interface ImageSize {
+    width: number;
+    height: number;
+  }
+
+  /**
+   * Represents thumbnail data if available.
+   */
+  export interface Thumbnail {
+    format: string;
+    width: number;
+    height: number;
+    offset: number;
+    size: number;
+    buffer: Buffer;
+  }
+
+  /**
+   * Represents GPS information if available.
+   */
+  export interface GPS {
+    latitude: number;
+    longitude: number;
+    altitude: number;
+    latitudeRef: string;
+    longitudeRef: string;
+    altitudeRef: number;
+    GPSDateStamp: string;
+    GPSTimeStamp: number[]; // [hour, minute, second]
+  }
+
+  /**
+   * Represents the parsed EXIF data structure.
+   * This includes common tags and derived properties.
+   */
+  export interface ExifData {
+    /**
+     * A dictionary of raw EXIF tags. Keys are tag names (e.g., 'Make', 'Model', 'DateTimeOriginal').
+     * Values can be of various types (string, number, Date, etc.).
+     */
+    tags: {
+      Make?: string;
+      Model?: string;
+      Orientation?: number;
+      XResolution?: number;
+      YResolution?: number;
+      ResolutionUnit?: number;
+      DateTimeOriginal?: Date; // Parsed into a Date object
+      DateTimeDigitized?: Date;
+      ExposureTime?: number;
+      FNumber?: number;
+      ISOSpeedRatings?: number;
+      ShutterSpeedValue?: number;
+      ApertureValue?: number;
+      BrightnessValue?: number;
+      ExposureBiasValue?: number;
+      MaxApertureValue?: number;
+      MeteringMode?: number;
+      LightSource?: number;
+      Flash?: number;
+      FocalLength?: number;
+      ColorSpace?: number;
+      ExifImageWidth?: number;
+      ExifImageHeight?: number;
+      ExposureMode?: number;
+      WhiteBalance?: number;
+      DigitalZoomRatio?: number;
+      FocalLengthIn35mmFilm?: number;
+      SceneCaptureType?: number;
+      GainControl?: number;
+      Contrast?: number;
+      Saturation?: number;
+      Sharpness?: number;
+      SubjectDistanceRange?: number;
+      GPSVersionID?: number[];
+      GPSLatitudeRef?: string;
+      GPSLatitude?: number[];
+      GPSLongitudeRef?: string;
+      GPSLongitude?: number[];
+      GPSAltitudeRef?: number;
+      GPSAltitude?: number;
+      GPSTimeStamp?: number[];
+      GPSDateStamp?: string;
+      [key: string]: any; // Allow for other, less common tags
+    };
+    imageSize: ImageSize;
+    thumbnail?: Thumbnail;
+    gps?: GPS;
+  }
+
+  export class ExifParser {
+    static create(buffer: Buffer): ExifParser;
+    parse(): ExifData;
+  }
+
+  export default ExifParser;
+}

src/types/pdf-poppler.d.ts

@@ -7,37 +7,115 @@
  * structure, preventing import errors and enabling type checking.
  */
 declare module 'pdf-poppler' {
+  /**
+   * Defines the options available for the main `convert` method.
+   * This appears to be a simplified wrapper around pdftocairo.
+   */
+  export interface ConvertOptions {
+    /**
+     * The output image format.
+     */
+    format?: 'jpeg' | 'png' | 'tiff';
+    /**
+     * The directory where output images will be saved.
+     */
+    out_dir?: string;
+    /**
+     * The prefix for the output image files.
+     */
+    out_prefix?: string;
+    /**
+     * Specify a page number to convert a specific page, or null to convert all pages.
+     */
+    page?: number | null;
+    /**
+     * Specifies the resolution, in DPI. The default is 72 DPI.
+     */
+    resolution?: number;
+    /**
+     * Scales each page to fit in scale-to x scale-to pixel square.
+     */
+    scale_to?: number;
+  }
+
   /**
    * Defines the options available for the pdfToCairo conversion method.
-   * This interface can be expanded as more options are used.
+   * These options correspond to the command-line arguments for the `pdftocairo` utility.
    */
   export interface PopplerOptions {
     antialias?: 'default' | 'gray' | 'none' | 'subpixel';
     cropBox?: boolean;
     cropHeight?: number;
     cropWidth?: number;
+    cropSize?: number;
     cropX?: number;
     cropY?: number;
+    duplex?: boolean;
+    epsFile?: boolean;
+    expand?: boolean;
     firstPage?: number;
+    grayFile?: boolean;
     lastPage?: number;
     jpegFile?: boolean;
     jpegOptions?: string;
+    level2?: boolean;
+    level3?: boolean;
+    monoFile?: boolean;
+    noCenter?: boolean;
     noCrop?: boolean;
     noRotate?: boolean;
+    noShrink?: boolean;
     ownerPassword?: string;
     paperHeight?: number;
     paperWidth?: number;
     paperSize?: 'letter' | 'legal' | 'A4' | 'A3' | 'match';
     pngFile?: boolean;
+    psFile?: boolean;
+    pdfFile?: boolean;
     resolution?: number;
+    scaleTo?: number;
+    scaleToX?: number;
+    scaleToY?: number;
     svgFile?: boolean;
+    tiffFile?: boolean;
     userPassword?: string;
   }
 
+  /**
+   * Defines the structure of the PDF information object returned by `pdfInfo`.
+   */
+  export interface PdfInfo {
+    // Based on common pdfinfo output
+    title: string;
+    author: string;
+    creator: string;
+    producer: string;
+    creationDate: string;
+    modDate: string;
+    tagged: boolean;
+    form: string;
+    pages: number;
+    encrypted: boolean;
+    pageSize: string;
+    fileSize: string;
+    optimized: boolean;
+    pdfVersion: string;
+  }
+
   export class Poppler {
     constructor(binPath?: string);
     pdfToCairo(file: string, outputFilePrefix?: string, options?: PopplerOptions): Promise<string>;
+    pdfInfo(file: string, options?: { ownerPassword?: string; userPassword?: string }): Promise<PdfInfo>;
+    pdfToPs(file: string, outputFile: string, options?: any): Promise<string>;
+    pdfToText(file: string, outputFile: string, options?: any): Promise<string>;
   }
 
+  /**
+   * Converts a PDF file to images. This seems to be a convenience function provided by the library.
+   * @param pdfPath The path to the PDF file.
+   * @param options The conversion options.
+   */
+  export function convert(pdfPath: string, options?: ConvertOptions): Promise<string>;
+
   export default Poppler;
 }

vite.config.ts

@@ -41,12 +41,14 @@ export default defineConfig({
     // By default, Vitest does not suppress console logs.
     // The onConsoleLog hook is only needed if you want to conditionally filter specific logs.
     // Keeping the default behavior is often safer to avoid missing important warnings.
-
     environment: 'jsdom',
-    // Explicitly point Vitest to the correct tsconfig and enable globals.
     globals: true, // tsconfig is auto-detected, so the explicit property is not needed and causes an error.
     globalSetup: './src/tests/setup/global-setup.ts',
-    setupFiles: ['./src/tests/setup/tests-setup-unit.ts'],
+    // The globalApiMock MUST come first to ensure it's applied before other mocks that might depend on it.
+    setupFiles: [
+      './src/tests/setup/globalApiMock.ts',
+      './src/tests/setup/tests-setup-unit.ts',
+    ],
     // Explicitly include only test files.
     // We remove 'src/vite-env.d.ts' which was causing it to be run as a test.
     include: ['src/**/*.test.{ts,tsx}'],