@react-spa-scaffold/mcp 2.2.0 → 2.4.0

package/templates/docs/TESTING.md

@@ -30,7 +30,180 @@ import { screen, renderHook, act, waitFor, fireEvent } from '@testing-library/re
 import userEvent from '@testing-library/user-event';
 
 // Custom utilities from @/test
-import { render, mockMatchMedia, createTestQueryClient, server } from '@/test';
+import { render, server, mockMatchMedia, silenceConsoleError } from '@/test';
+```
+
+## Mock Infrastructure
+
+The codebase uses a unified mocking approach with shared constants and reusable utilities.
+
+### Directory Structure
+
+```
+src/test/                    # Test utilities
+├── index.ts                 # Public API - import from '@/test'
+├── clerkMock.tsx            # Clerk auth mocks
+├── supabaseMock.ts          # Supabase mocks
+├── mocks.ts                 # Browser API mocks
+└── providers.tsx            # Test render wrapper
+
+src/mocks/                   # MSW infrastructure
+├── constants.ts             # Shared test values (MOCK_USER, etc.)
+├── fixtures/                # Test data factories
+│   ├── profiles.ts          # createProfile(), mockProfiles
+│   └── todos.ts             # createTodo(), mockTodos
+├── handlers/                # MSW request handlers
+│   ├── supabase.ts          # Supabase API mocks
+│   └── todos.ts             # JSONPlaceholder mocks
+└── node.ts                  # MSW server setup
+```
+
+### Shared Constants
+
+All mocks use shared constants from `@/mocks/constants.ts` to ensure consistency:
+
+```typescript
+import { MOCK_USER, MOCK_SESSION_ID } from '@/test';
+
+// MOCK_USER.id = 'user_123'
+// MOCK_USER.email = 'test@example.com'
+// MOCK_USER.fullName = 'Test User'
+```
+
+### Clerk Mocks
+
+Control authentication state in tests:
+
+```typescript
+import { setMockClerkSignedIn, setMockClerkLoaded, resetClerkMocks } from '@/test';
+
+beforeEach(() => resetClerkMocks());
+
+it('shows sign-in when not authenticated', () => {
+  setMockClerkSignedIn(false);
+  render(<ProtectedRoute />);
+  expect(screen.getByTestId('sign-in-button')).toBeInTheDocument();
+});
+```
+
+### Supabase Mocks
+
+Control Supabase query responses:
+
+```typescript
+import { setMockSupabaseData, setMockSupabaseError, createProfile, resetSupabaseMocks } from '@/test';
+
+beforeEach(() => resetSupabaseMocks());
+
+it('displays profile data', async () => {
+  setMockSupabaseData([createProfile({ full_name: 'John Doe' })]);
+  render(<ProfileCard />);
+  await waitFor(() => expect(screen.getByText('John Doe')).toBeInTheDocument());
+});
+
+it('handles database error', async () => {
+  setMockSupabaseError({ message: 'Connection failed', code: 'NETWORK_ERROR' });
+  render(<ProfileCard />);
+  await waitFor(() => expect(screen.getByText(/error/i)).toBeInTheDocument());
+});
+```
+
+### Browser API Mocks
+
+Reusable mocks for common browser APIs:
+
+```typescript
+import { mockMatchMedia, mockScrollTo, mockAnimationFrame, silenceConsoleError, silenceConsoleWarn } from '@/test';
+
+// Media queries
+beforeEach(() => {
+  window.matchMedia = mockMatchMedia(true); // matches
+});
+
+// Scroll behavior
+it('scrolls to top', () => {
+  const scrollSpy = mockScrollTo();
+  triggerScroll();
+  expect(scrollSpy).toHaveBeenCalledWith(0, 0);
+});
+
+// Animation frames
+let getCallback: () => FrameRequestCallback | null;
+beforeEach(() => {
+  getCallback = mockAnimationFrame();
+});
+
+it('updates on animation frame', () => {
+  const callback = getCallback();
+  act(() => callback?.(0));
+  // assert state change
+});
+
+// Silence console during error tests
+it('handles error gracefully', () => {
+  const spy = silenceConsoleError();
+  triggerError();
+  expect(handleError).toHaveBeenCalled();
+  spy.mockRestore();
+});
+```
+
+### Fetch Mocking
+
+Use `vi.spyOn` for type-safe fetch mocking:
+
+```typescript
+beforeEach(() => {
+  vi.spyOn(global, 'fetch');
+});
+
+afterEach(() => {
+  vi.restoreAllMocks();
+});
+
+it('handles API response', async () => {
+  vi.mocked(global.fetch).mockResolvedValueOnce({
+    ok: true,
+    status: 200,
+    json: () => Promise.resolve({ data: 'test' }),
+  } as Response);
+
+  const result = await fetchData();
+  expect(result.data).toBe('test');
+});
+```
+
+### MSW (Mock Service Worker)
+
+MSW handlers intercept HTTP requests. Override per-test:
+
+```typescript
+import { http, HttpResponse } from 'msw';
+import { server } from '@/test';
+
+it('handles API error', async () => {
+  server.use(http.get('/api/todos', () => new HttpResponse(null, { status: 500 })));
+  // Test error handling...
+});
+```
+
+MSW handlers auto-reset after each test via `src/test-setup.ts`.
+
+### Test Data Factories
+
+Use factories to create test data with sensible defaults:
+
+```typescript
+import { createProfile, createTodo } from '@/test';
+
+// Override specific fields
+const profile = createProfile({ full_name: 'Custom Name' });
+const todo = createTodo({ completed: true });
+
+// Create multiple
+import { createProfiles, createTodos } from '@/mocks/fixtures';
+const profiles = createProfiles(5);
+const todos = createTodos(10, { userId: 1 });
 ```
 
 ## Core Patterns
@@ -50,25 +223,6 @@ it.each([
 // ❌ Avoid - repetitive individual tests
 it('formats 0 bytes', () => expect(formatBytes(0)).toBe('0 Bytes'));
 it('formats 1024 bytes', () => expect(formatBytes(1024)).toBe('1 KB'));
-it('formats 1MB', () => expect(formatBytes(1024 * 1024)).toBe('1 MB'));
-```
-
-### Use Shared Mocks
-
-```typescript
-import { mockMatchMedia } from '@/test';
-
-describe('useMediaQuery', () => {
-  beforeEach(() => {
-    window.matchMedia = mockMatchMedia(false);
-  });
-
-  it('detects desktop viewport', () => {
-    window.matchMedia = mockMatchMedia(true); // matches min-width query
-    const { result } = renderHook(() => useIsDesktop());
-    expect(result.current).toBe(true);
-  });
-});
 ```
 
 ### Component Testing
