test fixes and doc work

docs/development/ERROR-LOGGING-PATHS.md

@@ -147,6 +147,7 @@ When creating new route handlers:
 ## Related Documentation
 
 - [ADR-008: API Versioning Strategy](../adr/0008-api-versioning-strategy.md) - Versioning implementation details
+- [ADR-057: Test Remediation Post-API Versioning](../adr/0057-test-remediation-post-api-versioning.md) - Comprehensive remediation guide
 - [ADR-004: Structured Logging](../adr/0004-standardized-application-wide-structured-logging.md) - Logging standards
 - [CODE-PATTERNS.md](CODE-PATTERNS.md) - General code patterns
 - [TESTING.md](TESTING.md) - Testing guidelines

docs/development/TESTING.md

@@ -262,6 +262,8 @@ Opens a browser-based test runner with filtering and debugging capabilities.
 6. **Use unique filenames** - file upload tests need timestamp-based filenames
 7. **Check exit codes** - `npm run type-check` returns 0 on success, non-zero on error
 8. **Use `req.originalUrl` in error logs** - never hardcode API paths in error messages
+9. **Use versioned API paths** - always use `/api/v1/` prefix in test requests
+10. **Use `vi.hoisted()` for module mocks** - ensure mocks are available during module initialization
 
 ## Testing Error Log Messages
 
@@ -314,3 +316,159 @@ expect(logSpy).toHaveBeenCalledWith(
 ```
 
 See [Error Logging Path Patterns](ERROR-LOGGING-PATHS.md) for complete documentation.
+
+## API Versioning in Tests (ADR-008, ADR-057)
+
+All API endpoints use the `/api/v1/` prefix. Tests must use versioned paths.
+
+### Configuration
+
+API base URLs are configured centrally in Vitest config files:
+
+| Config File                    | Environment Variable | Value                          |
+| ------------------------------ | -------------------- | ------------------------------ |
+| `vite.config.ts`               | `VITE_API_BASE_URL`  | `/api/v1`                      |
+| `vitest.config.e2e.ts`         | `VITE_API_BASE_URL`  | `http://localhost:3098/api/v1` |
+| `vitest.config.integration.ts` | `VITE_API_BASE_URL`  | `http://localhost:3099/api/v1` |
+
+### Writing API Tests
+
+```typescript
+// Good - versioned path
+const response = await request.post('/api/v1/auth/login').send({...});
+
+// Bad - unversioned path (will fail)
+const response = await request.post('/api/auth/login').send({...});
+```
+
+### Migration Checklist
+
+When API version changes (e.g., v1 to v2):
+
+1. Update all Vitest config `VITE_API_BASE_URL` values
+2. Search and replace API paths in E2E tests: `grep -r "/api/v1/" src/tests/e2e/`
+3. Search and replace API paths in integration tests
+4. Verify route handler error logs use `req.originalUrl`
+5. Run full test suite in dev container
+
+See [ADR-057](../adr/0057-test-remediation-post-api-versioning.md) for complete migration guidance.
+
+## vi.hoisted() Pattern for Module Mocks
+
+When mocking modules that are imported at module initialization time (like queues or database connections), use `vi.hoisted()` to ensure mocks are available during hoisting.
+
+### Problem: Mock Not Available During Import
+
+```typescript
+// BAD: Mock might not be ready when module imports it
+vi.mock('../services/queues.server', () => ({
+  flyerQueue: { getJobCounts: vi.fn() }, // May not exist yet
+}));
+
+import healthRouter from './health.routes'; // Imports queues.server
+```
+
+### Solution: Use vi.hoisted()
+
+```typescript
+// GOOD: Mocks are created during hoisting, before vi.mock runs
+const { mockQueuesModule } = vi.hoisted(() => {
+  const createMockQueue = () => ({
+    getJobCounts: vi.fn().mockResolvedValue({
+      waiting: 0,
+      active: 0,
+      failed: 0,
+      delayed: 0,
+    }),
+  });
+
+  return {
+    mockQueuesModule: {
+      flyerQueue: createMockQueue(),
+      emailQueue: createMockQueue(),
+      // ... additional queues
+    },
+  };
+});
+
+// Now the mock object exists when vi.mock factory runs
+vi.mock('../services/queues.server', () => mockQueuesModule);
+
+// Safe to import after mocks are defined
+import healthRouter from './health.routes';
+```
+
+See [ADR-057](../adr/0057-test-remediation-post-api-versioning.md) for additional patterns.
+
+## Testing Role-Based Component Visibility
+
+When testing components that render differently based on user roles:
+
+### Pattern: Separate Test Cases by Role
+
+```typescript
+describe('for authenticated users', () => {
+  beforeEach(() => {
+    mockedUseAuth.mockReturnValue({
+      authStatus: 'AUTHENTICATED',
+      userProfile: createMockUserProfile({ role: 'user' }),
+    });
+  });
+
+  it('renders user-accessible components', () => {
+    render(<MyComponent />);
+    expect(screen.getByTestId('user-component')).toBeInTheDocument();
+    // Admin-only should NOT be present
+    expect(screen.queryByTestId('admin-only')).not.toBeInTheDocument();
+  });
+});
+
+describe('for admin users', () => {
+  beforeEach(() => {
+    mockedUseAuth.mockReturnValue({
+      authStatus: 'AUTHENTICATED',
+      userProfile: createMockUserProfile({ role: 'admin' }),
+    });
+  });
+
+  it('renders admin-only components', () => {
+    render(<MyComponent />);
+    expect(screen.getByTestId('admin-only')).toBeInTheDocument();
+  });
+});
+```
+
+### Key Points
+
+1. Create separate `describe` blocks for each role
+2. Set up role-specific mocks in `beforeEach`
+3. Test both presence AND absence of role-gated components
+4. Use `screen.queryByTestId()` for elements that should NOT exist
+
+## CSS Class Assertions After UI Refactors
+
+After frontend style changes, update test assertions to match new CSS classes.
+
+### Handling Tailwind Class Changes
+
+```typescript
+// Before refactor
+expect(selectedItem).toHaveClass('ring-2', 'ring-brand-primary');
+
+// After refactor - update to new classes
+expect(selectedItem).toHaveClass('border-brand-primary', 'bg-teal-50/50');
+```
+
+### Flexible Matching
+
+For complex class combinations, consider partial matching:
+
+```typescript
+// Check for key classes, ignore utility classes
+expect(element).toHaveClass('border-brand-primary');
+
+// Or use regex for patterns
+expect(element.className).toMatch(/dark:bg-teal-\d+/);
+```
+
+See [ADR-057](../adr/0057-test-remediation-post-api-versioning.md) for lessons learned from the test remediation effort.