@react-spa-scaffold/mcp 2.1.1 → 2.3.0

package/templates/src/test/clerkMock.tsx

@@ -0,0 +1,137 @@
+/**
+ * Clerk authentication mocks for testing.
+ *
+ * Provides mock implementations of Clerk components and hooks,
+ * with state controls for testing different auth scenarios.
+ */
+
+import type { ReactNode } from 'react';
+
+import { MOCK_AUTH_TOKEN, MOCK_SESSION_ID } from '@/mocks/constants';
+import { defaultUser, type MockUser } from '@/mocks/fixtures/users';
+
+// Re-export user fixtures for test convenience
+export { createUser, createUsers, defaultUser, mockUsers, type MockUser } from '@/mocks/fixtures/users';
+
+// =============================================================================
+// Types
+// =============================================================================
+
+interface ClerkMockState {
+  isSignedIn: boolean;
+  isLoaded: boolean;
+  user: MockUser;
+}
+
+// =============================================================================
+// Default State
+// =============================================================================
+
+const defaultState: ClerkMockState = {
+  isSignedIn: true,
+  isLoaded: true,
+  user: defaultUser,
+};
+
+let mockState: ClerkMockState = { ...defaultState };
+
+// =============================================================================
+// State Controls
+// =============================================================================
+
+/** Set whether the user is signed in */
+export function setMockClerkSignedIn(value: boolean) {
+  mockState.isSignedIn = value;
+}
+
+/** Set whether Clerk has finished loading */
+export function setMockClerkLoaded(value: boolean) {
+  mockState.isLoaded = value;
+}
+
+/** Set multiple Clerk state values at once */
+export function setMockClerkState(state: Partial<ClerkMockState>) {
+  mockState = { ...mockState, ...state };
+}
+
+/** Set mock user properties */
+export function setMockClerkUser(user: Partial<MockUser>) {
+  mockState.user = { ...mockState.user, ...user };
+}
+
+/** Reset all Clerk mocks to default state */
+export function resetClerkMocks() {
+  mockState = { ...defaultState, user: { ...defaultUser } };
+}
+
+// =============================================================================
+// Mock Components
+// =============================================================================
+
+export function SignedIn({ children }: { children: ReactNode }) {
+  return mockState.isLoaded && mockState.isSignedIn ? <>{children}</> : null;
+}
+
+export function SignedOut({ children }: { children: ReactNode }) {
+  return mockState.isLoaded && !mockState.isSignedIn ? <>{children}</> : null;
+}
+
+export function SignInButton({ children }: { children?: ReactNode; mode?: string }) {
+  return <div data-testid="sign-in-button">{children}</div>;
+}
+
+export function SignUpButton({ children }: { children?: ReactNode; mode?: string }) {
+  return <div data-testid="sign-up-button">{children}</div>;
+}
+
+export function UserButton() {
+  return <button data-testid="user-button">User</button>;
+}
+
+export function RedirectToSignIn() {
+  return <div data-testid="redirect-to-sign-in" />;
+}
+
+export function ClerkProvider({
+  children,
+}: {
+  children: ReactNode;
+  publishableKey?: string;
+  afterSignOutUrl?: string;
+  appearance?: unknown;
+}) {
+  return <>{children}</>;
+}
+
+// =============================================================================
+// Mock Hooks
+// =============================================================================
+
+export function useAuth() {
+  return {
+    isLoaded: mockState.isLoaded,
+    isSignedIn: mockState.isSignedIn,
+    userId: mockState.isSignedIn ? mockState.user.id : null,
+    sessionId: mockState.isSignedIn ? MOCK_SESSION_ID : null,
+    getToken: async () => (mockState.isSignedIn ? MOCK_AUTH_TOKEN : null),
+  };
+}
+
+export function useUser() {
+  return {
+    isLoaded: mockState.isLoaded,
+    user: mockState.isSignedIn ? mockState.user : null,
+  };
+}
+
+export function useSession() {
+  return {
+    isLoaded: mockState.isLoaded,
+    session: mockState.isSignedIn
+      ? {
+          id: MOCK_SESSION_ID,
+          getToken: async () => MOCK_AUTH_TOKEN,
+        }
+      : null,
+  };
+}

package/templates/src/test/fetchMock.ts