@@ -120,61 +274,6 @@ it('updates after async action', async () => {
 });
 ```
 
-### Mocking
-
-```typescript
-import { mockMatchMedia } from '@/test';
-
-// Mock modules at top of file
-vi.mock('@/lib/storage', () => ({
-  setStorageItem: vi.fn(() => true),
-}));
-
-// Mock browser APIs using shared utilities
-beforeEach(() => {
-  window.matchMedia = mockMatchMedia(false);
-});
-
-afterEach(() => {
-  vi.restoreAllMocks();
-});
-
-// Mock fetch for API tests
-const mockFetch = vi.fn();
-beforeEach(() => {
-  global.fetch = mockFetch;
-});
-mockFetch.mockResolvedValueOnce({ ok: true, json: () => Promise.resolve({}) });
-```
-
-### MSW (Mock Service Worker)
-
-MSW handlers are organized in `src/mocks/`:
-
-```
-src/mocks/
-├── handlers/
-│   ├── index.ts     # Combines all handlers
-│   └── todos.ts     # Example domain handlers
-├── fixtures/
-│   └── todos.ts     # Response data
-├── browser.ts       # Browser worker setup
-└── node.ts          # Node server for tests
-```
-
-Override handlers per-test:
-
-```typescript
-import { http, HttpResponse, server } from '@/test';
-
-it('handles API error', async () => {
-  server.use(http.get('/api/todos', () => new HttpResponse(null, { status: 500 })));
-  // Test error handling...
-});
-```
-
-MSW handlers auto-reset after each test via `src/test-setup.ts`.
-
 ### Store Testing (Zustand)
 
 ```typescript