@@ -0,0 +1,58 @@
+import { vi } from 'vitest';
+
+/**
+ * Mock a successful fetch response with JSON data.
+ *
+ * @remarks Requires `vi.spyOn(global, 'fetch')` in beforeEach
+ */
+export function mockFetchSuccess<T>(data: T, status = 200): void {
+  vi.mocked(global.fetch).mockResolvedValueOnce({
+    ok: status >= 200 && status < 300,
+    status,
+    json: () => Promise.resolve(data),
+  } as Response);
+}
+
+/**
+ * Mock a 204 No Content response.
+ *
+ * @remarks Requires `vi.spyOn(global, 'fetch')` in beforeEach
+ */
+export function mockFetchNoContent(): void {
+  vi.mocked(global.fetch).mockResolvedValueOnce({
+    ok: true,
+    status: 204,
+  } as Response);
+}
+
+/**
+ * Mock an error response (4xx/5xx).
+ *
+ * @remarks Requires `vi.spyOn(global, 'fetch')` in beforeEach
+ */
+export function mockFetchError(status: number, message: string, hasJson = true): void {
+  vi.mocked(global.fetch).mockResolvedValueOnce({
+    ok: false,
+    status,
+    statusText: message,
+    json: hasJson ? () => Promise.resolve({ message }) : () => Promise.reject(new Error('No JSON')),
+  } as Response);
+}
+
+/**
+ * Mock a network error (fetch rejection).
+ *
+ * @remarks Requires `vi.spyOn(global, 'fetch')` in beforeEach
+ */
+export function mockFetchNetworkError(message = 'Network failure'): void {
+  vi.mocked(global.fetch).mockRejectedValueOnce(new Error(message));
+}
+
+/**
+ * Mock an unknown error (non-Error rejection).
+ *
+ * @remarks Requires `vi.spyOn(global, 'fetch')` in beforeEach
+ */
+export function mockFetchUnknownError(rejection: unknown = 'string error'): void {
+  vi.mocked(global.fetch).mockRejectedValueOnce(rejection);
+}

package/templates/src/test/index.ts

@@ -1,8 +1,57 @@
 // Custom render with all providers
 export { createTestQueryClient, render } from './providers';
 
-// Mock utilities
-export { mockMatchMedia } from './mocks';
+// Browser API mocks
+export {
+  mockAnimationFrame,
+  mockMatchMedia,
+  mockScrollTo,
+  mockStorageRemoveItemError,
+  mockStorageSetItemError,
+  silenceConsoleError,
+  silenceConsoleLog,
+  silenceConsoleWarn,
+} from './mocks';
+
+// Clerk test utilities
+export {
+  createUser,
+  createUsers,
+  mockUsers,
+  resetClerkMocks,
+  setMockClerkLoaded,
+  setMockClerkSignedIn,
+  setMockClerkState,
+  setMockClerkUser,
+  type MockUser,
+} from './clerkMock';
+
+// Supabase test utilities
+export {
+  createMockSupabaseClient,
+  createProfile,
+  createProfiles,
+  mockProfiles,
+  resetSupabaseMocks,
+  setMockSupabaseData,
+  setMockSupabaseError,
+  type Profile,
+} from './supabaseMock';
+
+// Fetch mock utilities
+export {
+  mockFetchError,
+  mockFetchNetworkError,
+  mockFetchNoContent,
+  mockFetchSuccess,
+  mockFetchUnknownError,
+} from './fetchMock';
 
 // MSW server instance
 export { server } from '@/mocks/node';
+
+// Todo fixtures
+export { createTodo, createTodos, mockTodos, type Todo } from '@/mocks/fixtures/todos';
+
+// Shared test constants
+export { MOCK_AUTH_TOKEN, MOCK_SESSION_ID, MOCK_SUPABASE_URL, MOCK_TIMESTAMPS, MOCK_USER } from '@/mocks/constants';

package/templates/src/test/mocks.ts

@@ -1,8 +1,25 @@
+/**
+ * Browser API mocks for testing.
+ *
+ * Provides reusable mock implementations for browser APIs
+ * that are commonly needed across tests.
+ */
+
 import { vi } from 'vitest';
 
+// =============================================================================
+// Media Query Mocks
+// =============================================================================
+
 /**
  * Creates a mock for window.matchMedia.
- * Usage: window.matchMedia = mockMatchMedia(true) // matches
+ *
+ * @example
+ * ```ts
+ * beforeEach(() => {
+ *   window.matchMedia = mockMatchMedia(true); // matches query
+ * });
+ * ```
  */
 export const mockMatchMedia = (matches: boolean) =>
   vi.fn().mockImplementation((query: string) => ({
@@ -15,3 +32,113 @@ export const mockMatchMedia = (matches: boolean) =>
     removeListener: vi.fn(),
     dispatchEvent: vi.fn(),
   }));
+
+// =============================================================================
+// Console Mocks
+// =============================================================================
+
+/**
+ * Silence console.error during a test.
+ * Returns a spy that can be restored with `.mockRestore()`.
+ *
+ * @example
+ * ```ts
+ * it('handles error gracefully', () => {
+ *   const spy = silenceConsoleError();
+ *   // ... test that triggers console.error
+ *   spy.mockRestore();
+ * });
+ * ```
+ */
+export function silenceConsoleError() {
+  return vi.spyOn(console, 'error').mockImplementation(() => {});
+}
+
+/**
+ * Silence console.warn during a test.
+ */
+export function silenceConsoleWarn() {
+  return vi.spyOn(console, 'warn').mockImplementation(() => {});
+}
+
+/**
+ * Silence console.log during a test.
+ */
+export function silenceConsoleLog() {
+  return vi.spyOn(console, 'log').mockImplementation(() => {});
+}
+
+// =============================================================================
+// Animation Frame Mocks
+// =============================================================================
+
+/**
+ * Creates mocks for requestAnimationFrame and cancelAnimationFrame.
+ * Returns the callback capture for manual triggering.
+ *
+ * @example
+ * ```ts
+ * let rafCallback: FrameRequestCallback | null = null;
+ * beforeEach(() => {
+ *   rafCallback = mockAnimationFrame();
+ * });
+ *
+ * it('updates on animation frame', () => {
+ *   // trigger state change
+ *   act(() => rafCallback?.(0));
+ *   // assert new state
+ * });
+ * ```
+ */
+export function mockAnimationFrame() {
+  let callback: FrameRequestCallback | null = null;
+
+  vi.spyOn(window, 'requestAnimationFrame').mockImplementation((cb) => {
+    callback = cb;
+    return 1;
+  });
+  vi.spyOn(window, 'cancelAnimationFrame').mockImplementation(() => {});
+
+  return () => callback;
+}
+
+// =============================================================================
+// Scroll Mocks
+// =============================================================================
+
+/**
+ * Mock window.scrollTo for tests.
+ * Returns a spy for assertions.
+ *
+ * @example
+ * ```ts
+ * const scrollSpy = mockScrollTo();
+ * // trigger scroll
+ * expect(scrollSpy).toHaveBeenCalledWith(0, 0);
+ * ```
+ */
+export function mockScrollTo() {
+  return vi.spyOn(window, 'scrollTo').mockImplementation(() => {});
+}
+
+// =============================================================================
+// Storage Mocks
+// =============================================================================
+
+/**
+ * Mock localStorage.setItem to throw (simulate quota exceeded).
+ */
+export function mockStorageSetItemError() {
+  return vi.spyOn(Storage.prototype, 'setItem').mockImplementation(() => {
+    throw new Error('QuotaExceeded');
+  });
+}
+
+/**
+ * Mock localStorage.removeItem to throw.
+ */
+export function mockStorageRemoveItemError() {
+  return vi.spyOn(Storage.prototype, 'removeItem').mockImplementation(() => {
+    throw new Error('Storage error');
+  });
+}

package/templates/src/test/providers.tsx

@@ -5,8 +5,10 @@ import { render, type RenderOptions } from '@testing-library/react';
 import { type ReactElement, type ReactNode } from 'react';
 import { MemoryRouter } from 'react-router';
 
+import { ClerkThemeProvider } from '@/contexts/clerkContext';
 import { MobileProvider } from '@/contexts/mobileContext';
 import { PerformanceProviderWrapper } from '@/contexts/performanceContext';