@@ -192,6 +291,24 @@ describe('preferencesStore', () => {
 });
 ```
 
+## Mock Best Practices
+
+### DO
+
+- ✅ Use shared constants (`MOCK_USER`, etc.) for consistency
+- ✅ Use `vi.spyOn()` for type-safe mocking
+- ✅ Use `vi.mocked()` wrapper for TypeScript support
+- ✅ Reset mocks in `beforeEach`/`afterEach`
+- ✅ Restore mocks after silencing console
+- ✅ Use factory functions for test data
+
+### DON'T
+
+- ❌ Hardcode user IDs or emails across files
+- ❌ Use `global.fetch = mockFn` (use `vi.spyOn` instead)
+- ❌ Create duplicate mock utilities in test files
+- ❌ Forget to reset stateful mocks between tests
+
 ## Test Organization
 
 ### Structure Within Test Files
@@ -239,9 +356,10 @@ npm run test:ui       # Visual UI
 ## Checklist for New Tests
 
 - [ ] File follows `[name].test.ts(x)` naming
+- [ ] Uses shared mocks from `@/test`
+- [ ] Uses shared constants (`MOCK_USER`, etc.)
 - [ ] Uses `it.each` for parameterized cases
-- [ ] Mocks are cleared in `beforeEach`/`afterEach`
-- [ ] No duplicate helper functions
+- [ ] Mocks are reset in `beforeEach`/`afterEach`
 - [ ] Tests behavior, not implementation
 - [ ] Async tests use `await`/`waitFor` properly
 - [ ] Coverage threshold maintained (80%)

package/templates/e2e/auth/auth.setup.ts

@@ -0,0 +1,60 @@
+import { clerk, clerkSetup } from '@clerk/testing/playwright';
+import { expect, test as setup } from '@playwright/test';
+
+import { ASYNC_CONTENT_TIMEOUT, AUTH_STATE_FILE } from '../fixtures';
+
+// Setup must be run serially for Clerk initialization
+setup.describe.configure({ mode: 'serial' });
+
+/**
+ * Configure Playwright with Clerk testing token.
+ * This obtains a Testing Token when the test suite starts.
+ *
+ * Required: CLERK_SECRET_KEY environment variable
+ */
+setup('global setup', async () => {
+  // Skip if CLERK_SECRET_KEY is not set
+  if (!process.env.CLERK_SECRET_KEY) {
+    setup.skip(true, 'CLERK_SECRET_KEY required for authenticated tests');
+    return;
+  }
+  await clerkSetup();
+});
+
+/**
+ * Authenticate and save state to storage.
+ * This creates a reusable auth state for authenticated tests.
+ *
+ * Required environment variables:
+ * - E2E_CLERK_USER_USERNAME: Test user email
+ * - E2E_CLERK_USER_PASSWORD: Test user password
+ */
+setup('authenticate and save state', async ({ page }) => {
+  const username = process.env.E2E_CLERK_USER_USERNAME;
+  const password = process.env.E2E_CLERK_USER_PASSWORD;
+
+  // Skip auth setup if credentials are not provided
+  if (!username || !password) {
+    setup.skip(true, 'E2E_CLERK_USER_USERNAME and E2E_CLERK_USER_PASSWORD required for authenticated tests');
+    return;
+  }
+
+  // Navigate to app and sign in
+  await page.goto('/');
+
+  await clerk.signIn({
+    page,
+    signInParams: {
+      strategy: 'password',
+      identifier: username,
+      password: password,
+    },
+  });
+
+  // Verify authentication succeeded by checking for authenticated UI
+  await page.goto('/profile');
+  await expect(page.getByText('Your Profile')).toBeVisible({ timeout: ASYNC_CONTENT_TIMEOUT });
+
+  // Save authentication state for reuse in other tests
+  await page.context().storageState({ path: AUTH_STATE_FILE });
+});

package/templates/e2e/fixtures/index.ts

@@ -1,4 +1,15 @@
 import type { Page } from '@playwright/test';
+import { dirname, join } from 'path';
+import { fileURLToPath } from 'url';
+
+// ESM-compatible path resolution
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+/** Path to Clerk auth state file for authenticated tests */
+export const AUTH_STATE_FILE = join(__dirname, '../.clerk/user.json');
+
+/** Default timeout for waiting on profile/async content to load */
+export const ASYNC_CONTENT_TIMEOUT = 10000;
 
 /**
  * Navigate to page with clean state (clears localStorage).

package/templates/e2e/tests/profile.auth.spec.ts

@@ -0,0 +1,103 @@
+import { expect, test } from '@playwright/test';
+
+import { ASYNC_CONTENT_TIMEOUT } from '../fixtures';
+
+// Check if auth credentials are configured
+const hasAuthCredentials = !!(
+  process.env.CLERK_SECRET_KEY &&
+  process.env.E2E_CLERK_USER_USERNAME &&
+  process.env.E2E_CLERK_USER_PASSWORD
+);
+
+/**
+ * Authenticated Profile Page E2E Tests
+ *
+ * These tests run with an authenticated user (from auth.setup.ts).
+ * They test the full profile CRUD flow with Supabase integration.
+ *
+ * Required environment variables:
+ * - E2E_CLERK_USER_USERNAME: Test user email
+ * - E2E_CLERK_USER_PASSWORD: Test user password
+ * - CLERK_SECRET_KEY: Clerk secret key for testing
+ *
+ * @see https://clerk.com/docs/testing/playwright
+ */
+test.describe('Authenticated Profile Tests', () => {
+  // Skip all tests if auth credentials aren't configured
+  test.skip(
+    !hasAuthCredentials,
+    'Auth credentials required (CLERK_SECRET_KEY, E2E_CLERK_USER_USERNAME, E2E_CLERK_USER_PASSWORD)',
+  );
+
+  test.beforeEach(async ({ page }) => {
+    await page.goto('/profile');
+    // Wait for profile content to load (semantic selector instead of CSS class)
+    await expect(page.getByText('Full Name')).toBeVisible({ timeout: ASYNC_CONTENT_TIMEOUT });
+  });
+
+  test('displays profile card with user info', async ({ page }) => {
+    await expect(page.getByText('Your Profile')).toBeVisible();
+    await expect(page.getByText('Manage your profile information stored in Supabase')).toBeVisible();
+  });
+
+  test('shows user email in profile', async ({ page }) => {
+    const email = process.env.E2E_CLERK_USER_USERNAME;
+    if (email) {
+      await expect(page.getByText(email)).toBeVisible();
+    }
+  });
+
+  test('can enter edit mode for name', async ({ page }) => {
+    await page.getByRole('button', { name: /edit/i }).click();
+
+    // Input field should appear
+    await expect(page.getByRole('textbox')).toBeVisible();
+
+    // Save and Cancel buttons should be visible
+    await expect(page.getByRole('button', { name: /save/i })).toBeVisible();
+    await expect(page.getByRole('button', { name: /cancel/i })).toBeVisible();
+  });
+
+  test('can cancel edit without saving', async ({ page }) => {
+    // Enter edit mode
+    await page.getByRole('button', { name: /edit/i }).click();
+
+    // Type a new name
+    const input = page.getByRole('textbox');
+    await input.clear();
+    await input.fill('Temporary Name');
+
+    // Cancel
+    await page.getByRole('button', { name: /cancel/i }).click();
+
+    // Should exit edit mode (input gone, edit button back)
+    await expect(input).not.toBeVisible();
+    await expect(page.getByRole('button', { name: /edit/i })).toBeVisible();
+  });
+
+  test('can update profile name', async ({ page }) => {
+    // Enter edit mode
+    await page.getByRole('button', { name: /edit/i }).click();
+
+    // Generate unique name with timestamp
+    const newName = `E2E Test User ${Date.now()}`;
+
+    // Update name
+    const input = page.getByRole('textbox');
+    await input.clear();
+    await input.fill(newName);
+
+    // Save
+    await page.getByRole('button', { name: /save/i }).click();
+
+    // Wait for save to complete (exit edit mode)
+    await expect(page.getByRole('button', { name: /edit/i })).toBeVisible({ timeout: ASYNC_CONTENT_TIMEOUT });
+
+    // Verify name is displayed
+    await expect(page.getByText(newName)).toBeVisible();
+  });
+
+  test('Full Name label is present', async ({ page }) => {
+    await expect(page.getByText('Full Name')).toBeVisible();
+  });
+});

package/templates/e2e/tests/profile.spec.ts

@@ -0,0 +1,64 @@
+import { expect, test } from '@playwright/test';
+
+/**
+ * Profile Page E2E Tests
+ *
+ * Note: These tests require a valid Clerk configuration to run.
+ * Without VITE_CLERK_PUBLISHABLE_KEY, the app may show an error page.
+ *
+ * For authenticated testing, see @clerk/testing package documentation.
+ * @see https://clerk.com/docs/testing/playwright
+ */
+
+test.describe('Profile Page', () => {
+  test.beforeEach(async ({ page }) => {
+    // Check if the app loads (Clerk needs to be configured)
+    await page.goto('/');
+
+    // Wait for app to be ready (header should be visible if Clerk is configured)
+    const header = page.getByRole('banner');
+    const isAppReady = await header.isVisible({ timeout: 5000 }).catch(() => false);
+
+    if (!isAppReady) {
+      test.skip(true, 'App not ready - Clerk may not be configured');
+    }
+  });
+
+  test('protected route blocks unauthenticated access', async ({ page }) => {
+    await page.goto('/profile');
+
+    // Wait for Clerk to process the route
+    await page.waitForTimeout(3000);
+
+    // Profile content should NOT be visible without authentication
+    const profileCard = page.getByText('Your Profile');
+    const isVisible = await profileCard.isVisible().catch(() => false);
+
+    // Should either redirect or show sign-in UI, but NOT show profile
+    expect(isVisible).toBe(false);
+  });
+
+  test('profile link only visible when authenticated', async ({ page }) => {
+    await page.goto('/');
+
+    // Wait for Clerk to initialize
+    await page.waitForTimeout(2000);
+
+    // Check for Profile link/button in header
+    // This is wrapped in <SignedIn>, so it should only appear for authenticated users
+    const profileButton = page.getByRole('button', { name: /profile/i });
+    const profileLink = page.getByRole('link', { name: /profile/i });
+
+    const buttonVisible = await profileButton.isVisible().catch(() => false);
+    const linkVisible = await profileLink.isVisible().catch(() => false);
+
+    // Without authentication, neither should be visible
+    // (unless user happens to be authenticated, which is also valid)
+    expect(buttonVisible || linkVisible).toBe(false);
+  });
+});
+
+/**
+ * @see profile.auth.spec.ts for authenticated profile tests (edit, update, etc.)
+ * @see https://clerk.com/docs/testing/playwright
+ */

package/templates/e2e/tests/register-form.spec.ts

@@ -0,0 +1,38 @@
+import { expect, test } from '@playwright/test';
+
+test.describe('Registration Form', () => {
+  test.beforeEach(async ({ page }) => {
+    await page.goto('/');
+  });
+
+  test('displays registration form with all fields', async ({ page }) => {
+    await expect(page.getByLabel(/username/i)).toBeVisible();
+    await expect(page.getByLabel(/email/i)).toBeVisible();
+    await expect(page.getByLabel('Password', { exact: true })).toBeVisible();
+    await expect(page.getByLabel(/confirm password/i)).toBeVisible();
+    await expect(page.getByRole('button', { name: /create account/i })).toBeVisible();
+  });
+
+  test('shows validation errors for empty submission', async ({ page }) => {
+    await page.getByRole('button', { name: /create account/i }).click();
+
+    await expect(page.getByText(/username must be at least/i)).toBeVisible();
+    await expect(page.getByText(/valid email address/i)).toBeVisible();
+    await expect(page.getByText(/password must be at least/i)).toBeVisible();
+  });
+
+  test('validates password requirements', async ({ page }) => {
+    await page.getByLabel('Password', { exact: true }).fill('weak');
+    await page.getByRole('button', { name: /create account/i }).click();
+
+    await expect(page.getByText(/password must be at least 8 characters/i)).toBeVisible();
+  });
+
+  test('validates password confirmation match', async ({ page }) => {
+    await page.getByLabel('Password', { exact: true }).fill('StrongPass1');
+    await page.getByLabel(/confirm password/i).fill('DifferentPass1');
+    await page.getByRole('button', { name: /create account/i }).click();
+
+    await expect(page.getByText(/passwords don't match/i)).toBeVisible();
+  });
+});

package/templates/forge.config.js

@@ -0,0 +1,53 @@
+// @ts-check
+
+/** @type {import('@electron-forge/shared-types').ForgeConfig} */
+const config = {
+  packagerConfig: {
+    name: 'ReactSPAScaffold',
+    appBundleId: 'com.example.react-spa-scaffold',
+    // No code signing for internal/dev use
+    osxSign: undefined,
+    osxNotarize: undefined,
+  },
+  rebuildConfig: {},
+  makers: [
+    {
+      name: '@electron-forge/maker-zip',
+      platforms: ['darwin'],
+    },
+    {
+      name: '@electron-forge/maker-dmg',
+      config: {
+        format: 'ULFO',
+        name: 'ReactSPAScaffold',
+      },
+    },
+  ],
+  plugins: [
+    {
+      name: '@electron-forge/plugin-vite',
+      config: {
+        build: [
+          {
+            entry: 'src/main.ts',
+            config: 'vite.main.config.mjs',
+            target: 'main',
+          },
+          {
+            entry: 'src/preload.ts',
+            config: 'vite.preload.config.mjs',
+            target: 'preload',
+          },
+        ],
+        renderer: [
+          {
+            name: 'main_window',
+            config: 'vite.renderer.config.mjs',
+          },
+        ],
+      },
+    },
+  ],
+};
+
+export default config;

package/templates/gitignore

@@ -23,10 +23,15 @@ coverage/
 playwright-report/
 test-results/
 playwright/.cache/
+e2e/.clerk/*
+!e2e/.clerk/.gitkeep
 
 # i18n compiled catalogs (generated by Vite plugin during build)
 src/locales/*.mjs
 
+# Supabase
+supabase/.temp/
+
 # Misc
 tmp
 *.log