+import { SupabaseProvider } from '@/contexts/supabaseContext';
 
 // Setup empty English catalog for tests
 i18n.loadAndActivate({ locale: 'en', messages: {} });
@@ -37,14 +39,18 @@ interface WrapperProps {
 function AllProviders({ children }: WrapperProps) {
   const queryClient = createTestQueryClient();
 
-  // Provider order matches main.tsx: Query > I18n > Router > Mobile > Performance
+  // Provider order matches main.tsx: Query > I18n > Router > Clerk > Supabase > Mobile > Performance
   return (
     <QueryClientProvider client={queryClient}>
       <I18nProvider i18n={i18n}>
         <MemoryRouter>
-          <MobileProvider>
-            <PerformanceProviderWrapper>{children}</PerformanceProviderWrapper>
-          </MobileProvider>
+          <ClerkThemeProvider publishableKey="test_key">
+            <SupabaseProvider>
+              <MobileProvider>
+                <PerformanceProviderWrapper>{children}</PerformanceProviderWrapper>
+              </MobileProvider>
+            </SupabaseProvider>
+          </ClerkThemeProvider>
         </MemoryRouter>
       </I18nProvider>
     </QueryClientProvider>

package/templates/src/test/supabaseMock.ts

@@ -0,0 +1,112 @@
+/**
+ * Supabase mocks for testing.
+ *
+ * Provides mock implementations of the Supabase context and client,
+ * with state controls for testing different scenarios.
+ */
+
+import type { ReactNode } from 'react';
+import { vi } from 'vitest';
+
+// Re-export fixtures for test convenience
+export { createProfile, createProfiles, mockProfiles } from '@/mocks/fixtures/profiles';
+export type { Profile } from '@/types/database';
+
+// =============================================================================
+// Mock State
+// =============================================================================
+
+interface SupabaseMockState {
+  data: unknown[];
+  error: { message: string; code: string } | null;
+}
+
+const defaultState: SupabaseMockState = {
+  data: [],
+  error: null,
+};
+
+let mockState: SupabaseMockState = { ...defaultState };
+
+// =============================================================================
+// State Controls
+// =============================================================================
+
+/** Set mock data to be returned by Supabase queries */
+export function setMockSupabaseData(data: unknown[]) {
+  mockState.data = data;
+}
+
+/** Set a mock error to be returned by Supabase queries */
+export function setMockSupabaseError(error: { message: string; code: string } | null) {
+  mockState.error = error;
+}
+
+/** Reset all Supabase mocks to default state */
+export function resetSupabaseMocks() {
+  mockState = { ...defaultState };
+}
+
+// =============================================================================
+// Mock Query Builder
+// =============================================================================
+
+function createMockQueryBuilder() {
+  const resolveQuery = () => {
+    if (mockState.error) {
+      return { data: null, error: mockState.error };
+    }
+    return { data: mockState.data, error: null };
+  };
+
+  const resolveSingle = () => {
+    if (mockState.error) {
+      return { data: null, error: mockState.error };
+    }
+    return { data: mockState.data[0] ?? null, error: null };
+  };
+
+  return {
+    select: vi.fn().mockReturnThis(),
+    insert: vi.fn().mockReturnThis(),
+    update: vi.fn().mockReturnThis(),
+    delete: vi.fn().mockReturnThis(),
+    upsert: vi.fn().mockReturnThis(),
+    eq: vi.fn().mockReturnThis(),
+    neq: vi.fn().mockReturnThis(),
+    single: vi.fn().mockImplementation(() => Promise.resolve(resolveSingle())),
+    maybeSingle: vi.fn().mockImplementation(() => Promise.resolve(resolveSingle())),
+    then: (resolve: (value: { data: unknown[] | null; error: unknown }) => void) => {
+      resolve(resolveQuery());
+      return { catch: () => {} };
+    },
+  };
+}
+
+// =============================================================================
+// Mock Supabase Client
+// =============================================================================
+
+/** Create a mock Supabase client for testing */
+export function createMockSupabaseClient() {
+  return {
+    from: vi.fn().mockReturnValue(createMockQueryBuilder()),
+  };
+}
+
+// Singleton client instance for useSupabase hook (maintains referential equality)
+const mockClientInstance = createMockSupabaseClient();
+
+// =============================================================================
+// Mock Context (for vi.mock)
+// =============================================================================
+
+/** Mock SupabaseProvider - passes through children */
+export function SupabaseProvider({ children }: { children: ReactNode }) {
+  return children;
+}
+
+/** Mock useSupabase hook - returns stable client instance */
+export function useSupabase() {
+  return mockClientInstance;
+}

package/templates/src/test-setup.ts

@@ -1,7 +1,45 @@
 import '@testing-library/jest-dom/vitest';
-import { afterAll, afterEach, beforeAll } from 'vitest';
+import { afterAll, afterEach, beforeAll, vi } from 'vitest';
+
+// =============================================================================
+// Environment Variable Mock (must be mocked before any imports that use env.ts)
+// =============================================================================
+vi.mock('@/lib/env', () => ({
+  env: {
+    VITE_APP_NAME: 'My App',
+    VITE_APP_URL: 'http://localhost:5173',
+    VITE_API_URL: 'https://jsonplaceholder.typicode.com',
+    VITE_SENTRY_DSN: 'https://test@sentry.io/123',
+    VITE_SENTRY_ENABLED: false,
+    VITE_CLERK_PUBLISHABLE_KEY: 'pk_test_mock',
+    VITE_SUPABASE_DATABASE_URL: 'https://test.supabase.co',
+    VITE_SUPABASE_ANON_KEY: 'test-anon-key',
+    VITE_PERF_TEST: false,
+    MODE: 'test',
+    DEV: false,
+    PROD: false,
+  },
+  validateEnv: vi.fn(),
+}));
 
 import { server } from '@/mocks/node';
+import { resetClerkMocks } from '@/test/clerkMock';
+import { resetSupabaseMocks } from '@/test/supabaseMock';
+
+// =============================================================================
+// Module Mocks
+// =============================================================================
+
+// Mock @clerk/react-router for testing
+vi.mock('@clerk/react-router', async () => import('@/test/clerkMock'));
+
+// Mock @clerk/themes for testing
+vi.mock('@clerk/themes', () => ({
+  shadcn: { baseTheme: 'shadcn' },
+}));
+
+// Mock Supabase context with test client
+vi.mock('@/contexts/supabaseContext', async () => import('@/test/supabaseMock'));
 
 // =============================================================================
 // MSW Server Setup
@@ -14,9 +52,11 @@ beforeAll(() => {
   });
 });
 
-// Reset handlers after each test to ensure test isolation
+// Reset handlers and mocks after each test to ensure test isolation
 afterEach(() => {
   server.resetHandlers();
+  resetClerkMocks();
+  resetSupabaseMocks();
 });
 
 // Close MSW server after all tests complete

package/templates/src/types/database.ts

@@ -0,0 +1,46 @@
+/**
+ * Database type aliases and re-exports.
+ *
+ * This file provides a database-agnostic public API for type imports.
+ * The underlying types are auto-generated in supabase.ts via `npm run db:types`.
+ *
+ * Usage:
+ *   import type { Profile, ProfileInsert, ProfileUpdate } from '@/types/database';
+ *
+ * When adding new tables:
+ *   1. Run `npm run db:types` to regenerate supabase.ts
+ *   2. Add convenience aliases here for your new tables
+ */
+
+// Re-export everything from the auto-generated Supabase types
+export * from './supabase';
+
+// Re-import for creating aliases
+import type { Database, Tables, TablesInsert, TablesUpdate } from './supabase';
+
+// =============================================================================
+// Generic Table Types
+// =============================================================================
+
+/**
+ * Table names available in the database schema.
+ */
+export type TableName = keyof Database['public']['Tables'];
+
+/**
+ * Row type for a given table.
+ */
+export type TableRowType<T extends TableName> = Database['public']['Tables'][T]['Row'];
+
+// =============================================================================
+// Profile Types
+// =============================================================================
+
+/** Profile row type (read operations) */
+export type Profile = Tables<'profiles'>;
+
+/** Profile insert type (create operations) */
+export type ProfileInsert = TablesInsert<'profiles'>;
+
+/** Profile update type (update operations) */
+export type ProfileUpdate = TablesUpdate<'profiles'>;

package/templates/src/types/index.ts

@@ -1,2 +1,3 @@
 export * from './preferences';
 export * from './api';
+export * from './database';